REST API overview

Everything the DataSquares UI does goes through the REST API, and a curated developer subset of it is documented here — the endpoint groups you need to integrate, automate, and embed. All endpoints live under /api/ on your DataSquares host and speak JSON.

Authentication

Requests carry a bearer token:

curl https://<your-datasquares-host>/api/dashboards \
  -H "Authorization: Bearer <token>"

Two ways to get one:

• API keys — for integrations. Create one under Settings → API keys with a scope (read, read/write, or admin) and send it in the X-API-Key header, not as a bearer token. The key is shown once at creation.

  curl https://<your-datasquares-host>/api/dashboards \n    -H "X-API-Key: <key>"

• Session tokens — sign in via the Auth endpoints with user credentials; you’ll receive the same JWT the web app uses.

Permissions follow the caller. A user token follows the user’s role. An API key can do only what its scope names and what its owner’s role allows at that moment: it narrows its owner’s access and never widens it, and a role change reaches the key at once. Row-level security applies to a key exactly as it does to its owner: a key reads only the rows its owner may read.

Scopes: read covers viewing and read-only queries; write covers creating, changing and deleting; admin covers both. An integration may instead name what it needs, such as source:read, dashboard:write or query:execute.

No scope lets a key use AI: AI features are available in the DataSquares app only. A route that runs AI for someone signed in answers an API key 403 with “AI features are available in the DataSquares app; API keys can’t use them.”, whatever the key’s scopes, admin included. That covers the AI chat, Summarize with AI, rebuilding the semantic index and every other AI action. The rest of the AI chat refuses a key the same way, though it runs no AI: its conversations (listing, searching, reading, renaming, pinning, deleting, forking, exporting and rating them) and the workspace’s AI settings, tools, quota, usage, audit log, feedback trends and escalations. Those endpoints are the app’s, so this reference doesn’t list them. On the pages it does list, each endpoint that always runs AI for someone signed in, such as Summarize with AI, is marked App only with the 403 a key gets, and so is reporting content for review. So is each of Prep for AI’s endpoints for the AI’s notes about a model’s tables and for Explore this model, though reading and deciding the notes and stopping an exploration run no AI: they are the app’s, as the AI chat’s conversations are. A share’s public Ask AI (POST /api/shares/{token}/chat) has no mark: it runs AI for anyone who has the share’s link, with no sign-in, takes the link rather than a key, and answers only while Ask AI is on for the share. An embedded person’s Ask AI is the same endpoint with the session their page swapped a signed token for (Embed dashboards for each person): it takes the session, not a key, and the session, not a key, reads their conversations (GET /api/shares/{token}/conversations and one of them). Embed apps and their embedded use (GET /api/embed-apps/usage, which counts AI credits but runs no AI) need a company admin signed in, so a key is refused them. GET /api/glossary/suggestions (Suggest terms to define) is a plain count: it calls no AI and uses no AI credits, so a key reads it as it reads the glossary. Other endpoints can refuse a key without the mark, such as the SSO settings and webhooks, which need a company admin signed in. A key can’t be created with an AI scope such as ai_chat:view, and a key that already holds one is refused all the same. Where AI is an optional step, a key gets the route without it:

• Explain this change, on a card (POST /api/ai/explain) or a metric (POST /api/ai/explain-metric), returns its statistical breakdown; asking for the AI summary (ai: true) is refused.
• Analyze (anomalies, key influencers, forecast) returns its statistics; asking for the narrative (options.phrase) is refused.
• A report comparison and a story’s analysis review return their calculated evidence; asking for the AI summary or proposal (ai: true) is refused.
• Semantic search answers from its spelling and glossary lane.
• A data-quality profiling scan keeps its rule-based findings; asking for the AI findings (aiFindings: true) is refused.
• A metric digest sent now keeps its standard sentences, and a key can’t turn a digest’s AI sentences on (aiSentences: true is refused), so a digest a key creates is sent on schedule with its standard sentences unless its owner turns AI sentences on in the app. A key can’t change a digest whose AI sentences are on at all (403), turning them off included: it is changed in the app, and a key can change it again once someone signed in has turned its AI sentences off.
• A key can turn a share’s Ask AI off, but not on (allowAi: true is refused).

Conventions

• List endpoints paginate with limit and offset query parameters.
• Errors return conventional status codes (400 validation, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict) with a JSON body describing the problem.
• Query endpoints are read-only — only SELECT/WITH SQL is accepted, matching the product’s SQL editor rules.

Endpoint groups

Group	Covers
Auth	sign-in, tokens, MFA, SSO
API Keys	programmatic credentials
Data Sources	connections: create, test, sync
Datasets	Warehouse datasets: import, refresh, schedule, history
Query	run read-only SQL
Saved Queries	the SQL library
Dashboards	dashboards and cards
Sharing	share links
Embedding	embed tokens and domains
Reports	reports and schedules
Themes	workspace themes
Metrics	governed metrics: definitions, values, series, digests
Alerts	threshold rules — field-based and metric-bound
Webhooks	outbound events, Slack-format channels, deliveries
Catalog	business glossary and certification
Pipelines	pipeline definitions, runs, backfill
Search	semantic search across dashboards, metrics, fields, saved queries
Shared schemas	JSON Schemas for the entitlement snapshot, product usage cards, pipeline definitions and run/step statuses

This reference is generated from the API’s OpenAPI specification, so it stays in lock-step with the deployed surface. The shared schemas come from the contracts package the api itself builds against. Endpoint groups beyond this subset (admin, internal) exist but aren’t documented publicly — if you need one for an integration, ask.