Colrows (2.0.0)

Every call except login and the OAuth token endpoints needs an Authorization: Bearer <token> header. The API accepts two kinds of token:

Use an OAuth client when a backend service, pipeline or script works with the semantic layer without a person signed in.

Call the Semantic API with an OAuth client

1. An organization admin creates a client with POST /api/sys/org/oauth-clients, or from the OAuth clients tab of the organization settings. Copy the client secret straight away: Colrows shows it only once.

2. Exchange the client ID and secret for an access token:

   curl -X POST https://cloud.colrows.com/api/oauth/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d grant_type=client_credentials \
     -d scope=semantic:read
   

3. Call the Semantic API with the token until it expires after 15 minutes, then request a new one:

   curl https://cloud.colrows.com/api/consensus/metrics \
     -H "Authorization: Bearer $ACCESS_TOKEN"
   

The semantic scopes cover every semantic entity, including the ones this reference documents: business terms, metrics, semantic datasets, semantic tables, semantic columns, table relationships, category sets, semantic objects, semantic events, semantic actions, semantic relationships, semantic categories and verified queries. Each operation lists the scope it needs. Semantic tables and columns come from metadata scans, so a client can read and update them but not create or delete them. Semantic categories can be created and read, but not updated or deleted.

Role requirements on an operation apply to user sessions. An OAuth client acts as a curator in its organization, so the scope is all it needs: semantic:read-write is enough to create, update and delete the semantic entities on this page. Verified queries can't be run over the REST API; agents run them with the MCP executeVerifiedQuery tool.

A few semantic operations don't accept OAuth client tokens at any scope: column distinct counts and distinct values, which read data from your database, and the business term draft-validation and intent-assessment helpers.

No operation in this reference runs queries you write against your data; metric, dataset and category set operations read from the datasource only to check output columns and values. A client can also hold semantic:sql, sql:execute, data:query, data:sql, documents:read, memory:read or memory:write; these scopes apply only to the Agent API routes under /api/agents/v1, which this reference does not cover. To give an AI agent query access as a signed-in user, connect it through MCP; MCP tokens act for that user and apply the user's data access rules.

A token without the required scope gets 403 Forbidden. Revoking a client stops all of its tokens at once.

Manage data access and data masking policies

A client with access-control:read or access-control:read-write manages data access and data masking policies with no user account. These scopes use client credentials only: no user sign-in, consent page, callback URL, or authorization code. Create the client as Server-to-server in Administration → Settings → OAuth clients, then request a token with scope=access-control:read-write (or access-control:read). access-control:read-write includes read access, so the token does not need both scopes.

Data masking policies replace redaction policies: the routes moved from /api/redaction/* to /api/masking/*, and the old routes no longer exist. Both policy types use scope, subjects and typed rules; see the request schemas on each operation. Unknown fields are rejected with 400. All calls act in the client's organization and use the same services as the UI, and policy creation records the creator as oauth-client:<clientId>. A token that holds access-control:read-write acts with the Admin role; other client tokens act as Curator. User sessions still need the Admin role to change policies; authorization-code tokens cannot call these routes.

Successful calls return HTTP 200 with this envelope:

{
  "meta": { "ctime": "2026-09-27T10:15:30.123" },
  "result": { "status": "SUCCESS", "outcome": "RESOLVED" },
  "payload": { }
}

List calls may also include a pagination object. Errors return an HTTP 4xx or 5xx status with { "code": "...", "message": "..." }.

A few operations use their own format, described on each operation: login and token refresh return only payload, and the OAuth client and token endpoints return plain objects.

Sign in with a username and password to get a user session token, and refresh it before it expires.

Create, list and revoke OAuth clients: org-level credentials that let a backend service call the Semantic API without a user account. Only organization admins can manage them.

Exchange an OAuth client ID and secret for a 15-minute access token, and revoke tokens early.

Business vocabulary in the Consensus semantic layer.

Governed metric definitions in the Consensus semantic layer.