API reference¶
This page is generated from the application's OpenAPI schema. Paths, parameters and body schemas are taken from the running code; the one-line summaries are written by hand.
Base URLs are listed in the overview. Every workspace-scoped path
starts with /{client_id}, your workspace identifier. Authentication is described in
Authentication.
Operations marked Preview are live but are not yet a stability commitment: they authenticate with a signed-in user session rather than an API token, and their paths and response shapes may change.
Workflow triggers¶
Start a workflow run from your own systems and collect the result. See Webhooks and callbacks for the full request, response and error contract.
POST /{client_id}/workflows/{workflow_id}/triggers/api¶
Start a run of a workflow. Returns 202 with an execution_id and a poll_url, or 200 when an Idempotency-Key replays an earlier run.
Auth: API token
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
workflow_id |
path | string | yes |
Request and response details: API trigger.
GET /{client_id}/workflows/{workflow_id}/runs/{run_id}¶
Get the status of a run, and its result once the run has completed.
Auth: API token or user session
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
workflow_id |
path | string | yes | |
run_id |
path | string | yes |
Request and response details: Polling for the result.
POST /api/webhooks/{webhook_path}¶
Start a run of a webhook-triggered workflow with a signed request.
Auth: HMAC signature
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
webhook_path |
path | string | yes |
Request and response details: Inbound webhook trigger.
People directory (SCIM 2.0)¶
A SCIM 2.0 endpoint that keeps the workspace's people directory in step with an identity
provider. It manages directory records, which drive row-level data scope. It does not create
or remove sign-in accounts, roles or tokens. Bulk operations, sorting, ETags and password
changes are not supported. Filtering supports eq clauses joined by and.
GET /{client_id}/scim/v2/ServiceProviderConfig¶
Describe the SCIM features this endpoint supports.
Auth: API token with the people scope pinned to the source scim, minted by a workspace owner
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
GET /{client_id}/scim/v2/ResourceTypes¶
List the SCIM resource types (User, Group).
Auth: API token with the people scope pinned to the source scim, minted by a workspace owner
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
GET /{client_id}/scim/v2/Schemas¶
List the SCIM schemas.
Auth: API token with the people scope pinned to the source scim, minted by a workspace owner
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
GET /{client_id}/scim/v2/Users¶
List people. Supports filter, startIndex and count.
Auth: API token with the people scope pinned to the source scim, minted by a workspace owner
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
POST /{client_id}/scim/v2/Users¶
Create a person record.
Auth: API token with the people scope pinned to the source scim, minted by a workspace owner
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
The request body is a JSON object. Its fields are not yet described in the OpenAPI schema.
GET /{client_id}/scim/v2/Groups¶
List teams. Supports filter, startIndex and count.
Auth: API token with the people scope pinned to the source scim, minted by a workspace owner
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
POST /{client_id}/scim/v2/Groups¶
Create a team.
Auth: API token with the people scope pinned to the source scim, minted by a workspace owner
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
The request body is a JSON object. Its fields are not yet described in the OpenAPI schema.
GET /{client_id}/scim/v2/{kind}/{key}¶
Get one record. kind is Users or Groups.
Auth: API token with the people scope pinned to the source scim, minted by a workspace owner
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
kind |
path | string | yes | |
key |
path | string | yes |
PUT /{client_id}/scim/v2/{kind}/{key}¶
Replace one record.
Auth: API token with the people scope pinned to the source scim, minted by a workspace owner
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
kind |
path | string | yes | |
key |
path | string | yes |
The request body is a JSON object. Its fields are not yet described in the OpenAPI schema.
PATCH /{client_id}/scim/v2/{kind}/{key}¶
Update one record with SCIM PATCH operations.
Auth: API token with the people scope pinned to the source scim, minted by a workspace owner
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
kind |
path | string | yes | |
key |
path | string | yes |
The request body is a JSON object. Its fields are not yet described in the OpenAPI schema.
DELETE /{client_id}/scim/v2/{kind}/{key}¶
Delete one record. A User is deactivated and kept as an inactive record; a Group is removed.
Auth: API token with the people scope pinned to the source scim, minted by a workspace owner
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
kind |
path | string | yes | |
key |
path | string | yes |
API tokens¶
Token management is normally done in the application's settings. The same operations are available to a signed-in user. See Authentication.
POST /{client_id}/api-tokens¶
Create a token. The token value is returned once, in this response only.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
The request body is a JSON object. Its fields are not yet described in the OpenAPI schema.
GET /{client_id}/api-tokens¶
List your own tokens. Token values are never returned.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
DELETE /{client_id}/api-tokens/{token_id}¶
Revoke one of your own tokens.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
token_id |
path | string | yes |
Workflows¶
Read workflows and their runs, and manage schedules and webhook secrets.
GET /{client_id}/workflows¶
List the workflows you can see.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
GET /{client_id}/workflows/{workflow_id}¶
Get one workflow.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
workflow_id |
path | string | yes |
GET /{client_id}/workflows/{workflow_id}/runs¶
List recent runs of a workflow.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
workflow_id |
path | string | yes | |
limit |
query | integer | no | |
trigger_type |
query | string or null | no |
POST /{client_id}/workflows/{workflow_id}/runs/{run_id}/cancel¶
Cancel a run that is in progress.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
workflow_id |
path | string | yes | |
run_id |
path | string | yes |
The request body is a JSON object. Its fields are not yet described in the OpenAPI schema.
GET /{client_id}/workflows/{workflow_id}/schedule¶
Get the workflow's schedule.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
workflow_id |
path | string | yes |
PUT /{client_id}/workflows/{workflow_id}/schedule¶
Set the workflow's schedule. trigger_type is cron, query_check or webhook.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
workflow_id |
path | string | yes |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
trigger_type |
string | yes | |
cron_expression |
string or null | no | |
timezone |
string or null | no | |
check_sql |
string or null | no | |
check_interval_minutes |
integer or null | no | |
webhook_endpoint_path |
string or null | no | |
is_enabled |
boolean | no | |
input_data |
object or null | no |
DELETE /{client_id}/workflows/{workflow_id}/schedule¶
Remove the workflow's schedule.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
workflow_id |
path | string | yes |
POST /{client_id}/workflows/{workflow_id}/schedule/webhook-secret¶
Create or rotate the signing secret for a webhook-triggered workflow. The secret is returned once.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
workflow_id |
path | string | yes |
Request and response details: Signing secrets.
DELETE /{client_id}/workflows/{workflow_id}/schedule/webhook-secret¶
Revoke the signing secret.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
workflow_id |
path | string | yes |
Metrics¶
Read and maintain metric definitions. A user whose role may only propose changes receives
202 and the change is queued for approval.
GET /{client_id}/metrics/list¶
List metrics, optionally filtered by status, category or a search string.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
status |
query | string or null | no | |
category |
query | string or null | no | |
search |
query | string or null | no |
GET /{client_id}/metrics/{metric_id}¶
Get one metric.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
metric_id |
path | string | yes |
POST /{client_id}/metrics¶
Create a metric.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
The request body is a JSON object. Its fields are not yet described in the OpenAPI schema.
PATCH /{client_id}/metrics/{metric_id}¶
Update a metric.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
metric_id |
path | string | yes |
The request body is a JSON object. Its fields are not yet described in the OpenAPI schema.
DELETE /{client_id}/metrics/{metric_id}¶
Delete a metric.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
metric_id |
path | string | yes |
GET /{client_id}/metrics/osi¶
Export the semantic model (datasets, relationships and metrics) as one OSI JSON document.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
Request and response details: Export and portability.
POST /{client_id}/metrics/osi¶
Import an OSI document. dry_run defaults to true and returns the difference without writing.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
dry_run |
query | boolean | no | Default true: return the diff without writing |
The request body is a JSON object. Its fields are not yet described in the OpenAPI schema.
Context¶
Read the context layer (tables, columns, business terms, usage rules, joins) and upload a dbt manifest.
GET /{client_id}/fde/context/tables¶
List the tables in the context layer.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
schema_filter |
query | string | no | |
fields |
query | string | no | |
order_by |
query | string | no | |
limit |
query | integer | no | |
exclude_fields |
query | string | no |
GET /{client_id}/fde/context/table/{table_id}¶
Get one table, including its columns.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
table_id |
path | string | yes |
GET /{client_id}/fde/context/terms¶
List business terms.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
GET /{client_id}/fde/context/rules¶
List usage rules.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
table_id |
query | string | no |
GET /{client_id}/fde/context/joins¶
List the known joins between tables.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
min_confidence |
query | number | no | |
fields |
query | string | no | |
limit |
query | integer | no | |
table_ids |
query | string | no |
POST /{client_id}/fde/context/upload-manifest¶
Upload a dbt manifest.json. Returns 201 with a run_id for the import.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
Request and response details: Data models.
SQL¶
Run read-only SQL against the workspace's warehouse, subject to your role's schema, column
and row permissions. For token-authenticated SQL, use the execute_sql tool on the
MCP server.
POST /{client_id}/tools/execute_sql¶
Validate or run one read-only SQL statement.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
sql |
string | yes | SQL query to execute |
validate_only |
boolean | no | Dry-run only, no execution |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
status |
string | yes | executed, validated, or failed |
rows |
array of object | no | Result rows |
row_count |
integer | no | Total row count |
sql |
string | yes | Executed SQL (may be modified) |
error |
string or null | no | Error if failed |
preview_as_role |
string or null | no | Set when answered under view-as-role |
Ingestion¶
See Connectors and ingestion for connecting sources, sync and schedules.
GET /{client_id}/rig-ingest/connectors¶
List the source connectors that can be connected, with the credentials each one needs.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
GET /{client_id}/rig-ingest/status¶
Report whether ingestion is set up for the workspace and which warehouse it loads into.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
GET /{client_id}/pipeline-health¶
Summarise the health of the workspace's data pipelines.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes |
GET /{client_id}/pipeline-health/runs¶
List recent pipeline runs.
Auth: User session (API tokens are not accepted) · Preview
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client_id |
path | string | yes | |
days |
query | integer | no | |
limit |
query | integer | no |
44 operations are documented here, selected by an explicit allow-list from the application's OpenAPI schema. Operations that are internal, administrative, operational or specific to a single deployment are not part of the public API.