Workspaces

A workspace holds one body of work — a deal, a portfolio, a client. Documents and tables both live in one, and it is the unit sharing is granted over. Every other path in this API names one.

The level field

Every workspace object carries level: what this key may do in it, computed per request. It is not a stored property of the workspace, and two keys will see different numbers for the same one.

level	Means
`0`	The key reaches one or more tables inside this workspace, but not the workspace itself. Listing its files returns `404`; the table routes work. Do not treat this as "no access".
`1`	Read — list and fetch files, tables, cells, jobs; search.
`2`	Read & write — everything above, plus upload, delete, create tables and columns, start runs, override cells.
`3`	Manage — everything above, plus renaming the workspace itself.

The number is the lower of the owner's live sharing level and whatever the key's scopes allow — see Authentication.

List workspaces

GET/v2/workspaces

Requires None — no API key

Every workspace this key reaches, with its level in each. One of the three paths that does not name a workspace, because this is the call that tells you which ones there are.

Archived workspaces and workspaces belonging to another organisation never appear. Start a client here.

Request

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

Response

{
  "success": true,
  "total": 2,
  "data": [
    {
      "id": "wks_7Kq2mB4nR8vXpL3d",
      "name": "Acme diligence",
      "orgId": "org_4pN8dW1zJ6hT2yUx",
      "level": 3,
      "createdAt": 1755504000000,
      "updatedAt": 1756108800000
    },
    {
      "id": "wks_Zf9tY1cH6sQwE0aN",
      "name": "Portfolio 2026",
      "orgId": "org_4pN8dW1zJ6hT2yUx",
      "level": 1,
      "createdAt": 1754899200000,
      "updatedAt": 1755763200000
    }
  ]
}

Get a workspace

GET/v2/workspaces/:workspaceId

Requires Read on the workspace

The same object the list returns. A workspace this key cannot reach answers 404 rather than 403, so this is not a way to test whether an id exists.

Request

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

Response

{
  "success": true,
  "total": 1,
  "data": {
    "id": "wks_7Kq2mB4nR8vXpL3d",
    "name": "Acme diligence",
    "orgId": "org_4pN8dW1zJ6hT2yUx",
    "level": 3,
    "createdAt": 1755504000000,
    "updatedAt": 1756108800000
  }
}

Create a workspace

POST/v2/workspaces

Requires None — no API key

Creates a workspace in the key owner's organisation. This is the only organisation-level write in the API, so no workspace level applies to it — instead there are three gates, and all three answer 403:

The key's owner must be an owner or admin of the organisation. The app restricts the same act the same way, and the two have to agree or the API is a way around the UI's rule.
It must be a personal key. A workspace key authenticates as a workspace, not as a person who could own a new one.
The key must be unscoped. A key narrowed to specific resources cannot create, because "minting a key can only ever take rights away" has to hold on every route to be worth relying on.

The new workspace is private, and the response's level is 3 because the caller created it. Sharing it with anyone else is done in the app; there is no endpoint for granting access.

Parameters

`name`	string · required1–64 characters.

Request

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

Response

{
  "success": true,
  "total": 1,
  "data": {
    "id": "wks_7Kq2mB4nR8vXpL3d",
    "name": "Acme diligence",
    "orgId": "org_4pN8dW1zJ6hT2yUx",
    "level": 3,
    "createdAt": 1756166400000,
    "updatedAt": 1756166400000
  }
}

Rename a workspace

PATCH/v2/workspaces/:workspaceId

Requires Manage on the workspace

The name is the only thing that can be changed, and it needs Manage rather than read & write. That is deliberate: a read-write grant is for what is inside a workspace, not for the container. A key with level 2 gets 403 here while happily uploading to the same workspace.

Parameters

`name`	string · required1–64 characters.

Request

curl -X PATCH https://api.ragextract.com/v2/workspaces/wks_7Kq2mB4nR8vXpL3d \
  -H "x-api-key: $RAGEXTRACT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name": "Acme diligence — phase 2"}'

Response

{
  "success": true,
  "total": 1,
  "data": {
    "id": "wks_7Kq2mB4nR8vXpL3d",
    "name": "Acme diligence — phase 2",
    "orgId": "org_4pN8dW1zJ6hT2yUx",
    "level": 3,
    "createdAt": 1755504000000,
    "updatedAt": 1756170000000
  }
}

There is no delete

Workspaces are archived in the app rather than deleted, and there is no endpoint for it here. An archived workspace disappears from GET /v2/workspaces and every path under it starts answering 404, which is what a client will observe.