/v1/tables for tables and rows, /v1/views for views, and /v1/grid for the computed graph.
Row appends and ingestion batches need the tables:append scope, not agent:write (see Authentication). Product-side docs: Tables.
Find and open a table
GET /v1/tables
List tables in the data grid.
GET /v1/tables/{table_id}
Show a table’s definition: its columns, types, and source, plus an
appendable annotation for whether it accepts row appends. (Catalog metadata is a separate endpoint, below.)GET /v1/tables/{table_id}/data
Preview a table’s rows.
Catalog
GET /v1/tables/catalog
List table catalog metadata across the tenant.
GET /v1/tables/{table_id}/catalog
Show a table’s catalog.
PATCH /v1/tables/{table_id}/catalog
Update a table’s catalog (description, owner, source system, modeling tier, agent description).
Lineage
GET /v1/grid/tables/{table_id}/lineage
Show a table’s lineage.
Delete a table
DELETE /v1/tables/{table_id}
Delete a table. Requires the
agent:write scope and confirm=true (a 400 otherwise); optional force and metadata_only query params.Create a calculation table
POST /v1/grid/tables
Create a calculation table from a SELECT query. This is the default (
kind: "calc"); the same route also creates data tables with kind: "data".POST /v1/grid/tables/{table_id}/materialize
Materialize the table so it can be queried.
POST /v1/grid/tables/{table_id}/synchronizations
Refresh it from the latest source data.
Create a data table
POST /v1/grid/tables
Create an empty data table from a column schema with
kind: "data" and columns. The API adds an integer s_id primary key and an _sm_created_at timestamp for you, so don’t declare them. The id it returns accepts appends immediately. Use this rather than POST /v1/table-imports, which loads a table from an uploaded file and produces an import table that does not accept appends.POST /v1/tables/{table_id}/rows
Append 1–500 rows per request; every row must include the table’s primary key column(s) (a
400 otherwise). Returns 200 when all rows apply, 207 for a partial result, or 422; a 409 means the table isn’t promoted yet. Requires the tables:append scope.PUT /v1/tables/{table_id}/rows
Upsert rows (insert or update by key), with the same 1–500 row limit and
tables:append scope.POST /v1/tables/{table_id}/ingestion-batches
Start a batched (multipart) ingestion for larger loads.
POST .../ingestion-batches/{batch_id}/parts/{part_number}/upload-url
Get a presigned URL to upload one part of a batch.
POST .../ingestion-batches/{batch_id}/commit
Commit the batch to apply its rows.
DELETE .../ingestion-batches/{batch_id}
Abort a batch and discard its parts. Requires the
tables:append scope and confirm=true.GET .../ingestion-batches/{batch_id}
Check a batch’s status.
Create a source table
POST /v1/table-imports
Import a file into a new source table, or refresh an existing one: set
import_type to FULL_REFRESH or INCREMENTAL_REFRESH to re-import into a table that already exists (the API counterpart of the refresh above).GET /v1/table-imports/{import_id}
Poll an import’s status.
Create and manage
GET /v1/views
List views (optionally for one table).
GET /v1/views/{view_id}
Show a view’s definition.
GET /v1/views/{view_id}/data
Fetch a page of the view’s rows.
DELETE /v1/views/{view_id}
Delete a view.
Catalog
GET /v1/views/{view_id}/catalog
Show a view’s catalog.
PATCH /v1/views/{view_id}/catalog
Update a view’s catalog (description, owner, agent description).