Sign in
Documents

Upload a document

Upload a document and optionally link it to targets with metadata.links. Each target must have a different kind. If any link fails, the document is not created. This operation is billable. Use Idempotency-Key to retry safely.

post/documents

Request

  • Base URL: https://next-api.saturation.io/v1
  • URL: https://next-api.saturation.io/v1/documents
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

A 16 to 255 character key for safe retries. Reusing the key with different content returns 409 idempotency_conflict.

Response

The created document and its links.

idstring required

A stable resource ID, such as prj_…, txn_…, or doc_….

namestring required

The document's display name.

mimeTypestring required

The file's MIME type.

sizeinteger required

The file size in bytes.

status'pending' | 'processing' | 'ready' | 'failed' required

The document's extraction status. ready means extracted data is available.

workspaceIdstring required

A stable resource ID, such as prj_…, txn_…, or doc_….

pageCountinteger nullable

The number of pages, or null until extraction finishes.

classificationstring nullable

The document classification, such as invoice or receipt.

coarseType'financial' | 'tax' | 'legal' | 'insurance' | 'production' | 'other'

The document category found during extraction.

hasSensitiveInfoboolean nullable

Whether the document may contain sensitive information.

descriptionstring nullable

The document description.

sourcestring nullable

How the document was added, such as api, agent, or upload.

folderIdstring

A stable resource ID, such as prj_…, txn_…, or doc_….

projectIdstring

A stable resource ID, such as prj_…, txn_…, or doc_….

contentHashstring nullable

A hash of the file contents.

createdAtstring date-time required

When the document was created.

updatedAtstring date-time required

When the document was last updated.

Example response

{
  "id": "doc_4b1f0a7c",
  "name": "vendor-invoice-0425.pdf",
  "mimeType": "application/pdf",
  "size": 184320,
  "status": "ready",
  "workspaceId": "ws_71aa",
  "pageCount": 2,
  "classification": "invoice",
  "coarseType": "financial",
  "folderId": "fld_9c2d",
  "projectId": "prj_71aa",
  "links": [
    {
      "kind": "transaction",
      "id": "txn_8f2a1c9e"
    }
  ],
  "createdAt": "2026-05-28T14:03:11Z",
  "updatedAt": "2026-05-28T14:03:40Z"
}

Changes

No recorded changes to this operation across all 4 revisions of this API.