API quick start: base URL, authentication, first request
Start with the clariBI REST API (v1): the base URL, authenticating with an API key, your first request, pagination, errors and rate limits. Professional and Enterprise.
What the API covers
The clariBI REST API (version 1) lets scripts and other systems work with your reports, dashboards, data sources, goals and forecasts. It is available on the Professional and Enterprise plans. The REST API feature page gives an overview, and the documentation has a REST API reference.
- Base URL:
https://claribi.com/api/v1/ - Interactive reference (OpenAPI/Swagger):
https://claribi.com/api/v1/docs/ - Machine-readable schema:
https://claribi.com/api/v1/schema/ - Format: JSON over HTTPS
Step 1: Create an API key
Open Settings > Developer, create a key under API Keys and give it the scopes your script needs (for example reports:read and dashboards:read). Copy the key when it is shown; it is not shown again. See API keys.
Step 2: Authenticate
Send the key as a bearer token in the Authorization header:
Authorization: Bearer claribi_your_key_here
Step 3: Your first request
Check that the key works:
curl -H "Authorization: Bearer $CLARIBI_API_KEY" \
https://claribi.com/api/v1/auth/verify/
Response:
{
"valid": true,
"api_key": {
"id": "5f0c...",
"name": "Weekly export script",
"scopes": ["reports:read", "dashboards:read"],
"created_at": "2026-09-01T09:12:00Z",
"expires_at": null
},
"organization": {"id": "8a41...", "name": "Acme", "tier": "professional"},
"user": {"id": "c3d2...", "email": "you@example.com"}
}
Then list your reports:
curl -H "Authorization: Bearer $CLARIBI_API_KEY" \
"https://claribi.com/api/v1/reports/?page_size=10"
Pagination
Lists are paginated: 20 items per page by default. Use page to move through pages and page_size to change the size (up to 100). The response contains count, next, previous and results:
{
"count": 24,
"next": "https://claribi.com/api/v1/reports/?page=2",
"previous": null,
"results": [ ... ]
}
Errors
| Code | Meaning |
|---|---|
200, 201, 204 |
Success |
400 |
The request body or parameters are invalid |
401 |
The key is missing, wrong, revoked or expired, or the organization's plan does not include API access |
403 |
The key lacks the scope for this action |
404 |
The item does not exist in your organization |
429 |
Rate limit reached |
500 |
Server error; try again, then contact support |
The response body explains the error in JSON.
Rate limits
| Plan | General requests | Generation requests (report generation, dashboard refresh, forecast runs) |
|---|---|---|
| Professional | 1,000 per hour, 20,000 per day | 100 per hour, 500 per day |
| Enterprise | 5,000 per hour, 100,000 per day | 500 per hour, 2,000 per day |
Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. When you get a 429, wait until the reset time before retrying.
Generating reports and running forecasts through the API also uses AI credits, as it does in the app.
Things to know
- Keep keys on the server. Never put a key in browser code or a mobile app.
- Only Professional and Enterprise. If your organization moves to a lower plan, its keys stop working.
- Keys for the MCP server are different. Keys starting with
claribi_mcp_work only with the clariBI MCP server, not the REST API. - Data comes in; there are no outgoing webhooks. To get data out on a schedule, poll the API. Automation with Zapier, webhooks and the REST API shows common patterns, and API-first analytics discusses building on top of a BI tool.