Skip to main content

Managing Files

The TANGO API provides a secure and scalable way to manage files used as inputs or outputs for your models. To ensure security and high performance with large files, TANGO uses a two-step transfer process for both uploads and downloads.

This guide provides the full API reference for all file operations.

The Two-Step Transfer Process​

Instead of sending a large file directly through the main API server, the process is split into two phases:

  1. Request Access: Your application first asks the TANGO API for permission to perform a transfer (upload or download).
  2. Perform Transfer: The API provides a unique ID for the transfer session. You then use this ID to send (or receive) the file data.

This method is common in modern cloud platforms and provides a more robust and secure experience.

Uploading a File​

Uploading a file is a two-step process. First, you declare your intent to upload, and then you send the file's content.

note

Files are stored persistently in the blob storage configured in the workspace and owners can download them at any time. To remove a file, owners can issue a delete request, which permanently removes the file from storage and deletes its metadata.

Step 1: Request an Upload​

Before uploading a file, you must inform TANGO about it to get a unique uploadId for the transfer session.

POST storage/{storage_key}/files/request_upload​

This endpoint initiates the file upload process by generating a unique upload session ID.

  • Security: Requires bearerAuth.
Request Body​

You must provide metadata about the file you intend to upload.

AttributeTypeRequiredDescription
file_namestringYesThe original name of the file (e.g., "patient-scan.dcm").

Example Request:

{
  "file_name": "patient-mri-scan.dcm",
}
Response​

If successful, the API returns an upload_id and an upload_url. The upload_id acts first as a temporary session key and later becomes the permanent file_id once the upload completes. The upload_url is generated within the TANGO infrastructure to manage the file transfer. To upload the file data, the user can either:

  • send it directly to the provided upload_url,
  • call the TANGO API proxy with the upload_id.
{
  "upload_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "upload_url": "https://storage.example.com/upload/d290f1ee-6c54-4b01-90e6-d701748f0851"
}

Step 2: Send the File Content​

Now, use the upload_id from the previous step to send the actual file data.

POST storage/{storage_key}/files/proxy_upload/{upload_id}​

This endpoint accepts the file content and streams it to the secure storage location. The request must be multipart/form-data.

  • Security: Requires bearerAuth.
Request Body​
AttributeTypeRequiredDescription
filebinaryYesThe raw file data.
Response​

A successful upload will result in a 200 OK response with a confirmation message.

{
  "file_id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}

Listing and Viewing Files​

Once files are uploaded, you can retrieve their metadata.

List All Accessible Files​

GET storage/{storage_key}/files​

Retrieves a list of metadata for all files your user has access to within the workspace.

  • Security: Requires bearerAuth.
Response​

Returns an array of FileMetadata objects.

[
  {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "storage_key": "primary-azure-eu-west",
    "user_id": "user-123",
    "workspace": "research-project-alpha",
    "data_uri": "data://tango-storage/d290f1ee-6c54-4b01-90e6-d701748f0851.dcm",
    "file_name": "patient-mri-scan.dcm",
    "download_count": 42
  }
]

Get Metadata for a Specific File​

GET storage/{storage_key}/files/{file_id}​

Retrieves the metadata for a single file, given its unique identifier.

  • Security: Requires bearerAuth.

Downloading a File​

Downloading a file is also a two-step process, similar to uploading.

Step 1: Request a Download​

First, request permission to download a file to receive a unique download_id.

GET storage/{storage_key}/files/{file_id}/request_download​

Initiates a secure file download session for the specified file_id.

  • Security: Requires bearerAuth.
Response​

If successful, the API returns a download_id and a download_url. The download_id acts as a temporary session key to be used in the next step, while the download_url is generated within the TANGO infrastructure to manage the file transfer. To download the file data, the user can either:

  • request it directly to the provided download_url,
  • call the TANGO API proxy with the download_id.
{
  "download_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "download_url": "https://storage.example.com/download/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}

Step 2: Retrieve the File Content​

Use the download_id to stream the file content through the API.

GET storage/{storage_key}/files/proxy_download/{download_id}​

This endpoint takes the download_id and returns the raw binary data of the file.

  • Security: Requires bearerAuth.
Response​

A successful request will stream the file's content with a 200 OK status and a content type of application/octet-stream.

Deleting a File​

DELETE storage/{storage_key}/files/{file_id}​

Permanently deletes a file's metadata record and the corresponding file from storage. This action is irreversible.

  • Security: Requires bearerAuth.
Response​

A successful deletion will result in a 204 No Content response.