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.
Connecting an MCP app such as ChatGPT or Claude? Use the MCP client connector. Building an agent that plans its own queries? Use the versioned agent API, over REST or MCP. Building your own app against the full platform? Use the routes on this page.
Base URL & authentication
Every route below is served under /api on your Colrows host. On Colrows Cloud that is:
https://cloud.colrows.com/apiEvery 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 data access, masking, and governance.
- OAuth client token (
cr_oauth_cc_at_...) - for server-to-server calls, from the client credentials grant. It works only on routes that accept a client scope:semantic:readandsemantic:read-writefor the Semantic API, including verified queries;access-control:readandaccess-control:read-writefor data access and data masking policies; and the agent scopessemantic:sql,sql:execute,data:query, anddata:sqlfor the agent API. The client acts as a curator in its organization (or an administrator when it holdsaccess-control:read-write). The REST API reference lists each route's scope. - OAuth user token (
cr_mcp_at_...) - from the authorization code grant. It works only on the MCP endpoints and, for an app your administrator registered, the agent API, as the user who approved it. See the MCP integration guide.
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.
Agent API
Agents and applications that plan their own queries use the versioned agent API under /api/agents/v1. It takes an OAuth client token or an OAuth user token from an app your administrator registered, never a user session token. Every route is also an MCP tool on /api/mcp/agents. Full arguments, limits, and errors are in the MCP Tool Reference; acting as your app's users is covered in Agent Query API for Your Users.
| Endpoint | Purpose | Scope |
|---|---|---|
GET /api/agents/v1/datasources | Accessible datasources and semantic publication readiness. | semantic:read |
POST /api/agents/v1/semantic/join-graph · /values/resolve | Join paths between tables; phrases mapped to typed stored values. | semantic:read |
POST /api/agents/v1/semantic-search · /semantic-entities/batch | Search semantic entities; batch-read up to 100 definitions. | semantic:read + semantic:sql |
POST /api/agents/v1/semantic-resolution-cache/search · /match | Cached SQL candidates; a confirmed cached match. | semantic:read + semantic:sql |
POST /api/agents/v1/queries/compile | Generate SQL from a prompt without running it. | data:query |
POST /api/agents/v1/queries/validate | Check SQL or a verified query without running it. | sql:execute |
POST /api/agents/v1/queries | Submit a governed, asynchronous execution. Needs an idempotency key. | data:query; SQL also data:sql |
GET /api/agents/v1/queries/{executionId} · /results · POST .../cancel | Status, result pages, and cancellation of your own execution. | data:query |
Agent routes return { "data", "meta" } and report errors as application/problem+json, not with the codes below. The former SQL routes POST /api/ai/generate-sql and POST /api/data-query/execute-sql are removed and return 404; use queries/compile and queries instead.
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/{queryId}[/{version}] | Read a verified query (and a specific version). There is no list route; find queries with search. |
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 and the agent API use their own codes (for example INVALID_INPUT, NOT_FOUND, ACCESS_DENIED, VERSION_CHANGED, IDEMPOTENCY_CONFLICT), documented in the MCP Tool Reference.
The analytics endpoints take intent (a question) and compile it into governed, validated SQL - see compile-then-execute. The agent API's POST /api/agents/v1/queries accepts SQL only with the data:sql scope, and only a single read-only query. It checks every column the query reads against the caller's access, then runs it with their row filters and masking rules and the cost guardrail.