The File object

Upload a file and you get this object back. Reference its id (file_…) wherever a product accepts a file. size and sha256 are set once the file is ready; while uploading, the object carries the resumable session’s segment_size and received_segments instead.

{
  "id": "file_9f3a...",
  "state": "ready",
  "media_type": "application/pdf",
  "filename": "invoice.pdf",
  "size": 48213,
  "sha256": "e3b0c442...",
  "expires_at": "2026-09-03T18:22:00Z",
  "created_at": "2026-09-02T18:22:00Z"
}

An upload in progress:

{
  "id": "file_9f3a...",
  "state": "uploading",
  "media_type": "application/pdf",
  "filename": "big-scan.pdf",
  "segment_size": 5242880,
  "received_segments": [0, 1, 3],
  "expires_at": "2026-09-03T18:22:00Z",
  "created_at": "2026-09-02T18:22:00Z"
}

Attributes

string

required

File handle (file_…). Reference this wherever a product takes a file.

enum

required

One of uploading, ready, referenced, or expired. A referenced file is pinned from cleanup.

string

MIME type, as declared on upload.

string

Optional client-supplied name. Never used to infer content type.

integer

Byte size. Present once ready.

string

Whole-file SHA-256. Present once ready.

integer

Bytes per segment for a chunked upload. Present while uploading.

array

Zero-based indices received so far. Present while uploading — resume by sending the ones missing.

string

When the file is swept if nothing references it. A reference suspends this.

string

When the file was created.

Core

Conversations

Configuration

Delivery

MCP

Workbench

Attributes

​Attributes

Attributes