Tables

A table is a question per column and a document per row. Creating one costs nothing — it is an empty grid until you add columns and run it, and the run is the part that spends credits.

The shape of a table

Columns are prompts with an output type. Each carries its own credit rate.
Rows point at a file or a bundle — the subject being asked about.
Cells are the answers, with citations and a confidence score. They exist once a run has created them.

Nothing is computed when you build the grid. Adding a column to a table with 200 rows creates no cells and costs nothing until you run it.

Reading a table

GET /tables/:tableId returns the table, all its columns, all its rows and all its cells in one response. That is the right call for a small table and the wrong one for a poll loop over a large one — a 500-row × 10-column table is 5,000 cells with citations attached.

None of the table collections page. /columns, /rows and /cells each return everything of their kind, so they are a narrower slice rather than a smaller one — useful when you want just the rows, not a way to walk a big table in chunks. There are no offset or limit parameters on them.

For watching a run, poll the run. GET …/runs/:runId carries totalCells and pendingCells in one small response, and is what a progress bar should read. Fetch the grid once when it lands.

Auto mode is called `standing`

A table with standing: true re-runs itself against each new document added to the workspace. It is off by default, and turning it on means new uploads spend credits without anyone asking — see Auto mode for the two controls worth setting first.

Standing runs are driven from the app's own scheduler, not from here. There is no endpoint for "run this table when a document arrives" other than setting the flag.

What `locale` does, and does not

locale makes a table answer in another language. It governs generated prose only. Dates still come back ISO, numbers still come back as numbers, and categorical answers still come back as the verbatim category — because those three are parsed to sort and filter, and a localised date is a string nothing can order.

Changing it marks every column stale and re-runs nothing. The existing answers stay readable and are flagged; getting them in the new language means running the table again, at full cost. The app asks for confirmation before this; the API does not.

List tables

GET/v2/workspaces/:workspaceId/tables

Requires Read on the workspace

Tables in the workspace. Metadata only — no columns, rows or cells.

Request

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

Response

{
  "success": true,
  "total": 1,
  "data": [  {
    "id": "rev_Qm5xC9bV3nK7sAeR",
    "workspaceId": "wks_7Kq2mB4nR8vXpL3d",
    "name": "Vendor contracts",
    "standing": false,
    "color": null,
    "locale": null,
    "archivedAt": null,
    "createdAt": 1756108800000,
    "updatedAt": 1756108800000
  }]
}

Get a table with its grid

GET/v2/workspaces/:workspaceId/tables/:tableId

Requires Read on the workspace

Everything at once, unpaged. Convenient, and expensive on a large table — see above for when to use the collection endpoints instead.

Archived columns are included, carrying their archivedAt stamp — filter on it if you are rendering a grid, because a run only ever targets active ones. Cells are every cell that exists, which on a partly-run table is fewer than rows × columns.

Request

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

Response

{
  "success": true,
  "total": 1,
  "data": {
    "table": { "id": "rev_Qm5xC9bV3nK7sAeR", "name": "Vendor contracts", ... },
    "columns": [
      { "id": "rcol_D9sW4kF7nJ2xB6mV", "name": "Governing law", "outputType": "text_quote", "creditRate": 4, "version": 1, ... }
    ],
    "rows": [
      { "id": "rrow_G3pL8qZ5tN1cH7yU", "subjectType": "file", "subjectId": "ds_M3xJ8pQ1vK5nB7wT", ... }
    ],
    "cells": [
      {
        "id": "rcel_V2mR6xD9bK4jT8nW",
        "rowId": "rrow_G3pL8qZ5tN1cH7yU",
        "columnId": "rcol_D9sW4kF7nJ2xB6mV",
        "status": "SUCCESS",
        "value": { "type": "text_quote", "value": "England and Wales" },
        "citations": [{ "fileId": "ds_M3xJ8pQ1vK5nB7wT", "page": 27, "quote": "…governed by the laws of England and Wales…", "box": [0.11, 0.42, 0.88, 0.47] }],
        "confidence": 0.94,
        "stale": false,
        ...
      }
    ]
  }
}

Create a table

POST/v2/workspaces/:workspaceId/tables

Requires Read & write on the workspace

An empty table. Free — nothing is computed until a run.

Parameters

`name`	string · required1–120 characters.
`standing`	booleanAuto mode. `false` by default. `true` means new documents in the workspace are run against this table automatically, spending credits.
`locale`	string \| nullUp to 16 characters, e.g. `fr` or `de-DE`. Governs generated prose only.
`color`	string \| nullUp to 16 characters. Presentation only.

Request

curl -X POST https://api.ragextract.com/v2/workspaces/wks_7Kq2mB4nR8vXpL3d/tables \
  -H "x-api-key: $RAGEXTRACT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name": "Vendor contracts"}'

Response

{
  "success": true,
  "total": 1,
  "data": {
  "id": "rev_Qm5xC9bV3nK7sAeR",
  "workspaceId": "wks_7Kq2mB4nR8vXpL3d",
  "name": "Vendor contracts",
  "standing": false,
  "color": null,
  "locale": null,
  "archivedAt": null,
  "createdAt": 1756108800000,
  "updatedAt": 1756108800000
}
}

Update a table

PATCH/v2/workspaces/:workspaceId/tables/:tableId

Requires Read & write on the workspace

Every field optional; omitted ones are left alone.

Changing locale bumps every active column's version, which marks every cell in the table stale. No cell is recomputed and nothing is charged — but a client showing this table needs to render the staleness, or a reader sees French answers that are still in English with nothing explaining why.

Parameters

`name`	string1–120 characters.
`standing`	booleanAuto mode on or off.
`locale`	string \| nullUp to 16 characters. Marks every column stale — see above.
`color`	string \| nullUp to 16 characters.

Request

curl -X PATCH https://api.ragextract.com/v2/workspaces/wks_7Kq2mB4nR8vXpL3d/tables/rev_Qm5xC9bV3nK7sAeR \
  -H "x-api-key: $RAGEXTRACT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"locale": "fr"}'

Response

{
  "success": true,
  "total": 1,
  "data": {
  "id": "rev_Qm5xC9bV3nK7sAeR",
  "workspaceId": "wks_7Kq2mB4nR8vXpL3d",
  "name": "Vendor contracts",
  "standing": false,
  "color": null,
  "locale": "fr",
  "archivedAt": null,
  "createdAt": 1756108800000,
  "updatedAt": 1756281600000
}
}

Archive a table

DELETE/v2/workspaces/:workspaceId/tables/:tableId

Requires Read & write on the workspace

Archives rather than deletes, and returns the table with its archivedAt stamp. The documents it was built over are untouched.

Request

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

Response

{
  "success": true,
  "total": 1,
  "data": {
  "id": "rev_Qm5xC9bV3nK7sAeR",
  "workspaceId": "wks_7Kq2mB4nR8vXpL3d",
  "name": "Vendor contracts",
  "standing": false,
  "color": null,
  "locale": null,
  "archivedAt": 1756281600000,
  "createdAt": 1756108800000,
  "updatedAt": 1756108800000
}
}

The shape of a table

Reading a table

Auto mode is called standing

What locale does, and does not

List tables

Get a table with its grid

Create a table

Update a table

Archive a table

Auto mode is called `standing`

What `locale` does, and does not