Using the API
Authorization
The permissions an API key holds, what each endpoint needs, and the error when a key can't.
Authentication proves who is calling. Authorization decides what that key may do: every API key belongs to one project and holds a set of permissions, and every endpoint needs one of them. A request succeeds only when the key's project matches the path and the key holds the endpoint's permission.
Get a key with the right permissionsLink to section
Open the project's API keysLink to section
In the app, open the project and choose API keys.
Choose its permissionsLink to section
Name the key after where it runs, then pick the permissions it needs from the list below and nothing more. A key for a nightly export needs
tables:read; an importer that creates rows also needstables:write.Use itLink to section
Send it as
Authorization: ApiKey <key>. To change what a key can do, create a new key with the permissions you want, deploy it, and revoke the old one.
What each endpoint needsLink to section
Each endpoint's page in the API reference names its permission under its path
(Requires tables:read), and its Markdown says the same. The
OpenAPI document carries it too, as the scope of the apiKey security
requirement, so generated clients and agents can read it:
"security": [{ "apiKey": ["tables:read"] }]An endpoint whose requirement lists no scope accepts any valid key of the project.
PermissionsLink to section
| Permission | Allows |
|---|---|
columns:write | Add, edit, reorder and remove a table's columns. |
export:read | Export a table's rows and download the files. |
extract:write | Run extractions and schema suggestions, which use your plan's credits. |
rows:delete | Delete rows. |
rows:read | List, read, filter and aggregate rows. |
rows:write | Create, edit and bulk-write rows. |
tables:delete | Delete tables and their rows. |
tables:read | List and read tables, their rows, batches, exports and downloads. |
tables:write | Create, edit, restore and duplicate tables; change their columns and rows. |
webhooks:manage | Create, edit, test and delete webhooks, and rotate their secrets. |
columns:writeLink to section
Add, edit, reorder and remove a table's columns.
No endpoint requires this permission yet.
export:readLink to section
Export a table's rows and download the files.
No endpoint requires this permission yet.
extract:writeLink to section
Run extractions and schema suggestions, which use your plan's credits.
POST /v1/projects/{project_id}/extract: Extract data from text or file (JSON response)POST /v1/projects/{project_id}/extract-stream: Extract data from text or file (SSE stream)POST /v1/projects/{project_id}/tables/{table_id}/extract: Extract into table (JSON response)POST /v1/projects/{project_id}/tables/{table_id}/extract-stream: Extract into table (SSE stream)POST /v1/projects/{project_id}/suggest-schema: Suggest schema from text or file (multipart)
rows:deleteLink to section
Delete rows.
No endpoint requires this permission yet.
rows:readLink to section
List, read, filter and aggregate rows.
No endpoint requires this permission yet.
rows:writeLink to section
Create, edit and bulk-write rows.
No endpoint requires this permission yet.
tables:deleteLink to section
Delete tables and their rows.
DELETE /v1/projects/{project_id}/tables/{table_id}: Delete table (soft, 72h grace)DELETE /v1/projects/{project_id}/tables/{table_id}/rows/{row_id}: Delete row
tables:readLink to section
List and read tables, their rows, batches, exports and downloads.
GET /v1/projects/{project_id}/tables: List tablesGET /v1/projects/{project_id}/tables/{table_id}: Get tableGET /v1/projects/{project_id}/tables/{table_id}/columns/{col_id}/distinct: Get distinct column valuesGET /v1/projects/{project_id}/tables/{table_id}/rows: List rowsGET /v1/projects/{project_id}/tables/{table_id}/rows/aggregate: Aggregate column valuesGET /v1/projects/{project_id}/tables/{table_id}/rows/{row_id}: Get rowGET /v1/projects/{project_id}/tables/{table_id}/rows/{row_id}/source: The source file behind a row: download it, or open a PDF or image inlineGET /v1/projects/{project_id}/batches: List batchesGET /v1/projects/{project_id}/batches/{batch_id}: Get batchGET /v1/projects/{project_id}/batches/{batch_id}/download/csv: Download batch CSVGET /v1/projects/{project_id}/batches/{batch_id}/download/json: Download batch JSONGET /v1/projects/{project_id}/batches/{batch_id}/download/xlsx: Download batch XLSXGET /v1/projects/{project_id}/exports/{export_id}: Get export statusGET /v1/projects/{project_id}/tables/{table_id}/export: Export table rowsGET /v1/projects/{project_id}/table-templates: Browse table templatesGET /v1/projects/{project_id}/table-templates/{template_id}: Preview table template
tables:writeLink to section
Create, edit, restore and duplicate tables; change their columns and rows.
POST /v1/projects/{project_id}/tables: Create tablePATCH /v1/projects/{project_id}/tables/{table_id}: Update tablePOST /v1/projects/{project_id}/tables/{table_id}/duplicate: Duplicate table structurePOST /v1/projects/{project_id}/tables/{table_id}/restore: Restore deleted tablePOST /v1/projects/{project_id}/tables/{table_id}/columns: Add columnPUT /v1/projects/{project_id}/tables/{table_id}/columns/order: Reorder columnsPATCH /v1/projects/{project_id}/tables/{table_id}/columns/{col_id}: Update columnDELETE /v1/projects/{project_id}/tables/{table_id}/columns/{col_id}: Remove columnPOST /v1/projects/{project_id}/tables/{table_id}/rows: Create rowPOST /v1/projects/{project_id}/tables/{table_id}/rows/bulk: Bulk create/update/delete rowsPATCH /v1/projects/{project_id}/tables/{table_id}/rows/{row_id}: Update rowPOST /v1/projects/{project_id}/table-templates/{template_id}/use: Create table from template
webhooks:manageLink to section
Create, edit, test and delete webhooks, and rotate their secrets.
GET /v1/organizations/{organization_id}/webhooks: List webhooksPOST /v1/organizations/{organization_id}/webhooks: Create webhookGET /v1/organizations/{organization_id}/webhooks/{id}: Get webhookPATCH /v1/organizations/{organization_id}/webhooks/{id}: Update webhookDELETE /v1/organizations/{organization_id}/webhooks/{id}: Delete webhookGET /v1/organizations/{organization_id}/webhooks/{id}/deliveries: List webhook deliveriesPOST /v1/organizations/{organization_id}/webhooks/{id}/rotate-secret: Rotate webhook secretPOST /v1/organizations/{organization_id}/webhooks/{id}/test: Send test webhook
When a key can'tLink to section
A key without the endpoint's permission, or one from another project, gets a 403:
HTTP/1.1 403 Forbiddencontent-type: application/json{ "error_key": "forbidden", "fields": {}, "message": "Access forbidden", "status": 403, "status_key": "forbidden", "success": false}| Status | error_key | Cause | Fix |
|---|---|---|---|
| 401 | unauthorized | No Authorization header, a key that doesn't exist, or one that expired or was revoked | Send a live key as ApiKey <key> |
| 403 | forbidden | The key lacks the endpoint's permission, belongs to another project, or the request comes from an IP the key doesn't allow | Use a key of this project that holds the permission |
| 403 | org_suspended | The organization's payment failed | Update the payment method; vars.current_plan names the plan |
A 401 has the same shape with "error_key": "unauthorized" and
"message": "Authentication required". See Errors for the full envelope.
RecipesLink to section
| Job | Permissions |
|---|---|
| Read-only agent or dashboard | tables:read |
| Importer that extracts files into tables | extract:write, tables:read |
| Sync that writes rows from another system | tables:read, tables:write |
| Webhook setup in CI | webhooks:manage |
| Full automation | every permission it uses, listed above |