Files

A file is one uploaded document. Putting one in a workspace reads, splits and indexes it — that is what costs credits, and it happens once. Everything you ask of it afterwards is paid for already.

What upload actually does

Uploading returns a job, not a finished file. The document is converted to page images, each page is indexed, and the file becomes usable when the job reaches SUCCESS. Poll the job; do not assume the file is queryable the moment the upload returns.

Ingest costs 1 credit per page. The page count is not known until the document has been read, so the upload endpoint refuses only a balance that cannot cover a single page — a large document on a thin balance will start and then fail partway rather than being rejected up front.

Formats and sizes

PDF, DOC, DOCX, PPTX, XLSX, JPEG, PNG and WebP. Legacy .xls is not accepted. An image ingests as a single page.

Two size limits apply and the smaller one wins. A single-request upload is capped at 100 MB; over that, use an upload session. Separately, the organisation's tier caps the size of any upload at all — 10 MB at Starter, 25 MB at Bronze, 100 MB at Silver, 300 MB at Gold — and it caps pages per job (100 to 1,000). Those are on Tiers and limits, and they are the ones people actually hit.

Pages are file items

Ingest turns a document into file items (dsx_…), one per page, in three representations: pdf (the single-page PDF), jpg (the rendered image) and embedding_image (what retrieval matched against). Citations point at a page, so this is how you fetch the thing behind an answer.

Item responses carry a share link, which is a short-lived signed URL. It is minted at read time and expires — it is not a permanent address, so do not store one.

Upload a file

POST/v2/workspaces/:workspaceId/files

Requires Read & write on the workspace

multipart/form-data, not JSON. Returns the ingest job.

Spends credits — 1 per page, charged as the document is read.

Parameters

`file`	fileThe document. Up to 100 MB here, and within the organisation's tier ceiling. Exactly one of `file` or `url`.
`url`	stringA public URL to fetch instead of sending bytes. Must be reachable from the internet; loopback and internal addresses are refused with `400`.
`expiresInDays`	numberStamps a deletion date on the file. Optional, and nothing sets one by default — a file with no expiry is never deleted automatically, on any tier. Setting this is the only thing that makes `expiresAt` non-null.

Request

curl -X POST https://api.ragextract.com/v2/workspaces/wks_7Kq2mB4nR8vXpL3d/files \
  -H "x-api-key: $RAGEXTRACT_API_KEY" \
  -F "file=@acme-msa-2024.pdf"

# or, instead of a file, a URL we should fetch:
#  -F "url=https://example.com/acme-msa-2024.pdf"

Response

{
  "success": true,
  "total": 1,
  "data": {
    "id": "dsj_L8vB2mQ6xR3kW9pZ",
    "fileId": "ds_M3xJ8pQ1vK5nB7wT",
    "type": "extract",
    "status": "NOT_STARTED",
    "statusText": null,
    "startedAt": null,
    "finishedAt": null,
    "canceledAt": null,
    "createdAt": 1756108800000,
    "updatedAt": 1756108800000
  }
}

List files

GET/v2/workspaces/:workspaceId/files

Requires Read on the workspace

Everything in the workspace, newest first unless you say otherwise.

Query parameters

`types`	stringComma-separated: `doc`, `image`, `image_list`, `audio`, `video`. Audio and video exist in the type list and are not supported — nothing ingests as one.
`offset`	numberRows to skip. Default 0.
`limit`	numberRows to return. Default 10, clamped to 100.
`sort`	stringComma-separated field names, each prefixed `-` for descending — `-createdAt,fileName`. Defaults to `-createdAt`. Unknown field names are ignored.
`expiresInSeconds`	numberLifetime of the share URLs minted on this response. 60 to 86,400; the default is 600. See Share links.

Request

curl "https://api.ragextract.com/v2/workspaces/wks_7Kq2mB4nR8vXpL3d/files?limit=25&types=doc,image" \
  -H "x-api-key: $RAGEXTRACT_API_KEY"

Response

{
  "success": true,
  "total": 1,
  "data": [  {
    "id": "ds_M3xJ8pQ1vK5nB7wT",
    "workspaceId": "wks_7Kq2mB4nR8vXpL3d",
    "type": "doc",
    "fileName": "acme-msa-2024.pdf",
    "fileExt": "pdf",
    "fileSize": 2418176,
    "itemCount": 34,
    "mimeType": "application/pdf",
    "createdAt": 1756108800000,
    "updatedAt": 1756109120000,
    "expiresAt": null,
    "share": {
      "url": "https://api.ragextract.com/v2/share/dsx_R4hN9kP2sD6yF1cV?token=v1.1756110000.9Xk…",
      "token": "v1.1756110000.9Xk…",
      "expiresAt": 1756110000000
    }
  }],
  "offset": 0,
  "limit": 25
}

Get a file

GET/v2/workspaces/:workspaceId/files/:fileId

Requires Read on the workspace

One file. itemCount is its page count — the number ingest charged for.

expiresAt is null unless someone asked for an expiry when uploading. It is not a retention window: nothing deletes documents on a schedule, on any tier.

Query parameters

`expiresInSeconds`	numberLifetime of the share URL on this response. 60–86,400, default 600.

Request

curl https://api.ragextract.com/v2/workspaces/wks_7Kq2mB4nR8vXpL3d/files/ds_M3xJ8pQ1vK5nB7wT \
  -H "x-api-key: $RAGEXTRACT_API_KEY"

Response

{
  "success": true,
  "total": 1,
  "data": {
  "id": "ds_M3xJ8pQ1vK5nB7wT",
  "workspaceId": "wks_7Kq2mB4nR8vXpL3d",
  "type": "doc",
  "fileName": "acme-msa-2024.pdf",
  "fileExt": "pdf",
  "fileSize": 2418176,
  "itemCount": 34,
  "mimeType": "application/pdf",
  "createdAt": 1756108800000,
  "updatedAt": 1756109120000,
  "expiresAt": null,
  "share": {
    "url": "https://api.ragextract.com/v2/share/dsx_R4hN9kP2sD6yF1cV?token=v1.1756110000.9Xk…",
    "token": "v1.1756110000.9Xk…",
    "expiresAt": 1756110000000
  }
}
}

List a file's pages

GET/v2/workspaces/:workspaceId/files/:fileId/items

Requires Read on the workspace

The document's pages. col is the page number, 1-based; row is which representation.

Each item's share.url is a signed link to the actual bytes, valid for the window you asked for. It is minted per response — fetch it, don't file it.

Query parameters

`row`	string`pdf`, `jpg` or `embedding_image`. Anything else is a `400`. Omit for all three.
`cols`	stringComma-separated page numbers, to fetch specific pages.
`offset`	numberRows to skip. Default 0.
`limit`	numberRows to return. Default 10, clamped to 100.
`sort`	stringComma-separated field names, `-` for descending. Defaults to `-createdAt`, which on pages is upload order rather than page order — sort on `col` if you want page 1 first.
`expiresInSeconds`	numberLifetime of the share URLs. 60–86,400, default 600.

Request

curl "https://api.ragextract.com/v2/workspaces/wks_7Kq2mB4nR8vXpL3d/files/ds_M3xJ8pQ1vK5nB7wT/items?row=jpg&limit=5" \
  -H "x-api-key: $RAGEXTRACT_API_KEY"

Response

{
  "success": true,
  "total": 2,
  "data": [
    {
      "id": "dsx_R4hN9kP2sD6yF1cV",
      "fileId": "ds_M3xJ8pQ1vK5nB7wT",
      "row": "jpg",
      "col": 1,
      "createdAt": 1756108900000,
      "share": {
        "url": "https://api.ragextract.com/v2/share/dsx_R4hN9kP2sD6yF1cV?token=v1.…",
        "token": "v1.1756110000.9Xk…",
        "expiresAt": 1756110000000
      }
    },
    { "id": "dsx_T7bM1wG5jH8qE3zY", "fileId": "ds_M3xJ8pQ1vK5nB7wT", "row": "jpg", "col": 2, ... }
  ],
  "offset": 0,
  "limit": 5
}

Get one page

GET/v2/workspaces/:workspaceId/files/:fileId/items/:fileItemId

Requires Read on the workspace

One page, when you already have its id — from a citation or a search match.

Query parameters

`expiresInSeconds`	numberLifetime of the share URL. 60–86,400, default 600.

Request

curl https://api.ragextract.com/v2/workspaces/wks_7Kq2mB4nR8vXpL3d/files/ds_M3xJ8pQ1vK5nB7wT/items/dsx_R4hN9kP2sD6yF1cV \
  -H "x-api-key: $RAGEXTRACT_API_KEY"

Response

{
  "success": true,
  "total": 1,
  "data": {
    "id": "dsx_R4hN9kP2sD6yF1cV",
    "fileId": "ds_M3xJ8pQ1vK5nB7wT",
    "row": "jpg",
    "col": 1,
    "createdAt": 1756108900000,
    "share": { "url": "https://api.ragextract.com/v2/share/…", "token": "v1.…", "expiresAt": 1756110000000 }
  }
}

Delete a file

DELETE/v2/workspaces/:workspaceId/files/:fileId

Requires Read & write on the workspace

Returns the file it deleted. The removal of the stored bytes and index entries is handed to a background job, but the file stops being readable immediately — including through any share link already minted for one of its pages, which starts answering 404 rather than continuing to work until the cleanup lands.

Credits are not refunded. Ingest paid for reading the document; deleting it does not un-read it.

Request

curl -X DELETE https://api.ragextract.com/v2/workspaces/wks_7Kq2mB4nR8vXpL3d/files/ds_M3xJ8pQ1vK5nB7wT \
  -H "x-api-key: $RAGEXTRACT_API_KEY"

Response

{
  "success": true,
  "total": 1,
  "data": {
  "id": "ds_M3xJ8pQ1vK5nB7wT",
  "workspaceId": "wks_7Kq2mB4nR8vXpL3d",
  "type": "doc",
  "fileName": "acme-msa-2024.pdf",
  "fileExt": "pdf",
  "fileSize": 2418176,
  "itemCount": 34,
  "mimeType": "application/pdf",
  "createdAt": 1756108800000,
  "updatedAt": 1756109120000,
  "expiresAt": null,
  "share": {
    "url": "https://api.ragextract.com/v2/share/dsx_R4hN9kP2sD6yF1cV?token=v1.1756110000.9Xk…",
    "token": "v1.1756110000.9Xk…",
    "expiresAt": 1756110000000
  }
}
}

Delete several files

DELETE/v2/workspaces/:workspaceId/files

Requires Read & write on the workspace

All or nothing: if any id in the list is not a file in this workspace, the whole call fails and nothing is deleted, with the offending ids named in the error.

Parameters

`fileIds`	string[] · required1 to 100 ids, each starting `ds_`.

Request

curl -X DELETE https://api.ragextract.com/v2/workspaces/wks_7Kq2mB4nR8vXpL3d/files \
  -H "x-api-key: $RAGEXTRACT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"fileIds": ["ds_M3xJ8pQ1vK5nB7wT", "ds_K2nV7cX4jL9bR1sD"]}'

Response

{
  "success": true,
  "total": 2
}