API Reference Overview

The clariBI API lets you programmatically access your data sources, dashboards, reports, and analytics. This page covers the basics you need to get started.

Base URL

https://claribi.com/api/

All API endpoints are relative to this base URL.

Authentication

Two authentication methods are supported:

JWT Tokens

Obtain a token by posting credentials to /api/auth/login/. Include the token in subsequent requests:

Authorization: Bearer eyJ0eXAiOiJKV1Qi...

JWT tokens expire after 1 hour. Use the refresh token (valid 7 days) to get a new access token without re-authenticating.

API Keys

Generate API keys from Settings > Developer > API Keys. Include in requests as:

Authorization: Bearer claribi_key_abc123...

API keys can be set to expire after 30 days, 90 days, or 1 year, or configured to never expire. They can be revoked at any time. Keys inherit the permissions of the user who created them.

See Authentication for full details.

Rate Limit Headers

Every API response includes the following headers so your application can track its throttle state:

When the limit is exceeded, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Per-Tier Rate Limits

Limits are enforced per API key (or per user session for JWT) on a rolling one-hour window.

Generation endpoints (e.g., POST /api/v1/reports/generate/) consume AI credits and have lower rate limits. All other endpoints use the general limit.

Error Response Format

All error responses use a consistent JSON structure:

{
  "error": {
    "message": "Human-readable description",
    "code": "machine_readable_code",
    "details": {}
  }
}

Common Error Codes

Example: Validation Error

{
  "error": {
    "message": "Invalid request parameters",
    "code": "validation_error",
    "details": {
      "name": ["This field is required."],
      "scopes": ["'reports:write' is not a valid scope."]
    }
  }
}

Example: Rate Limit Exceeded

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712444400
Retry-After: 1200

{
  "error": {
    "message": "Rate limit exceeded. Try again in 1200 seconds.",
    "code": "rate_limited",
    "details": {}
  }
}

Response Format

All successful responses return JSON with HTTP 200 or 201. List endpoints return paginated results (see Pagination below).

Complete Endpoint Reference

The external API uses the /api/v1/ prefix. All endpoints require Bearer token authentication unless noted otherwise.

Authentication & Usage

Reports

Dashboards

Data Sources

Goals

Filtering & Sorting

List endpoints support these query parameters:

Pagination

List endpoints return paginated results. Default page size 20, max 100.

GET /api/v1/reports/?page=2&page_size=50

OpenAPI Spec & Swagger UI

Machine-readable spec and interactive docs are publicly accessible (no auth required):

System Health Endpoint

A public, unauthenticated endpoint that reports the real-time status of clariBI's core services. No API key required.

The quick check returns:

{
  "overall_status": "healthy",   // healthy | warning | critical
  "timestamp": "2026-04-11T...",
  "version": "1.0.0"
}

overall_status is the worst status across all checked services. Returns HTTP 503 when critical — load balancers and uptime monitors can use this directly.

The status indicator in the site footer reads from this endpoint in real time.

Next Steps

• Authentication & permission scopes
• Data Sources API
• Reports, Dashboards & Goals API
• Webhooks & Zapier