HTTP API

The Colrows platform exposes a REST API under /api on your Colrows host - the same surface the web app uses. It lets you ask governed analytics questions, read semantic entities and metrics, and manage governance from your own code. For AI agents and third-party MCP clients, prefer the stable, purpose-built MCP Tool Reference.

Which surface should I use?

Building an agent or integration? Use the MCP Tool Reference (or MCP over JSON-RPC) - a small, stable, read-only tool contract with clarification and continuation. Building your own app against the full platform? Use this HTTP API.

Base URL & authentication

Every route below is served under /api on your Colrows host. On Colrows Cloud that is:

https://cloud.colrows.com/api

Every request sends a bearer token. Three kinds exist:

User session token - works on every route the user's role allows. The request runs as that user and inherits their access, redaction, and governance.
OAuth client token (cr_sem_at_...) - for server-to-server calls, from the client credentials grant. It works only on routes that accept a client scope: semantic:read and semantic:write for the Semantic API, including verified queries, and access-control:read and access-control:read-write for access and redaction policies. The client acts as a curator in its organization (or an administrator when it holds access-control:read-write). The REST API reference lists each route's scope.
MCP token (cr_mcp_at_...) - for MCP clients only. See the MCP Tool Reference.

See Authentication for how to get and send each token.

Authorization: Bearer <token>

Ask & run analytics

The core of the API is asking a governed question and getting a proven answer - Colrows compiles intent into validated SQL.

Endpoint	Purpose
`POST /api/ai/ask`	Ask a natural-language analytics question; returns a governed answer.
`POST /api/ai/query` · `/api/ai/query/continue`	Generate/run a query, and continue when a clarification is needed.
`POST /api/ai/validate`	Validate a query without running it.
`POST /api/ai/query/executions` · `GET .../{executionId}`	Submit a governed execution and re-fetch its result by ID.
`GET /api/ai/chat/list` · `/get/{conversationId}`	List and reopen prior conversations (see Audit & Traces).

An answer carries the generated SQL, a confidence score and explanation, the semantic sources used (entity types with names and descriptions), columns, rows, a row count, and a truncated flag. Row limits and cost guardrails apply.

Generate & run SQL for your users

An application can also write and run read-only SQL as one of its users, with that user's access and redaction rules. The user approves the app once through OAuth 2.0 authorization code with PKCE, and the app calls these routes with a token that has the sql:generate and sql:execute scopes. The full guide is SQL API for Your Users.

Endpoint	Purpose
`POST /api/ai/generate-sql`	Turn a question into one read-only SQL query for a datasource, or return a clarification. Does not run the query. See Generate SQL.
`POST /api/data-query/execute-sql`	Run one read-only SQL query as the user and return its rows (up to 10,000). See Run SQL.

Read the semantic layer

Semantic entities live under /api/consensus/*. A few common reads:

Endpoint	Purpose
`POST /api/consensus/search`	Search the semantic layer by meaning.
`GET /api/consensus/metrics/{metricId}[/{version}]`	Read a metric definition (and a specific version); a `/schema` variant returns its output schema.
`GET /api/consensus/business-terms` · `/{termId}`	Read business terms.
`GET /api/consensus/verified-queries`	List verified queries.
`GET /api/consensus/datasources/{id}/semantic-state`	Datasource readiness.

Metrics and other entities are keyed by ID and version, not by name - definitions are immutable and versioned. Curators author them in Catalog.

Errors

Failures use standard HTTP statuses and a JSON body with a machine-readable code and a message:

{ "code": "INSUFFICIENT_PRIVILEGE", "message": "You do not have sufficient permissions to perform this operation." }

Code	Typical status	Meaning
`INVALID_REQUEST`	400	The request failed validation.
`INVALID_AUTH_HEADER`	401	The bearer token is missing, malformed, expired, or revoked.
`INCORRECT_SESSION_INFO`	401	The user session is no longer active.
`INSUFFICIENT_PRIVILEGE`	403	The role or token scope does not allow this route, or access policies deny the data.
`RESOURCE_NOT_FOUND`	404	The entity does not exist or is not visible to the caller.
`OPERATION_FAILED`	500, or 200 for a handled failure	The operation failed; `message` says why.

MCP tools use their own codes (INVALID_INPUT, NOT_FOUND, ACCESS_DENIED, VERSION_CHANGED, FAILED), documented in the MCP Tool Reference.

Governed either way.

The analytics endpoints take intent (a question) and compile it into governed, validated SQL - see compile-then-execute. POST /api/data-query/execute-sql accepts SQL, but only a single read-only query. It checks every column the query reads against the user's access, then runs it as the user with their row filters and redaction rules and the cost guardrail.