Docs/Developer/API reference

API reference

Complete REST API reference — authentication, endpoints, request and response formats, and examples.

WeaverReferenceUpdated May 2026 · 12 min read

✦

In this section

The Celiq REST API lets you query your semantic layer from any tool. Available on Team plan — create API keys in Lumen → API Keys.

The Celiq REST API lets you embed queries, manage the semantic model, and integrate Celiq data into your own applications. All endpoints require authentication via API key.

Authentication

All requests must include an Authorization header:

Authorization: Bearer <your_api_key>

Generate an API key in Admin Console → API keys → New key. Keys are workspace-scoped. You can create multiple keys with different permission scopes.

Base URL: https://api.celiq.co/v1

Queries

Run a query

Run a query against a node and return results as JSON.

POST /query

Request body:

json

{
  "node": "orders",
  "dimensions": ["status", "created_at.month"],
  "measures": ["total_revenue", "order_count"],
  "filters": [
    { "field": "created_at", "operator": ">=", "value": "2026-01-01" }
  ],
  "sorts": [{ "field": "total_revenue", "direction": "desc" }],
  "limit": 500
}

Field	Type	Required	Description
`node`	string	Yes	Node identifier to query.
`dimensions`	string[]	No	Dimension identifiers. Use `field.granularity` for date fields.
`measures`	string[]	No	Measure identifiers.
`filters`	object[]	No	Filter conditions.
`sorts`	object[]	No	Sort order.
`limit`	number	No	Max rows. Default 5000. Max 50000.

Response:

json

{
  "data": [
    { "status": "completed", "created_at.month": "2026-01", "total_revenue": 125000, "order_count": 480 },
    { "status": "refunded",  "created_at.month": "2026-01", "total_revenue": -8200,  "order_count": 31 }
  ],
  "sql": "SELECT ... FROM analytics.orders WHERE ...",
  "metadata": {
    "row_count": 24,
    "query_time_ms": 340,
    "node": "orders",
    "ran_at": "2026-05-21T08:15:30Z"
  }
}

Get available fields

Returns all dimensions and measures for a node.

GET /nodes/{node_id}/fields

Response:

json

{
  "node": "orders",
  "dimensions": [
    { "id": "order_id", "label": "Order ID", "type": "string" },
    { "id": "created_at", "label": "Created At", "type": "date" }
  ],
  "measures": [
    { "id": "total_revenue", "label": "Total Revenue", "type": "sum", "format": "currency" }
  ]
}

Nodes

List nodes

Returns all nodes in the Live semantic layer accessible to the authenticated key.

GET /nodes

Query parameters:

Parameter	Type	Description
`tags`	string	Filter by tag (comma-separated).
`connection`	string	Filter by data connection name.

Response:

json

{
  "nodes": [
    { "id": "orders", "label": "Orders", "description": "...", "tags": ["ecommerce"] },
    { "id": "customers", "label": "Customers", "description": "...", "tags": ["ecommerce"] }
  ]
}

Get node detail

GET /nodes/{node_id}

Returns full metadata for a single node including all fields, Data Keys, and join relationships.

Scenes

List Scenes

Returns Scenes accessible to the authenticated key (respects Vault membership).

GET /scenes

Get a Scene

GET /scenes/{scene_id}

Returns Scene metadata: name, Vault, node, dimensions, measures, filters, visualisation config.

Run a Scene

Re-runs the Scene's query and returns fresh results.

POST /scenes/{scene_id}/run

Response: Same format as POST /query.

Mosaics

List Mosaics

GET /mosaics

Get a Mosaic

GET /mosaics/{mosaic_id}

Returns Mosaic metadata including all tile definitions.

Users

List users (Luminary only)

GET /users

Get user

GET /users/{user_id}

Update user attributes (Data Key assignments)

PATCH /users/{user_id}/attributes

Request body:

json

{
  "region_access": "EMEA",
  "sales_rep_access": "rep_042"
}

This is the programmatic equivalent of Admin Console → Users → Attributes. Use this endpoint to sync Data Key assignments from your own identity provider.

Webhooks

Celiq can POST to your endpoint when certain events occur. Configure webhooks in Admin Console → Integrations → Webhooks.

Signal triggered

json

{
  "event": "signal.triggered",
  "signal_id": "sig_abc123",
  "signal_name": "Revenue below target",
  "triggered_at": "2026-05-21T07:00:00Z",
  "value": 42300,
  "threshold": 50000,
  "condition": "less_than"
}

Model deployed

json

{
  "event": "model.deployed",
  "deployed_at": "2026-05-20T14:23:11Z",
  "deployed_by": "alice@example.com",
  "changed_nodes": ["orders", "customers"],
  "pr_url": "https://github.com/org/repo/pull/42"
}

Error codes

Code	Meaning
`400`	Bad request — check your request body or parameters.
`401`	Missing or invalid API key.
`403`	The API key does not have permission for this action.
`404`	Resource not found.
`422`	CML validation error (for model write endpoints).
`429`	Rate limited — max 1000 requests per minute per workspace.
`500`	Internal server error. Contact support if this persists.