Uploaded Files API

These operations allow you to manage files uploaded by participants.

Contents

Query Uploaded Files
Get Download URL
Upload File
Delete File

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

The category used to group related files.

files[n].fileName string

The name of the uploaded file.

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_record.png",
            "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_record.png",
            "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_record.png

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_record.png?Expires=1715527513&various-access-credentials..."
}
  {
  "preSignedUrl": "https://your-presigned-secure-image-url/58b331cc-50ee-460b-8e7e-871e08867687/image/2024-03-14T17:26:43.526Z_record.png?Expires=1715527513&various-access-credentials..."
}

Upload File

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

Uploads a file. This must be done in two steps:

Use this operation to post the file metadata. The response will contain a pre-signed, time-limited URL granting access to an S3 bucket.
Use a separate PUT operation to upload the file contents to the URL.

Limitations:

The maximum file size is 200MB.
Only images, PDFs, audio files, and video files are allowed.

Body Parameters

participantIdentifier string

Project-set, unique participant identifier. Either participantIdentifier or participantID is required.

participantID

Internal, stable, unique ID for the participant. Either participantIdentifier or participantID is required.

category string (required)

The category used to group related files. May only contain alphanumeric characters and limited symbols: dot (.), dash (-), and underscore (_).

fileName string (required)

A fileName to use when storing the uploaded file. May only contain alphanumeric characters and limited symbols: dot (.), dash (-), and underscore (_).

Response Fields

preSignedUrl string

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

Sample Data

        {
        "participantID": "58b331cc-50ee-460b-8e7e-871e08867687",
        "participantIdentifier": "PT-123",
        "category": "images",
        "fileName": "record.png"
    }
      {
        "participantID": "58b331cc-50ee-460b-8e7e-871e08867687",
        "participantIdentifier": "PT-123",
        "category": "images",
        "fileName": "record.png"
    }

Sample Response

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

Example Code

          url = `/api/v1/administration/projects/${mdhProjectId}/files`;
      response = await postToApi(serviceAccessToken, url, {}, { participantIdentifier: "PT-123", category: "image", fileName: "record.png" });
      const preSignedUrl = response.data.preSignedUrl;

      fs.readFile("./record.png", (err, data) => {
        fetch(preSignedUrl, {
            method: 'PUT',
            body: data,
            headers: {
                'Content-Type': 'image/png',
                'x-amz-server-side-encryption': 'AES256'
            }
        }).then(res => console.log(res));    
      });
        url = `/api/v1/administration/projects/${mdhProjectId}/files`;
      response = await postToApi(serviceAccessToken, url, {}, { participantIdentifier: "PT-123", category: "image", fileName: "record.png" });
      const preSignedUrl = response.data.preSignedUrl;

      fs.readFile("./record.png", (err, data) => {
        fetch(preSignedUrl, {
            method: 'PUT',
            body: data,
            headers: {
                'Content-Type': 'image/png',
                'x-amz-server-side-encryption': 'AES256'
            }
        }).then(res => console.log(res));    
      });

Delete File

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

Deletes a previously uploaded file.

Warning
This cannot be undone.

Query Parameters

key string (required)

The primary key identifying the file.