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.

File metadata

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.

File origins

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 and deletion

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 --fail-with-body --silent --show-error \
  -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
• project_id: Filter to files assigned to one project
• unassigned: Use true to return files without a project
• mine: Use true to show files uploaded by the API key creator

Do not combine project_id and unassigned=true.

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",
  "project_id": "project_123",
  "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 --fail-with-body --silent --show-error \
  -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 --fail-with-body --silent --show-error -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: Application validation allows up to 50 MB per file; the hosting service can reject a smaller request before it reaches this validation.
• 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
• project_id: Project that should contain the file

Successful uploads return the created file resource with status 201.

A non-null project_id requires projects:write in addition to files:write. File resources return project_id as null when they are unassigned.

Reference files in jobs

This example requires an uploaded FASTA sequence file; replace file_123 with its ID. ESMfold accepts sequences, so the PDB file shown in the metadata example cannot be used here.

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 reads the saved file before the job starts.

{
  "tool": "esmfold",
  "name": "Fold saved sequence",
  "input": {
    "inputs": [
      {
        "id": "protein_1",
        "slotId": "protein",
        "kind": "protein",
        "format": "fasta",
        "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.

Inline content and all resolved file references together must fit within 50 MiB per quote or submission. For example, two 30 MiB references exceed the aggregate limit even though each file meets the upload validation limit. Tool-specific input limits also apply.

Saved-file downloads

File resources currently include content_url and download_url metadata, but the corresponding public v1 download routes are not implemented. Do not build download requests from those fields.

Download saved files through Files in the app. For a job output, use the signed URLs from the Results API. Saved files can still be reused directly as job 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 --fail-with-body --silent --show-error -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. Deleting its source job also removes saved references to that artifact; saving it to Files is not a separate backup.