API Quick Start: Base URL, Auth, First Request

Overview

The clariBI REST API lets you programmatically access and manage your data sources, dashboards, reports, and analytics. Whether you are building an integration, automating workflows, or pulling data into another system, this guide gets you up and running.

Base URL

All API requests use the following base URL:

https://claribi.com/api/

All endpoints require HTTPS. HTTP requests are rejected.

Authentication

The clariBI API supports two authentication methods: JWT tokens and API keys. Use whichever fits your use case.

Method 1: JWT Token

JWT (JSON Web Token) authentication is ideal for user-facing applications and short-lived sessions.

Getting a token:

curl -X POST https://claribi.com/api/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Response:

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

• Access token: Valid for 1 hour. Include this in every API request.
• Refresh token: Valid for 7 days. Use it to get a new access token without re-entering credentials.

Using the access token:

curl -H "Authorization: Bearer eyJ0eXAi..." \
  https://claribi.com/api/auth/status/

Refreshing the token:

curl -X POST https://claribi.com/api/auth/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh": "eyJ0eXAi..."}'

This returns a new access token. The refresh token itself does not change.

Method 2: API Key

API keys are better for server-to-server integrations, scripts, and long-running automation. They do not expire on a timer (unless you set an expiration date).

Using an API key:

curl -H "X-API-Key: claribi_sk_live_your_key_here" \
  https://claribi.com/api/data-sources/

Create API keys from Settings > Security > API Keys in the clariBI web interface. See API Keys: Create, Scope, Rotate, Revoke for details.

Which Method to Use

Your First Request

Let's verify your authentication is working by checking your account status.

Using JWT

# Step 1: Get a token
TOKEN=$(curl -s -X POST https://claribi.com/api/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}' \
  | jq -r '.access')

# Step 2: Make an authenticated request
curl -H "Authorization: Bearer $TOKEN" \
  https://claribi.com/api/auth/status/

Using an API Key

curl -H "X-API-Key: claribi_sk_live_your_key_here" \
  https://claribi.com/api/auth/status/

Expected Response

{
  "user": {
    "id": 1,
    "email": "you@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "role": "administrator"
  },
  "organization": {
    "id": 1,
    "name": "Acme Corp",
    "plan": "professional",
    "ai_credits_remaining": 1347
  }
}

If you see your user and organization information, authentication is working. If you get a 401 Unauthorized error, double-check your token or API key.

Response Format

All API responses are JSON. Successful responses follow this structure:

Single Object

{
  "id": 42,
  "name": "Revenue Dashboard",
  "created_at": "2025-06-15T10:30:00Z",
  "updated_at": "2025-06-20T14:22:00Z"
}

List of Objects

{
  "count": 24,
  "next": "https://claribi.com/api/dashboards/?page=2",
  "previous": null,
  "results": [
    {"id": 1, "name": "Revenue Dashboard"},
    {"id": 2, "name": "Marketing Funnel"}
  ]
}

Lists are paginated with 20 items per page by default. Use the page query parameter to navigate pages, or page_size to change the number of items per page (maximum 100).

Error Handling

Errors return an appropriate HTTP status code and a JSON body:

{
  "error": "not_found",
  "message": "The requested resource does not exist.",
  "detail": "No dashboard with ID 999 was found."
}

Common Status Codes

Rate Limits

When you exceed the rate limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Next Steps

Now that you can authenticate and make requests, explore the full API:

• Authentication: JWT Tokens vs. API Keys -- Deep dive into auth methods
• Endpoint Reference: Data Sources, Reports, Dashboards -- Complete endpoint documentation
• API Keys: Create, Scope, Rotate, Revoke -- API key management