HTTP API

Every Colrows capability is exposed over a clean REST API. Use it to embed the semantic execution layer in your applications, drive your custom AI agents, or build integrations into the rest of your stack. The API is the same surface the UI uses - there is no second-class path.

Base URL & versioning

https://api.colrows.com/v1

The API is versioned through the URL prefix. Backwards-incompatible changes ship under a new prefix; everything within a major version is forwards-additive. The X-Colrows-Version response header reports the exact build serving the request, useful for support tickets.

Authentication

Two equivalent options:

  • API key - generate from Settings → API keys. Pass as Authorization: Bearer cl_…. Keys are scoped to a persona and can be rotated without downtime.
  • OAuth 2.0 client credentials - for service-to-service flows where your auth platform issues short-lived tokens. Token introspection is supported.
curl -H "Authorization: Bearer cl_live_8a2c…" \
     https://api.colrows.com/v1/me

Common operations

Compile & run a query

POST /v1/compile
{
  "input":   "Net revenue in EMEA last quarter, by month",
  "format":  "natural_language",          // or "sql"
  "persona": "regional_analyst",
  "execute": true
}

200 OK
{
  "trace_id": "trc_e1f9…",
  "plan": {
    "concepts":  ["net_revenue", "region"],
    "join_path": ["customer → order → refund"],
    "constraints": [{ "type": "time_window", "value": "Q1 2026" }],
    "policies":  ["region_scope:EMEA"]
  },
  "sql": "SELECT date_trunc('month', o.created_at)... ",
  "rows": [...]
}

Fetch a metric

GET /v1/metrics/net_revenue?as_of=2026-03-31&grain=month®ion=EMEA

List concepts in scope

GET /v1/concepts?persona=regional_analyst

Manage the semantic graph

POST   /v1/concepts            // register a concept
PATCH  /v1/concepts/{id}       // new version
GET    /v1/concepts/{id}/history
GET    /v1/traces/{trace_id}    // fetch a full audit trace

Errors

Every error response is structured and explainable. There is no opaque "internal server error" for compilation failures.

422 Unprocessable Entity
{
  "code":   "ambiguous_join_path",
  "message":"Two valid join paths exist between 'order' and 'campaign'. Add an anchor to disambiguate.",
  "details": {
    "candidates": [
      ["order","attribution","campaign"],
      ["order","customer","campaign_membership","campaign"]
    ],
    "trace_id": "trc_…"
  }
}

Common error codes: ambiguous_join_path, scope_violation, grain_mismatch, cycle_in_metric_graph, unauthorized_concept, schema_drift.

Idempotency, rate limits & pagination

  • Mutating endpoints accept an Idempotency-Key header. Replays return the original response.
  • Rate limits are returned in standard X-RateLimit-* headers; defaults are 600 req/min on Free, higher on paid plans.
  • List endpoints use cursor-based pagination via ?cursor=… and a next_cursor field on the response.

SDKs

Official SDKs for Python, TypeScript, and Java are thin wrappers over the REST surface - same auth, same errors, same paginated responses. They live on PyPI / npm / Maven Central.

For the full machine-readable reference (every endpoint, schema, and example), see the REST API reference.