Files

The Files API gives code access to the same saved workspace files used in the web app. Use it to upload inputs once, list reusable files, pass a file reference into POST /api/v1/jobs, and delete files your key is allowed to manage.

Basic concepts

File

A file is a saved workspace asset with a stable id, filename, format, MIME type, size, origin, and timestamps. API responses do not include internal storage keys, workspace ids, or uploader ids.

Origin

origin describes how the file entered the workspace:

• UPLOAD: Uploaded directly to Files
• JOB_OUTPUT: Saved from a completed job result
• JOB_INPUT: Saved from persisted job input
• IMPORT: Imported from a supported database or dataset source

Storage owner

storage_owner describes deletion behavior:

• FILE_LIBRARY: The saved file owns its stored object. Deleting the file also removes the stored object.
• JOB_ARTIFACT: The saved file points at an existing job artifact. Deleting the file removes the saved file record, not the original job artifact.

List files

Use GET /api/v1/files to list files in the API key workspace. The endpoint requires the files:read scope.

curl -s \
  -H "Authorization: Bearer $PROTEINIQ_API_KEY" \
  "https://proteiniq.io/api/v1/files?limit=20&format=PDB"

Supported query parameters:

• limit: Integer from 1 to 100, defaults to 20
• starting_after: Cursor returned as next_cursor from a previous page
• q: Search by filename, original name, format, job name, or job type
• format: Filter by one file format, such as PDB, FASTA, or SDF
• origin: Filter by UPLOAD, JOB_OUTPUT, JOB_INPUT, or IMPORT
• collection_id: Filter to files in one collection
• mine: Use true to show files uploaded by the API key creator

List responses use the standard list envelope:

{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}

File resource

Single-file responses and list items use the same file resource shape.

{
  "id": "file_123",
  "object": "file",
  "filename": "protein.pdb",
  "original_name": "protein.pdb",
  "format": "PDB",
  "mime_type": "chemical/x-pdb",
  "size": 18420,
  "origin": "UPLOAD",
  "storage_owner": "FILE_LIBRARY",
  "preview_kind": "structure",
  "job_id": null,
  "job_name": null,
  "job_type": null,
  "tool": null,
  "tags": ["receptor"],
  "description": "Reference receptor",
  "collection_ids": [],
  "collections": [],
  "created_at": "2026-06-12T08:00:00.000Z",
  "updated_at": "2026-06-12T08:00:00.000Z",
  "content_url": "/api/v1/files/file_123/content",
  "download_url": "/api/v1/files/file_123/download",
  "input_reference": {
    "type": "file",
    "file_id": "file_123"
  }
}

Use GET /api/v1/files/{fileId} to retrieve one file resource.

curl -s \
  -H "Authorization: Bearer $PROTEINIQ_API_KEY" \
  "https://proteiniq.io/api/v1/files/file_123"

Files from another workspace return not_found.

Upload files

Use POST /api/v1/files with multipart/form-data to upload one file into the API key workspace. The endpoint requires the files:write scope and the same workspace permission needed to create jobs.

curl -s -X POST \
  -H "Authorization: Bearer $PROTEINIQ_API_KEY" \
  -F "file=@protein.pdb;type=chemical/x-pdb" \
  -F "description=Reference receptor" \
  -F "tags=receptor,screening" \
  "https://proteiniq.io/api/v1/files"

Uploads use the same file validation as the web app:

• Size: Each upload is limited to 50 MB
• Supported types: Common sequence, structure, ligand, table, image, archive, PDF, JSON, and text formats are accepted
• Active content: Browser-executable formats such as HTML, JavaScript, SVG, XML, and CSS are not accepted as uploads
• Storage quota: Workspace plan storage limits are enforced before the stored object is created

Optional multipart fields:

• description: Short note stored with the file
• tags: Comma-separated or JSON-array tags
• collection_ids: JSON array or comma-separated collection ids to attach after upload

Successful uploads return the created file resource with status 201.

Reference files in jobs

Use the file resource input_reference in input.inputs[] when submitting a job. Its file_id value becomes source.file_id in the job input. ProteinIQ resolves the saved file server-side before the job starts, so compute receives normal canonical input content.

{
  "tool": "esmfold",
  "name": "Fold saved structure",
  "input": {
    "inputs": [
      {
        "id": "protein_1",
        "slotId": "protein",
        "kind": "protein",
        "format": "pdb",
        "source": {
          "type": "file",
          "file_id": "file_123"
        }
      }
    ]
  },
  "settings": {}
}

File references require both jobs:write and files:read. The file must belong to the API key workspace. Binary files and image files cannot be used as text input references.

Delete files

Use DELETE /api/v1/files/{fileId} to remove a saved file. The endpoint requires the files:write scope and delete permission for the file.

curl -s -X DELETE \
  -H "Authorization: Bearer $PROTEINIQ_API_KEY" \
  "https://proteiniq.io/api/v1/files/file_123"

Successful deletion returns:

{
  "object": "file_deletion",
  "id": "file_123",
  "deleted": true
}

Deleting a FILE_LIBRARY file removes its stored object. Deleting a JOB_ARTIFACT file removes the saved file record while leaving the original job artifact available through the job result.