Uploaded Files API

These operations allow you to manage files uploaded by participants.

Contents

Query Uploaded Files
Get Download URL

Query Uploaded Files

GET api/v1/administration/projects/:projectID/files

Queries the file store for uploaded files. There are several ways to query:

To get files for all participants - Omit the participantID, participantIdentifier and category parameters.
To get all files for a single participant - Specify either participantID or participantIdentifier.
To get files of a specific type for a single participant - Specify category and either a participantID or participantIdentifier.

Querying for files of a specific type across all participants is not currently supported.

Query Parameters

participantID guid

Search for files for a participant based on the participant’s internal, stable, unique ID field.

participantIdentifier string

Search for files for a participant based on the project-set, unique participant identifier.

category string

Queries files with the specified category.

uploadedAfter date

Queries files uploaded after this date.

uploadedBefore date

Queries files uploaded before this date.

limit int

How many entries to include in each page of results. Default and maximum is 100.

pageID string

Each page of results will return a nextPageID if there are additional pages that can be queried. Supply that as pageID to query the next page. When excluded, retrieves the first page.

Response Fields

files collection

A list files filtered by the query parameters.

Element Fields

files[n].key string

A primary key used to identify the file.

files[n].participantIdentifier string

Project-set, unique participant identifier.

files[n].participantID

Internal, stable, unique ID for the participant.

files[n].category string

An optional category used to group related files.

files[n].lastModified date

Date when the file was last modified, in ISO8601 format.

nextPageID string

An ID to be used with subsequent queries. Results from queries using this ID as the pageID parameter will show the next page of results. This field is null if there isn’t a next page.

    Sample Response 
    
  

    {
    "files": [
        {
            "participantID": "58b331cc-50ee-460b-8e7e-871e08867687",
            "participantIdentifier": "PT-123",
            "key": "58b331cc-50ee-460b-8e7e-871e08867687/images/2024-05-12T14:16:36.244Z_Kitty.jpg",
            "category": "images",
            "lastModified": "2024-05-12T10:16:37-04:00"
        },
        {
            "participantID": "58b331cc-50ee-460b-8e7e-871e08867687",
            "participantIdentifier": "PT-123",
            "key": "58b331cc-50ee-460b-8e7e-871e08867687/files/2024-05-12T14:51:30.569Z_Llama.jpg",
            "category": "workout-videos",
            "lastModified": "2024-05-12T10:51:32-04:00"
        },
        ...
    ],
    "nextPageID": "A8MAqb65R6Ezx7NdzcND"
}
  {
    "files": [
        {
            "participantID": "58b331cc-50ee-460b-8e7e-871e08867687",
            "participantIdentifier": "PT-123",
            "key": "58b331cc-50ee-460b-8e7e-871e08867687/images/2024-05-12T14:16:36.244Z_Kitty.jpg",
            "category": "images",
            "lastModified": "2024-05-12T10:16:37-04:00"
        },
        {
            "participantID": "58b331cc-50ee-460b-8e7e-871e08867687",
            "participantIdentifier": "PT-123",
            "key": "58b331cc-50ee-460b-8e7e-871e08867687/files/2024-05-12T14:51:30.569Z_Llama.jpg",
            "category": "workout-videos",
            "lastModified": "2024-05-12T10:51:32-04:00"
        },
        ...
    ],
    "nextPageID": "A8MAqb65R6Ezx7NdzcND"
}

Get Download URL

GET api/v1/administration/projects/:projectID/files/download?key=58b331cc-50ee-460b-8e7e-871e08867687/image/2024-03-14T17:26:43.526Z_kitty.jpg

Returns a pre-signed URL that allows secure, time-limited access to download a file from the file store. This URL includes query parameters that provide the credentials necessary to download the file. The time the URL expires is embedded in the URL in the Expires query parameter.

Query Parameters

key string (required)

The primary key identifying the file.

Response Fields

preSignedUrl string

A pre-signed URL offering secure, time-limited access to the file. The time the URL expires is embedded in the URL. The time the URL expires is embedded in the URL.

    Sample Response 
    
  

    {
  "preSignedUrl": "https://your-presigned-secure-image-url/58b331cc-50ee-460b-8e7e-871e08867687/image/2024-03-14T17:26:43.526Z_kitty.jpg?Expires=1715527513&various-access-credentials..."
}
  {
  "preSignedUrl": "https://your-presigned-secure-image-url/58b331cc-50ee-460b-8e7e-871e08867687/image/2024-03-14T17:26:43.526Z_kitty.jpg?Expires=1715527513&various-access-credentials..."
}