Eos Developers
Design target — not live yet. This documentation defines the contract Eos will implement. Existing internal application APIs are not part of this contract.

Files API

The Files API uploads, downloads, lists, and links files without sending large binary bodies through the Eos API service.

Roles and access

The Role required to access a file is inherited from its linked resource. A client that can read a project but cannot read Finance data does not gain access to an invoice attachment merely because it knows the file ID. Upload and delete operations also require write permission on the linked resource.

File object

{
  "object": "file",
  "id": "fil_01J8R8WJ9HZ2N2ZB0M8VMSY6Y3",
  "name": "statement-of-work.pdf",
  "content_type": "application/pdf",
  "size_bytes": 248112,
  "sha256": "e3b0c44298fc1c149afbf4c8996fb924...",
  "status": "ready",
  "linked_resource": {"type": "project", "id": "prj_01J8Q8QFXT2Y3QAD6M0MPB75GC"},
  "created_at": "2026-08-22T10:00:00Z"
}

List and get file metadata

  • GET /v1/files — listFiles
  • GET /v1/files/{file_id} — getFile

List filters: linked_resource_type, linked_resource_id, content_type, created_after, limit, and after.

Create an upload

POST /v1/files/uploads

Operation ID: createFileUpload. Required header: Idempotency-Key.

{
  "name": "statement-of-work.pdf",
  "content_type": "application/pdf",
  "size_bytes": 248112,
  "sha256": "e3b0c44298fc1c149afbf4c8996fb924...",
  "linked_resource": {"type": "project", "id": "prj_01J8Q8QFXT2Y3QAD6M0MPB75GC"}
}

Eos returns a short-lived, single-purpose upload URL plus required headers and an upload ID. Limits and permitted content types are returned in the response and may depend on organization policy.

Complete an upload

POST /v1/files/uploads/{upload_id}/complete

Operation ID: completeFileUpload. Required header: Idempotency-Key.

Eos verifies object size and checksum before making the file available. Malware or content-policy checks may leave the file temporarily in processing or reject it.

Create a download URL

POST /v1/files/{file_id}/download

Operation ID: createFileDownload. Returns a short-lived URL. The URL is a bearer capability and must not be logged or shared.

Archive a file

POST /v1/files/{file_id}/archive

Operation ID: archiveFile. Required header: Idempotency-Key. Files subject to retention, legal hold, or posted financial-record rules cannot be archived through the API.

Common errors

FILE_NOT_FOUND, LINKED_RESOURCE_NOT_FOUND, FILE_ACCESS_DENIED, FILE_TOO_LARGE, CONTENT_TYPE_NOT_ALLOWED, CHECKSUM_MISMATCH, UPLOAD_EXPIRED, FILE_SCAN_FAILED, and RETENTION_BLOCKED.

Next: Reports API.