API docs by Redocly

Colrows (2.0.0)

Download OpenAPI specification:

The Colrows REST API manages users, groups and the Consensus semantic layer: business terms, metrics, semantic tables, semantic columns and verified queries.

All paths are relative to https://cloud.colrows.com.

Authentication

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

Token How to get it What it can call
User session token POST /api/user/login with a username and password Everything the user's role allows
OAuth client access token (cr_sem_at_…) POST /api/oauth/token with an OAuth client's ID and secret Only the operations its scopes cover

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"
Scope Grants
semantic:read Read every semantic entity in the Consensus semantic layer, including versions and lists
semantic:read-write Create, update and delete semantic entities; includes read
access-control:read List and get data access and data masking policies
access-control:read-write Read, create, update and delete data access and data masking policies; includes read

The semantic scopes cover every semantic entity, including the ones this reference documents: business terms, metrics, semantic tables, semantic columns 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.

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 verified queries, business terms and metrics. semantic:write is a legacy name for semantic:read-write: clients that already hold it keep working, but new clients and token requests must use semantic:read-write. 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 against your data. A client can also hold semantic:sql, sql:execute, data:query or data:sql; 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.

Method Data access policy route Data masking policy route Required scope
GET /api/access/list /api/masking/list access-control:read
GET /api/access/list/{policyId} /api/masking/get/{policyId} access-control:read
GET (none) /api/masking/list/{policyId}/{version} access-control:read
POST /api/access/create /api/masking/create access-control:read-write
PUT /api/access/update /api/masking/update access-control:read-write
DELETE /api/access/delete/{policyId} /api/masking/delete/{policyId} access-control:read-write

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.

Responses

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.

User Auth

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

Log in with username and password

Authenticates a user (native password, or a configured LDAP/OAuth/SAML realm) and opens a session. The response body is {payload: {...}} without the standard meta/result envelope; the access token and a refresh token are also set as HttpOnly cookies. When Turnstile is enabled on the server, turnstileToken must be supplied and valid.

Authorizations:
noauthAuth
Request Body schema: application/json
required

User credentials.

userName
required
string

User id (the user's email address). Lower-cased by the server; must not be null.

pwd
required
string <password>

User password. Trimmed by the server; must not be null. Never returned.

turnstileToken
string

Cloudflare Turnstile response token. Required only when the server has Turnstile verification enabled; ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "userName": "priya.sharma@example.com",
  • "pwd": "pa$$word",
  • "turnstileToken": "0.aBcD1234-turnstile-response"
}

Response samples

Content type
application/json
{
  • "payload": {
    }
}

Refresh the access token

Issues a new access token and rotates the refresh token. Send the CRrefresh cookie; if it is absent, a still-valid Bearer access token of an active user session is accepted to bootstrap a refresh session (OAuth client and MCP tokens are not accepted). The response body is {payload: {...}} without the standard envelope, and new CRtoken and CRrefresh cookies are set.

Authorizations:
bearerAuthnoauthAuth
cookie Parameters
CRrefresh
string
Example: CRrefresh=Zm9vYmFyLXJlZnJlc2gtdG9rZW4tZXhhbXBsZQ

Refresh token cookie set by login or a previous refresh (HttpOnly, Path=/api/user).

Responses

Response samples

Content type
application/json
{
  • "payload": {
    }
}

OAuth Clients

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.

Create an OAuth client

Creates an OAuth client (client ID and secret) for your organization. A backend service uses it to call the Semantic API without a user account.

Only organization admins can call this, with a user session token. OAuth client tokens are rejected.

The response contains clientSecret. This is the only time Colrows returns it: only a hash is stored, so copy it straight into your secret store. The response is sent with Cache-Control: no-store.

In the app, admins can do the same from the OAuth clients tab of the organization settings.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Display name for the client. Must not be blank. The app limits it to 100 characters.

scopes
required
Array of strings (OAuthScope) non-empty
Items Enum: "semantic:read" "semantic:read-write" "access-control:read" "access-control:read-write" "semantic:sql" "sql:execute" "data:query" "data:sql"

Scopes the client may request. At least one is required. Duplicates are removed.

expiresAt
required
integer <int64>

When the client stops working, in milliseconds since the Unix epoch. Must be in the future and no more than one year from now.

Responses

Request samples

Content type
application/json
{
  • "name": "Nightly metric sync",
  • "scopes": [
    ],
  • "expiresAt": 1822478400000
}

Response samples

Content type
application/json
{
  • "clientId": "cr_sem_client_Xq3v9bT2mK8pLw4nR7sD1fGh6jZ0aYcE5uVoNiQeWxA",
  • "clientSecret": "Jd8Kq2Lm5Np9Rs3Tv7Wx1Yz4Ab6Cd0Ef2Gh8Ij5Kl3M",
  • "name": "Nightly metric sync",
  • "scopes": [
    ],
  • "expiresAt": 1822478400000
}

List OAuth clients

Lists your organization's OAuth clients, including revoked and expired ones. Secrets are never returned. A legacy semantic:write scope is listed as semantic:read-write.

Any signed-in user of the organization can call this, with a user session token. OAuth client tokens are rejected.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Revoke an OAuth client

Revokes a client. From then on, the client can't get new access tokens, and any access tokens it already has stop working on their next request. The client stays in the list with active: false.

Only organization admins can call this, with a user session token.

Authorizations:
bearerAuth
path Parameters
clientId
required
string
Example: cr_sem_client_Xq3v9bT2mK8pLw4nR7sD1fGh6jZ0aYcE5uVoNiQeWxA

ID of the client to revoke.

Responses

Response samples

Content type
application/json
{
  • "code": "INSUFFICIENT_PRIVILEGE",
  • "message": "You do not have sufficient permissions to perform this operation."
}

OAuth Tokens

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

Get an access token (client credentials)

Exchanges an OAuth client's ID and secret for an access token, using the OAuth 2.0 client credentials grant. Send the ID and secret with HTTP Basic authentication: Authorization: Basic base64(clientId:clientSecret).

The access token starts with cr_sem_at_ and is valid for 15 minutes. Send it as Authorization: Bearer <access_token> to the Semantic API, and request a new one when it expires. No refresh token is issued for this grant.

The token acts inside the client's organization with curator-level permissions, or admin-level permissions when it holds access-control:read-write. Every call is still limited to the scopes the token was issued with.

This endpoint also serves the authorization_code and refresh_token grants that MCP clients use; those are covered in the MCP documentation.

Authorizations:
clientBasicAuth
Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "client_credentials"

Must be client_credentials.

scope
string

Optional. A space-separated subset of the client's scopes. If omitted, the token gets all of the client's scopes. An unsupported scope, including the legacy semantic:write, returns invalid_scope.

Responses

Response samples

Content type
application/json
{
  • "access_token": "cr_sem_at_N4pQ8sV2xY6zB1cD5fG9hJ3kL7mR0tW4uA8eI2oS6yU",
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "scope": "semantic:read semantic:read-write"
}

Revoke an access token

Revokes one access token before it expires. Authenticate with the same client's ID and secret over HTTP Basic. Tokens issued to other clients are left unchanged.

Authorizations:
clientBasicAuth
Request Body schema: application/x-www-form-urlencoded
required
token
required
string

The access token to revoke.

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_client",
  • "error_description": "Client credentials are invalid"
}

Business Terms

Business vocabulary in the Consensus semantic layer.

List business terms

Returns the organization's business terms. With personaId, returns the terms for that persona's semantic scope (the persona must exist in the organization). Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
query Parameters
personaId
string
Example: personaId=persona_finance

Persona ID. When blank or omitted, all business terms of the organization are returned.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ]
}

Create a business term

Creates a business term in organization scope, or a persona variant of an organization term. Requires the ADMIN or CURATOR role (OAuth clients act as CURATOR). Required scope for OAuth clients: semantic:read-write.

Authorizations:
bearerAuthoauthClientCredentials
Request Body schema: application/json
required
baseEntityId
string or null

Organization base term ID. Must be omitted for ORGANIZATION scope; required for PERSONA scope (must reference an organization-scoped term).

object or null

Defaults to ORGANIZATION when omitted.

label
required
string
description
required
string
synonyms
Array of strings or null unique
Array of objects or null (TableHint)

Each hint must resolve to an active Semantic Table.

dependencyTermIds
Array of strings or null

Active Business Term IDs; no duplicates, no self-reference, no cycles.

Array of objects or null (SemanticCategoryRef)

Responses

Request samples

Content type
application/json
{
  • "baseEntityId": "5f0c2a9e-7b1d-4c3e-9a51-2d8e6f1b0c47",
  • "semanticScope": {
    },
  • "label": "Net Revenue",
  • "description": "Gross order value minus refunds and discounts, in USD.",
  • "synonyms": [
    ],
  • "tableHints": [
    ],
  • "dependencyTermIds": [
    ],
  • "categories": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Get a business term

Returns the current version of a business term. Table hints missing a tableId are filled from the matching Semantic Table when one is found. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
termId
required
string
Example: 5f0c2a9e-7b1d-4c3e-9a51-2d8e6f1b0c47

Business Term ID.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Update a business term

Saves a new version of a business term. Send the same termId in the path and in the request body. Scope and base term cannot change. Requires the ADMIN or CURATOR role (OAuth clients act as CURATOR). Required scope for OAuth clients: semantic:read-write.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
termId
required
string
Example: 5f0c2a9e-7b1d-4c3e-9a51-2d8e6f1b0c47

Business Term ID.

Request Body schema: application/json
required
termId
required
string

ID of the term to update. This body field (not the path parameter) selects the term.

baseEntityId
string or null

Optional. If present it must match the existing baseEntityId.

object or null

Optional. If present it must match the existing scope; scope cannot change on update.

label
required
string
description
required
string
synonyms
Array of strings or null unique
Array of objects or null (TableHint)

Each hint must resolve to an active Semantic Table.

dependencyTermIds
Array of strings or null

Active Business Term IDs; no duplicates, no self-reference, no cycles.

Array of objects or null (SemanticCategoryRef)

When omitted/null, existing categories are kept.

Responses

Request samples

Content type
application/json
{
  • "termId": "5f0c2a9e-7b1d-4c3e-9a51-2d8e6f1b0c47",
  • "baseEntityId": "5f0c2a9e-7b1d-4c3e-9a51-2d8e6f1b0c47",
  • "semanticScope": {
    },
  • "label": "Net Revenue",
  • "description": "Gross order value minus refunds and discounts, in USD.",
  • "synonyms": [
    ],
  • "tableHints": [
    ],
  • "dependencyTermIds": [
    ],
  • "categories": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Delete a business term

Deletes a business term. Requires the ADMIN or CURATOR role (OAuth clients act as CURATOR). Required scope for OAuth clients: semantic:read-write.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
termId
required
string
Example: 5f0c2a9e-7b1d-4c3e-9a51-2d8e6f1b0c47

Business Term ID.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Get a business term version

Returns a specific version of a business term. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
termId
required
string
Example: 5f0c2a9e-7b1d-4c3e-9a51-2d8e6f1b0c47

Business Term ID.

version
required
integer <int32>
Example: 2

Business term version number.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Metrics

Governed metric definitions in the Consensus semantic layer.

List metrics

Returns the organization's metrics. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ]
}

Create a metric

Creates a metric after validating its business terms, grain, examples and SQL against the datasource. Requires the ADMIN or CURATOR role (OAuth clients act as CURATOR). Required scope for OAuth clients: semantic:read-write.

Authorizations:
bearerAuthoauthClientCredentials
Request Body schema: application/json
required
baseEntityId
string or null

Organization base entity ID. For ORGANIZATION scope it may be omitted (defaults to the metric ID).

object or null

Defaults to ORGANIZATION when omitted.

datasourceId
required
string
label
required
string
description
required
string
synonyms
Array of strings or null
Array of objects or null (SemanticCategoryRef)
businessTermIds
Array of strings or null

Business Terms that ground this metric. Unique, active IDs.

required
object (MetricGrain)
required
object (MetricComputation)
guidance
Array of strings or null
Array of objects or null (MetricUsageExample)

Responses

Request samples

Content type
application/json
{
  • "baseEntityId": "string",
  • "semanticScope": {
    },
  • "datasourceId": "ds_7f3a91c2",
  • "label": "Net Revenue",
  • "description": "Order revenue net of refunds, per day and region.",
  • "synonyms": [
    ],
  • "categories": [
    ],
  • "businessTermIds": [
    ],
  • "grain": {
    },
  • "computation": {
    },
  • "guidance": [
    ],
  • "examples": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Get a metric

Returns the current version of a metric. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
metricId
required
string
Example: c7d2e1f0-4a8b-4b6c-9d3e-5f1a2b3c4d5e

Metric ID.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Update a metric

Saves a new version of a metric, re-validating its definition and SQL. Use expectedVersion for optimistic concurrency. Requires the ADMIN or CURATOR role (OAuth clients act as CURATOR). Required scope for OAuth clients: semantic:read-write.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
metricId
required
string
Example: c7d2e1f0-4a8b-4b6c-9d3e-5f1a2b3c4d5e

Metric ID.

Request Body schema: application/json
required
baseEntityId
string or null

Organization base entity ID. For ORGANIZATION scope it may be omitted (defaults to the metric ID).

object or null

Defaults to ORGANIZATION when omitted.

datasourceId
required
string
label
required
string
description
required
string
synonyms
Array of strings or null
Array of objects or null (SemanticCategoryRef)

When omitted/null, existing categories are kept.

businessTermIds
Array of strings or null

Business Terms that ground this metric. Unique, active IDs.

required
object (MetricGrain)
required
object (MetricComputation)
guidance
Array of strings or null
Array of objects or null (MetricUsageExample)
expectedVersion
integer or null <int32> >= 1

Version the editor loaded. Must be positive; if it differs from the latest version the request fails with 409. When omitted the latest version is used.

Responses

Request samples

Content type
application/json
{
  • "baseEntityId": "string",
  • "semanticScope": {
    },
  • "datasourceId": "ds_7f3a91c2",
  • "label": "Net Revenue",
  • "description": "Order revenue net of refunds, per day and region.",
  • "synonyms": [
    ],
  • "categories": [
    ],
  • "businessTermIds": [
    ],
  • "grain": {
    },
  • "computation": {
    },
  • "guidance": [
    ],
  • "examples": [
    ],
  • "expectedVersion": 3
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Delete a metric

Deletes a metric. Requires the ADMIN or CURATOR role (OAuth clients act as CURATOR). Required scope for OAuth clients: semantic:read-write.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
metricId
required
string
Example: c7d2e1f0-4a8b-4b6c-9d3e-5f1a2b3c4d5e

Metric ID.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Get a metric version

Returns a specific version of a metric. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
metricId
required
string
Example: c7d2e1f0-4a8b-4b6c-9d3e-5f1a2b3c4d5e

Metric ID.

version
required
integer <int32>
Example: 2

Metric version number.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Get metric output columns

Returns the output columns of the metric's resolved SQL as reported by the datasource. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
metricId
required
string
Example: c7d2e1f0-4a8b-4b6c-9d3e-5f1a2b3c4d5e

Metric ID.

version
required
integer <int32>
Example: 2

Metric version number.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ]
}

Semantic Tables

Semantic descriptions of the tables in a datasource.

Get a semantic table

Returns the current semantic table entity by ID. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
tableId
required
string
Example: 7f3c2a9e-5b1d-4c8e-9a6f-2d4e8b1c0a37

Semantic table ID.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Update a semantic table

Updates the table description and row definition and returns the updated entity. Only organization scope is accepted. Requires the ADMIN or CURATOR role (OAuth clients act as CURATOR). Required scope for OAuth clients: semantic:read-write.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
tableId
required
string
Example: 7f3c2a9e-5b1d-4c8e-9a6f-2d4e8b1c0a37

Semantic table ID.

Request Body schema: application/json
required
description
string or null

New table description.

rowDefinition
string or null

What one physical row represents.

baseEntityId
string or null

Organization entity ID. Ignored for organization scope (reset to the entity's own ID when blank).

object or null

Semantic scope. Omitted means ORGANIZATION; PERSONA is rejected with 400.

Responses

Request samples

Content type
application/json
{
  • "description": "One record per customer order placed through the web store.",
  • "rowDefinition": "One customer order",
  • "baseEntityId": null,
  • "semanticScope": {
    }
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Get a semantic table version

Returns a specific version of a semantic table. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
tableId
required
string
Example: 7f3c2a9e-5b1d-4c8e-9a6f-2d4e8b1c0a37

Semantic table ID.

version
required
integer <int32>
Example: 2

Table version number.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

List semantic tables for a datasource

Returns summaries of all semantic tables in a datasource; an empty array when there are none. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
datasourceId
required
string
Example: ds_5f8a2c1e9b7d

Datasource ID.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ]
}

List schemas for a datasource

Returns the distinct schemas that have semantic tables in a datasource, sorted by name. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
datasourceId
required
string
Example: ds_5f8a2c1e9b7d

Datasource ID.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ]
}

List tables in a schema

Returns the semantic tables in one schema of a datasource, sorted by table name; an empty array when none match. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
datasourceId
required
string
Example: ds_5f8a2c1e9b7d

Datasource ID.

schema
required
string
Example: sales

Schema name.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ]
}

Semantic Columns

Semantic descriptions of columns, including nested columns.

Get a semantic column

Returns the current semantic column entity by ID. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
columnId
required
string
Example: c41e9b2a-8d73-4f15-b6a0-3e9d2c7f5a18

Semantic column ID.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Update a semantic column

Updates a column's description, LLM description flag and value search flag and returns the updated entity. Only organization scope is accepted; a PERSONA scope returns 400. Requires the ADMIN or CURATOR role (OAuth clients act as CURATOR). Required scope for OAuth clients: semantic:read-write.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
columnId
required
string
Example: c41e9b2a-8d73-4f15-b6a0-3e9d2c7f5a18

Semantic column ID.

Request Body schema: application/json
required
description
string or null

New column description.

useDescriptionForLlm
boolean or null

Whether the description may be included in LLM context. Unchanged when null.

valueSearchEnabled
boolean or null

Enable value search. true is rejected (currently as a 500 error) when the column hierarchy is not accessible. Unchanged when null.

baseEntityId
string or null

Organization entity ID. Ignored for organization scope (reset to the entity's own ID when blank).

object or null

Semantic scope. Omitted means ORGANIZATION; PERSONA is rejected with 400.

Responses

Request samples

Content type
application/json
{
  • "description": "Current fulfilment status of the order.",
  • "useDescriptionForLlm": true,
  • "valueSearchEnabled": true,
  • "baseEntityId": null,
  • "semanticScope": {
    }
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Get a semantic column version

Returns a specific version of a semantic column. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
columnId
required
string
Example: c41e9b2a-8d73-4f15-b6a0-3e9d2c7f5a18

Semantic column ID.

version
required
integer <int32>
Example: 2

Column version number.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

List nested fields of a column

Returns the nested fields under a complex root column (ARRAY, MAP or ROW). Returns 404 when the root column does not exist. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
columnId
required
string
Example: a92d5e17-3c48-4b6f-8e21-7d0c4f9b6e53

Root semantic column ID.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ]
}

List semantic columns for a datasource

Returns summaries of all semantic columns in a datasource; an empty array when there are none. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
datasourceId
required
string
Example: ds_5f8a2c1e9b7d

Datasource ID.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ]
}

List columns in a table

Returns the semantic columns of one table, sorted by column name; an empty array when the table is unknown. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
datasourceId
required
string
Example: ds_5f8a2c1e9b7d

Datasource ID.

schema
required
string
Example: sales

Schema name.

tableName
required
string
Example: orders

Table name.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ]
}

Update a nested column field

Updates a nested field under a complex root column and returns the updated field. Returns 404 when the root or the field is missing or the field does not belong to the root. Requires the ADMIN or CURATOR role (OAuth clients act as CURATOR). Required scope for OAuth clients: semantic:read-write.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
rootColumnId
required
string
Example: a92d5e17-3c48-4b6f-8e21-7d0c4f9b6e53

Root semantic column ID.

fieldId
required
string
Example: c41e9b2a-8d73-4f15-b6a0-3e9d2c7f5a18

Nested field (semantic column) ID.

Request Body schema: application/json
required
description
string or null

New field description.

useDescriptionForLlm
boolean or null

Whether the description may be included in LLM context.

categorySetId
string or null

Category set to link (must belong to the root column's datasource). Empty string removes the link and sets categoryDecision to UNKNOWN; a non-empty value sets it to CONFIRMED.

valueSearchEnabled
boolean or null

Enable value search. true is rejected (400) unless the field is a string field with a complete hierarchy.

Responses

Request samples

Content type
application/json
{
  • "description": "City of the shipping address.",
  • "useDescriptionForLlm": true,
  • "categorySetId": "cs_2d9f7a1e4c6b",
  • "valueSearchEnabled": false
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Verified Queries

Create and manage curator-approved, read-only SQL queries, each paired with the question it answers and optional typed parameters. OAuth clients can call them with the semantic:read and semantic:read-write scopes. Agents find and run verified queries with the searchVerifiedQueries, getVerifiedQuery and executeVerifiedQuery tools over MCP.

Create a verified query

Saves a new read-only SQL query as version 1 after checking the SQL, schema and parameter definitions against the datasource. A missing or blank label, description, query or datasourceId returns 400. Invalid SQL, a schema mismatch or an invalid parameter definition also returns 400, with a message starting "Invalid verified query:" that gives the reason; an unknown datasource returns 404. Requires the ADMIN or CURATOR role (OAuth clients act as CURATOR). Required scope for OAuth clients: semantic:read-write.

Authorizations:
bearerAuthoauthClientCredentials
Request Body schema: application/json
required
label
required
string non-empty

Short name. Must not be blank.

description
required
string non-empty

Main question or scenario. Must not be blank.

query
required
string non-empty

Exactly one read-only SELECT (WITH, UNION, INTERSECT, EXCEPT and ORDER BY are allowed). Use :name placeholders; positional ? markers are not allowed when parameters are declared. Placeholders inside strings and comments are ignored.

datasourceId
required
string non-empty

Datasource that runs the query. It must exist.

schema
string or null

Default schema. Required when no table in the SQL is schema-qualified; must match when the SQL references exactly one schema; must be omitted when the SQL references several schemas.

alternativeQuestions
Array of strings

Other phrasings that help search find the query.

Array of objects (VerifiedQueryParameter) <= 20 items

One definition for each distinct :name placeholder, at most 20. Duplicate names, unused definitions and undeclared placeholders are rejected.

Array of objects (VerifiedQueryCategoryRef)

Semantic category references.

object

Defaults to organization scope when omitted.

baseEntityId
string

For a persona variant, the ID of the organization query it varies. Ignored for organization scope, which uses the query's own ID.

Responses

Request samples

Content type
application/json
{
  • "label": "Revenue for a region after a date",
  • "description": "What is the revenue for a region from a given date?",
  • "alternativeQuestions": [
    ],
  • "datasourceId": "sales-prod",
  • "schema": "public",
  • "query": "SELECT SUM(revenue) AS total_revenue FROM sales WHERE region = :region AND sale_date >= :from_date",
  • "parameters": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    },
  • "pagination": null
}

Get a verified query

Returns the latest version of a verified query. A query marked invalid returns 404; a deleted query returns its deletion version with deleted set to true. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
queryId
required
string
Example: 8f3c2a1e-5b7d-4c9a-9e21-6d4f0b7a3c55

Verified query ID.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    },
  • "pagination": null
}

Update a verified query

Saves a new version from the complete definition in the body; the query ID comes from the URL. A missing or blank label or description, or a missing query or datasourceId, returns 400. Invalid SQL, a schema mismatch or an invalid parameter definition also returns 400, with a message starting "Invalid verified query:" that gives the reason. An unknown or deleted query ID, or an unknown datasource, returns 404. Requires the ADMIN or CURATOR role (OAuth clients act as CURATOR). Required scope for OAuth clients: semantic:read-write.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
queryId
required
string
Example: 8f3c2a1e-5b7d-4c9a-9e21-6d4f0b7a3c55

Verified query ID.

Request Body schema: application/json
required
label
required
string non-empty

Short name. Must not be blank.

description
required
string non-empty

Main question or scenario. Must not be blank.

query
required
string non-empty

Exactly one read-only SELECT (WITH, UNION, INTERSECT, EXCEPT and ORDER BY are allowed). Use :name placeholders; positional ? markers are not allowed when parameters are declared. Placeholders inside strings and comments are ignored.

datasourceId
required
string non-empty

Datasource that runs the query. It must exist.

schema
string or null

Default schema. Required when no table in the SQL is schema-qualified; must match when the SQL references exactly one schema; must be omitted when the SQL references several schemas.

alternativeQuestions
Array of strings

Full list for the new version. Omitting it clears the alternative questions.

Array of objects (VerifiedQueryParameter) <= 20 items

Full parameter list for the new version, at most 20. Omit to keep the current definitions; send [] to remove all.

Array of objects (VerifiedQueryCategoryRef)

Full list for the new version. Omit to keep the current categories.

object

Defaults to organization scope when omitted.

baseEntityId
string

For a persona variant, the ID of the organization query it varies. Ignored for organization scope, which uses the query's own ID.

queryId
string

Ignored; the ID in the URL is used.

Responses

Request samples

Content type
application/json
{
  • "label": "Revenue for a region after a date",
  • "description": "What is the revenue for a region from a given date?",
  • "alternativeQuestions": [
    ],
  • "datasourceId": "sales-prod",
  • "schema": "public",
  • "query": "SELECT SUM(revenue) AS total_revenue FROM sales WHERE region = :region AND sale_date >= :from_date AND channel <> 'internal'",
  • "parameters": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    },
  • "pagination": null
}

Delete a verified query

Deletes a verified query by recording a new, deleted version; earlier versions stay readable by version number. Requires the ADMIN or CURATOR role (OAuth clients act as CURATOR). Required scope for OAuth clients: semantic:read-write.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
queryId
required
string
Example: 8f3c2a1e-5b7d-4c9a-9e21-6d4f0b7a3c55

Verified query ID.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    },
  • "pagination": null
}

Get a verified query version

Returns one version of a verified query, including versions that are no longer current, invalid or deleted. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
queryId
required
string
Example: 8f3c2a1e-5b7d-4c9a-9e21-6d4f0b7a3c55

Verified query ID.

version
required
integer <int32>
Example: 1

Version number.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    },
  • "pagination": null
}

Get parameter Catalog columns

Returns, for each parameter, the Catalog column IDs that the saved SQL compares it with; the server works these out when the query is saved. Omit version to use the latest version. Required scope for OAuth clients: semantic:read.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
queryId
required
string
Example: 8f3c2a1e-5b7d-4c9a-9e21-6d4f0b7a3c55

Verified query ID.

query Parameters
version
integer <int32>
Example: version=2

Version number; defaults to the latest version.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    },
  • "pagination": null
}

Data Access Policies

Table, column and row access policies, with optional attribute-based (ABAC) conditions. Client credentials: access-control:read to read, access-control:read-write to change.

A policy has a scope (datasource and schema), subjects (user and group IDs) and a set of rules. Each rule has a ruleType: TABLE rules select a table by name, PATTERN rules select tables by regular expression. Each rule has an effect of ALLOW or DENY. A rule can carry an attribute condition, and a TABLE rule can also carry SQL rowConditions and a typed attribute rowFilter. Attribute names used in conditions must be defined first with the Authorization Attributes operations.

Leave both subjects.userIds and subjects.groupIds empty to select users by attributes only. Such a policy applies only when every rule has a condition or a rowFilter.

Datasource gate: restrictedAccess. Access policies are enforced only on datasources whose restrictedAccess flag is true. New datasources start with it off (false), so an admin must turn on Restricted Access (Administration → Connections, or restrictedAccess: true on the datasource API) before any policy takes effect. On an unrestricted datasource, Colrows skips access checks and row predicates entirely.

List access policies

Returns the organization's active access policies. Deleted policies are not listed. Required scope for OAuth clients: access-control:read (or access-control:read-write, which includes read).

Authorizations:
bearerAuthoauthClientCredentials

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ]
}

Get an access policy

Returns one access policy by ID, including a deleted one (active: false). Required scope for OAuth clients: access-control:read (or access-control:read-write, which includes read).

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
policyId
required
string
Example: 8f14e45f-ceea-467f-a8f5-2b1c6f0e2d3a

ID of the access policy.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Create an access policy

Creates an access policy at revision 1. Required scope for OAuth clients: access-control:read-write. User sessions need the ADMIN role.

Authorizations:
bearerAuthoauthClientCredentials
Request Body schema: application/json
required
name
required
string

Display name. Must not be blank, and must not match the name of another policy of the same type, including a deleted one.

description
string

Optional description.

required
object (PolicyScope)

Where the policy applies. Unknown fields are rejected.

required
object (PolicySubjects)

Users and groups the policy applies to. Both sets default to empty; blank IDs are rejected. Unknown fields are rejected.

required
Array of any (AccessRule) non-empty

Rules of the policy. At least one is required.

Responses

Request samples

Content type
application/json
{
  • "name": "Sales readers",
  • "description": "Read sales data and exclude confidential rows.",
  • "scope": {
    },
  • "subjects": {
    },
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Update an access policy

Replaces the definition of an active access policy and increases its revision. Send the policyId in the body. A missing or deleted policy returns 404. Required scope for OAuth clients: access-control:read-write. User sessions need the ADMIN role.

Authorizations:
bearerAuthoauthClientCredentials
Request Body schema: application/json
required
policyId
required
string

ID of the policy to update.

name
required
string

Display name. Must not be blank, and must not match the name of another policy of the same type, including a deleted one.

description
string

Optional description.

required
object (PolicyScope)

Where the policy applies. Unknown fields are rejected.

required
object (PolicySubjects)

Users and groups the policy applies to. Both sets default to empty; blank IDs are rejected. Unknown fields are rejected.

required
Array of any (AccessRule) non-empty

Rules of the policy. At least one is required.

Responses

Request samples

Content type
application/json
{
  • "policyId": "8f14e45f-ceea-467f-a8f5-2b1c6f0e2d3a",
  • "name": "Sales readers",
  • "description": "Read sales data and exclude confidential rows.",
  • "scope": {
    },
  • "subjects": {
    },
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Delete an access policy

Deletes an access policy by marking it inactive and increasing its revision. A missing or already deleted policy returns 404. Required scope for OAuth clients: access-control:read-write. User sessions need the ADMIN role.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
policyId
required
string
Example: 8f14e45f-ceea-467f-a8f5-2b1c6f0e2d3a

ID of the access policy to delete.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Data Masking Policies

Data masking policies (formerly redaction policies), served under /api/masking. The old /api/redaction/* routes no longer exist. Client credentials: access-control:read to read, access-control:read-write to change.

A policy has a scope (datasource and schema), subjects (user and group IDs) and a set of rules. Each rule selects columns with a TABLE or PATTERN resource selector and masks them with a strategy: FULL, KEEP_PREFIX or KEEP_SUFFIX. A masking policy applies only to the users and groups in its subjects.

Each policy is stored as one record. Updates and deletes increase its revision; earlier revisions are not kept.

Datasource gate: restrictedAccess. Data masking policies are enforced only on datasources whose restrictedAccess flag is true. New datasources start with it off (false), so an admin must turn on Restricted Access (Administration → Connections, or restrictedAccess: true on the datasource API) before any policy takes effect. On an unrestricted datasource, Colrows skips masking entirely.

List data masking policies

Returns all of the organization's data masking policies, including deleted ones (active: false). Required scope for OAuth clients: access-control:read (or access-control:read-write, which includes read).

Authorizations:
bearerAuthoauthClientCredentials

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ]
}

Get a data masking policy

Returns one data masking policy by ID, as an array with one element. An unknown ID returns an empty array, not 404. Required scope for OAuth clients: access-control:read (or access-control:read-write, which includes read).

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
policyId
required
string
Example: 8f14e45f-ceea-467f-a8f5-2b1c6f0e2d3a

ID of the data masking policy.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ]
}

Get a data masking policy at a revision

Returns a data masking policy, as an array with one element, only when its current revision equals version. Earlier revisions are not stored, so any other version returns 404. Required scope for OAuth clients: access-control:read (or access-control:read-write, which includes read).

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
policyId
required
string
Example: 8f14e45f-ceea-467f-a8f5-2b1c6f0e2d3a

ID of the data masking policy.

version
required
integer
Example: 2

Expected current revision of the policy.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ]
}

Create a data masking policy

Creates a data masking policy at revision 1. Required scope for OAuth clients: access-control:read-write. User sessions need the ADMIN role.

Authorizations:
bearerAuthoauthClientCredentials
Request Body schema: application/json
required
name
required
string

Display name. Must not be blank, and must not match the name of another policy of the same type, including a deleted one.

description
string

Optional description.

required
object (PolicyScope)

Where the policy applies. Unknown fields are rejected.

required
object (PolicySubjects)

Users and groups the policy applies to. Both sets default to empty; blank IDs are rejected. Unknown fields are rejected.

required
Array of any (MaskingRule) non-empty

Rules of the policy. At least one is required.

Responses

Request samples

Content type
application/json
{
  • "name": "Customer contact masks",
  • "scope": {
    },
  • "subjects": {
    },
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Update a data masking policy

Replaces the definition of an active data masking policy and increases its revision. Send the policyId in the body. A missing or deleted policy returns 404. Required scope for OAuth clients: access-control:read-write. User sessions need the ADMIN role.

Authorizations:
bearerAuthoauthClientCredentials
Request Body schema: application/json
required
policyId
required
string

ID of the policy to update.

name
required
string

Display name. Must not be blank, and must not match the name of another policy of the same type, including a deleted one.

description
string

Optional description.

required
object (PolicyScope)

Where the policy applies. Unknown fields are rejected.

required
object (PolicySubjects)

Users and groups the policy applies to. Both sets default to empty; blank IDs are rejected. Unknown fields are rejected.

required
Array of any (MaskingRule) non-empty

Rules of the policy. At least one is required.

Responses

Request samples

Content type
application/json
{
  • "policyId": "8f14e45f-ceea-467f-a8f5-2b1c6f0e2d3a",
  • "name": "Customer contact masks",
  • "scope": {
    },
  • "subjects": {
    },
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Delete a data masking policy

Deletes a data masking policy by marking it inactive and increasing its revision. A missing or already deleted policy returns 400 (INVALID_REQUEST). Required scope for OAuth clients: access-control:read-write. User sessions need the ADMIN role.

Authorizations:
bearerAuthoauthClientCredentials
path Parameters
policyId
required
string
Example: 8f14e45f-ceea-467f-a8f5-2b1c6f0e2d3a

ID of the data masking policy to delete.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Authorization Attributes

Define the attributes that access policy conditions use, and set their values for users, tables and columns (attribute-based access control). These operations need a user session with the ADMIN role; OAuth client tokens are rejected.

Every write carries the revision you read and fails with 400 if the record changed since. Values from LDAP, SAML or OIDC sign-in are set by the identity provider through the schema mappings, not through this API.

Get the authorization schema

Returns the organization's attribute definitions and identity-provider mappings. When none has been saved, returns an empty schema with revision 0. Requires the ADMIN role and a user session token; OAuth client tokens are rejected.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Replace the authorization schema

Replaces all attribute definitions and mappings. Send the revision you read; the saved schema has the next revision. Attributes must be defined here before access policy conditions can reference them. Requires the ADMIN role and a user session token; OAuth client tokens are rejected.

Authorizations:
bearerAuth
Request Body schema: application/json
required
revision
required
integer <int64> >= 0

The revision you read. Use 0 when no schema exists yet.

required
Array of objects (AttributeDefinition) <= 256 items
required
Array of objects (IdentityAttributeMapping) <= 256 items

Responses

Request samples

Content type
application/json
{
  • "revision": 0,
  • "mappings": [ ],
  • "definitions": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Get a user's attributes

Returns a user's attribute values from every source, with the current revision. A user outside your organization returns 400. Requires the ADMIN role and a user session token; OAuth client tokens are rejected.

Authorizations:
bearerAuth
path Parameters
userId
required
string
Example: rahul.verma@example.com

User ID.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

Replace a user's admin attributes

Replaces all of a user's ADMIN attribute values. Values from LDAP, SAML or OIDC are kept and cannot be set here. Each value must match its definition's type and allowed values. Requires the ADMIN role and a user session token; OAuth client tokens are rejected.

Authorizations:
bearerAuth
path Parameters
userId
required
string
Example: rahul.verma@example.com

User ID.

Request Body schema: application/json
required
revision
required
integer <int64> >= 0

The revision you read.

required
object <= 256 properties

The complete set of ADMIN values, by attribute name. Each name must be a SUBJECT attribute with source ADMIN. An empty object removes all ADMIN values.

Responses

Request samples

Content type
application/json
{
  • "revision": 0,
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

List resource attributes

Returns every table and column attribute record for a datasource. Requires the ADMIN role and a user session token; OAuth client tokens are rejected.

Authorizations:
bearerAuth
path Parameters
datasourceId
required
string
Example: ds_sales

Datasource ID.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ]
}

Save resource attributes

Creates or replaces the attribute record for one table or column. The table and column must exist in the datasource. Send revision 0 for a new record, or the revision you read. Requires the ADMIN role and a user session token; OAuth client tokens are rejected.

Authorizations:
bearerAuth
Request Body schema: application/json
required
datasourceId
required
string
schema
required
string
table
required
string
column
string

Optional. Omit for a table record; must not be blank when present.

revision
required
integer <int64> >= 0

In a request, the revision you read (0 for a new record). In a response, the new revision.

required
object <= 256 properties

Values by attribute name. Each name must be a RESOURCE attribute. An empty object clears the record.

Responses

Request samples

Content type
application/json
{
  • "datasourceId": "ds_sales",
  • "schema": "public",
  • "table": "orders",
  • "revision": 0,
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    }
}

User Management

Create, list, update and deactivate users in your organization.

Create a native user

Creates an active native (password) user in the caller's organization; the email becomes the user id. Requires a user session token and the ADMIN role.

Authorizations:
bearerAuth
Request Body schema: application/json
required

New user details.

name
required
string

Display name. Must not be null.

email
required
string <email>

Email address; lower-cased and also used as the new user's userId. Must not be null and must not already exist.

secret
required
string <password>

Initial password for the native user. Must not be null. Stored hashed; never returned.

Responses

Request samples

Content type
application/json
{
  • "name": "Ananya Iyer",
  • "email": "ananya.iyer@example.com",
  • "secret": "pa$$word"
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    },
  • "pagination": null
}

List users

Returns all users of the caller's organization, including deactivated ones. Requires a user session token; any role can call it.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ],
  • "pagination": null
}

Update a user's name

Changes the display name of a native user. Send the user's current email in email; it is not changed. Non-native (LDAP/OAuth/SAML) users cannot be updated. Requires a user session token and the ADMIN role.

Authorizations:
bearerAuth
Request Body schema: application/json
required

User to update and the new name.

userId
required
string

Id of the user to update (lower-cased by the server). Must not be null.

name
required
string

New display name. Must not be null. This is the only attribute the server actually changes.

email
required
string <email>

Must not be null (validated), but is ignored: the user's email is not changed.

Responses

Request samples

Content type
application/json
{
  • "userId": "ananya.iyer@example.com",
  • "name": "Ananya Iyer Rao",
  • "email": "ananya.iyer@example.com"
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    },
  • "pagination": null
}

Deactivate a user

Marks the user inactive and ends all of the user's sessions; the record is not deleted. Requires a user session token and the ADMIN role.

Authorizations:
bearerAuth
path Parameters
userId
required
string
Example: ananya.iyer@example.com

Id of the user to deactivate (lower-case email address; not normalized by the server).

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    },
  • "pagination": null
}

User Group Management

Create, list, update and deactivate user groups.

Create a user group

Creates an active user group with the given members; the caller is recorded as creator but is not added as a member. Requires a user session token; any role can call it.

Authorizations:
bearerAuth
Request Body schema: application/json
required

Group name and members.

groupName
required
string <= 64 characters

Group name. Must not be null; at most 64 characters.

memberIds
required
Array of strings non-empty unique

User ids of the group members. Must be present and non-empty (the requester is not added automatically).

Responses

Request samples

Content type
application/json
{
  • "groupName": "Finance Analysts",
  • "memberIds": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    },
  • "pagination": null
}

Update a user group

Renames a group and replaces its full member list. Requires a user session token; any role can call it.

Authorizations:
bearerAuth
Request Body schema: application/json
required

Group id, new name and complete member list.

groupId
required
string

Id of the group to update. Must not be blank.

groupName
required
string <= 64 characters

New group name. Must not be blank; at most 64 characters.

memberIds
required
Array of strings non-empty unique

Complete new member list (replaces the existing members). Must be present and non-empty.

Responses

Request samples

Content type
application/json
{
  • "groupId": "5b1e2d7c-9a44-4f3e-8c1d-2e6f0a9b7c31",
  • "groupName": "Finance Analysts EMEA",
  • "memberIds": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    },
  • "pagination": null
}

List user groups

Returns all user groups of the caller's organization, including deactivated ones, with creator and members resolved to user references. Requires a user session token; any role can call it.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": [
    ],
  • "pagination": null
}

Deactivate a user group

Marks the user group inactive; the record is not deleted. Requires a user session token and the ADMIN role.

Authorizations:
bearerAuth
path Parameters
groupId
required
string
Example: 5b1e2d7c-9a44-4f3e-8c1d-2e6f0a9b7c31

Id of the group to deactivate.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "result": {
    },
  • "payload": {
    },
  • "pagination": null
}