REST API reference

The REST API gives scripts and back-end systems access to your reports, dashboards, data sources, goals, forecasts and usage. It is available on the Professional and Enterprise plans.

Base URL

https://claribi.com/api/v1/

All paths below are relative to this URL and end with a slash.

Authentication

Every request needs an API key in the Authorization header:

Authorization: Bearer claribi_xxxxxxxxxxxxxxxx

Owners and Administrators create keys in Settings > Developer. Each key carries a list of scopes; see Authentication. MCP keys (claribi_mcp_...) are rejected here, and browser session tokens are not accepted on /api/v1/.

Plans

The API needs the Professional ($199/month) or Enterprise ($999/month) plan. The check runs on every request against the organization that owns the key. If the organization is on another plan, or its subscription is suspended or cancelled, the request fails with HTTP 401 and a message saying why.

Rate limits

Limits apply per organization, over a rolling 60-minute window. Creating more keys does not raise them.

Generation requests are the ones that run AI or forecasting work: POST reports/generate/, POST dashboards/{id}/refresh/ and POST forecasts/{id}/run/. Everything else counts as general.

Throttled responses include these headers:

Over the limit, the API returns HTTP 429 with a Retry-After header in seconds.

Errors

Check the HTTP status first. The body is JSON in one of two shapes:

// Errors returned by an endpoint itself (unknown template, no credits, ...)
{ "error": "Insufficient credits", "message": "...", "credits_remaining": 3, "estimated_cost": 5 }

// Authentication, permission, not found and throttling errors
{ "error": { "message": "Request failed", "code": "REQUEST_ERROR", "status": 401,
             "details": { "detail": "Invalid API key" } } }

Validation errors (HTTP 400) list the problem per field, for example {"data_source_ids": ["This list may not be empty."]}.

Pagination and filters

List endpoints return pages of 20 items by default. Use ?page=2 and ?page_size= (up to 100). The response has count, next, previous and results.

Endpoints

Key and usage

Reports

Dashboards

Data sources

Goals

Forecasts

What the API does not cover

• Connecting, editing or deleting data sources. Do that in the app.
• Users, roles, billing and settings.
• Listing templates, and generating from the built-in template library. reports/generate/ accepts report templates saved in your organization; see Reports API.
• Outbound webhooks. See Webhooks and Zapier.

Health endpoint

GET https://claribi.com/api/monitoring/health/ needs no key and reports whether the database, cache and background workers respond. It returns overall_status (healthy, warning or critical) and HTTP 503 when the status is critical. Add ?level=summary for a per-service breakdown.

Next

• Authentication and scopes
• Data sources API
• Reports, dashboards and goals API
• Webhooks and Zapier