REST API
Authenticate, query the semantic layer, manage sources and dashboards, and handle pagination, errors and rate limits with the Kimo REST API.
The Kimo REST API exposes everything the app can do. It is JSON over HTTPS, versioned in the URL (/v1), and uses the same permissions as the person or service account that owns the token. The base URL is https://api.getkimo.com for cloud workspaces and your own host for on-premise installs.
Authentication
Create a token under Settings → API tokens. Personal tokens act as you; service accounts are recommended for integrations because they survive people leaving. Send the token as a bearer header. Tokens can be scoped to read-only and to specific spaces.
curl https://api.getkimo.com/v1/me \ -H "Authorization: Bearer $KIMO_TOKEN"Query the semantic layer
POST /v1/query is the workhorse. Pass a model, measures, dimensions and filters; Kimo compiles the SQL, applies your policies and returns rows plus metadata.
curl -X POST https://api.getkimo.com/v1/query \ -H "Authorization: Bearer $KIMO_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "subscriptions", "measures": ["mrr"], "dimensions": ["plan"], "range": "last_6_months" }'Core endpoints
| Method | Path | Description |
|---|---|---|
GET | /v1/sources | List sources and their sync status |
POST | /v1/sources/{id}/sync | Trigger a sync now |
GET | /v1/models | List published models |
POST | /v1/query | Run a semantic query |
POST | /v1/ask | Ask a question in natural language |
GET | /v1/dashboards/{id} | Dashboard definition and tiles |
POST | /v1/alerts | Create an alert |
Pagination
List endpoints use cursor pagination. Responses include next_cursor; pass it as ?cursor= to get the next page. The default page size is 50 and the maximum is 500. Query results over 10,000 rows return a job_id you can poll, then download as Parquet or CSV.
Errors and rate limits
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_query | Unknown measure or incompatible dimension |
| 401 | unauthenticated | Missing or expired token |
| 403 | forbidden | Token lacks access to the space or model |
| 404 | not_found | Object does not exist or is not visible |
| 429 | rate_limited | Too many requests; see Retry-After |
| 503 | source_unavailable | Live source unreachable; retry later |
Versioning and deprecation
The /v1 API is stable: we add fields and endpoints, but never remove or rename them within a major version. Breaking changes ship as a new major version with at least 12 months of overlap, announced in the changelog and by email to the owners of affected tokens. Responses include a Kimo-Version header with the exact release that served the request, which is useful when reporting issues.
- Ignore unknown fields in responses; new ones appear without notice.
- Pin SDK versions in production and upgrade deliberately.
- Subscribe to the API changelog under Settings → Notifications.