On This Page

External API Reference

REST API for programmatic access to reports, dashboards, and data sources. Generate reports, refresh dashboards, and retrieve analytics data.

Base URL

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

Need an API key? Go to Settings → API Keys in the clariBI app to generate one.

Authentication

API Key Authentication

All API requests require authentication using an API key in the Authorization header. API keys are prefixed with claribi_.

curl -H "Authorization: Bearer claribi_your_api_key_here" \
     -H "Content-Type: application/json" \
     https://claribi.com/api/v1/auth/verify/

Verify Your API Key

Test that your API key is valid and check your permissions:

GET /api/v1/auth/verify/
Response
{
  "valid": true,
  "api_key": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Integration",
    "permissions": [
      "reports:read",
      "reports:generate",
      "dashboards:read",
      "usage:read"
    ],
    "created_at": "2025-01-01T00:00:00Z",
    "expires_at": null
  },
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Acme Corp",
    "tier": "professional"
  },
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "email": "user@example.com"
  }
}
Security Note

Keep your API key secure. Never expose it in client-side code or public repositories. API keys are hashed before storage and cannot be retrieved after creation.

Rate Limits

API rate limits vary by subscription tier. Limits are tracked per API key per hour.

Tier General Requests Generation Requests
Trial 60/hour, 500/day 5/hour, 20/day
Starter 300/hour, 5,000/day 20/hour, 100/day
Professional 1,000/hour, 20,000/day 100/hour, 500/day
Enterprise 5,000/hour, 100,000/day 500/hour, 2,000/day

Generation requests include report generation and dashboard refresh operations that consume AI credits.

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1705142400

429 Too Many Requests: When rate limited, wait until the reset timestamp before retrying.

Error Handling

The API uses standard HTTP status codes and returns errors in JSON format.

Status Code Description
200 Success
201 Created - Resource successfully created
400 Bad Request - Invalid parameters or validation error
401 Unauthorized - Invalid, missing, or expired API key
402 Payment Required - Insufficient AI credits
403 Forbidden - API key lacks required permission
404 Not Found - Resource doesn't exist or not accessible
405 Method Not Allowed - HTTP method not supported
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Error Response Format

{
  "error": "Insufficient credits",
  "message": "Insufficient credits. Need ~25, have 10",
  "credits_remaining": 10,
  "estimated_cost": 25
}

Usage & Credits

GET

Get Usage Information

GET /api/v1/usage/

Get current credit usage and limits for your organization.

Required Permission: usage:read

Response

{
  "credits": {
    "used": 1250,
    "limit": 5000,
    "remaining": 3750,
    "percentage_used": 25.0
  },
  "tier": "professional"
}

Reports

GET

List Reports

GET /api/v1/reports/

Retrieve a paginated list of reports for your organization.

Required Permission: reports:read

Query Parameters

Parameter Type Description
pageintegerPage number (default: 1)
page_sizeintegerItems per page (default: 20, max: 100)

Response

{
  "count": 45,
  "next": "https://claribi.com/api/v1/reports/?page=2",
  "previous": null,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440005",
      "title": "Weekly Sales Report",
      "status": "completed",
      "output_format": "pdf",
      "created_at": "2025-01-13T08:00:00Z",
      "generation_completed_at": "2025-01-13T08:02:30Z",
      "processing_credits_used": 47
    }
  ]
}
POST

Generate Report

POST /api/v1/reports/generate/

Generate a new report using a template and data sources. This is a synchronous operation that may take 30-60 seconds.

Required Permission: reports:generate

Credit Consumption: Report generation consumes AI credits based on data size and complexity. Credits are estimated before generation and consumed upon completion.

Request Body

{
  "template_id": "550e8400-e29b-41d4-a716-446655440010",
  "data_source_ids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "987fcdeb-51a2-3bc4-d567-890123456789"
  ],
  "output_format": "pdf",
  "report_parameters": {
    "date_range": {
      "start": "2025-01-01",
      "end": "2025-01-31"
    }
  }
}

Parameters

Field Type Required Description
template_idUUIDYesReport template ID
data_source_idsUUID[]YesArray of data source IDs
output_formatstringNojson, pdf, html, excel, csv (default: pdf)
report_parametersobjectNoTemplate-specific parameters

Response (201 Created)

{
  "success": true,
  "report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Executive Summary Report",
  "status": "completed",
  "output_format": "pdf",
  "download_url": "/api/v1/reports/a1b2c3d4.../download/",
  "credits_consumed": 47,
  "generation_duration_seconds": 34
}
GET

Get Report Details

GET /api/v1/reports/{id}/

Retrieve detailed information about a specific report.

Required Permission: reports:read

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440005",
  "title": "Weekly Sales Report",
  "description": "Automated weekly sales summary",
  "status": "completed",
  "output_format": "pdf",
  "template": "550e8400-e29b-41d4-a716-446655440010",
  "template_name": "Executive Summary",
  "data_sources": [
    {"id": "...", "name": "Sales DB", "type": "database"}
  ],
  "download_url": "/api/v1/reports/550e8400.../download/",
  "processing_credits_used": 47,
  "generation_duration_seconds": 34,
  "created_at": "2025-01-13T08:00:00Z",
  "generation_completed_at": "2025-01-13T08:02:30Z"
}
GET

Download Report

GET /api/v1/reports/{id}/download/

Download the generated report file. Returns the file with appropriate content-type header.

Required Permission: reports:read

Response: Binary file with Content-Disposition header for download.

DELETE

Delete Report

DELETE /api/v1/reports/{id}/

Permanently delete a report and its generated file.

Required Permission: reports:delete

Response (204 No Content)

Empty response on success.

Dashboards

GET

List Dashboards

GET /api/v1/dashboards/

Retrieve a paginated list of dashboards for your organization.

Required Permission: dashboards:read

Response

{
  "count": 12,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "name": "Sales Overview",
      "description": "Key sales metrics",
      "status": "active",
      "niche_domain": "ecommerce",
      "widget_count": 8,
      "last_refresh": "2025-01-13T09:00:00Z",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}
POST

Create Dashboard

POST /api/v1/dashboards/

Create a new dashboard with custom metrics and data sources.

Required Permission: dashboards:create

Request Body

{
  "name": "Sales Dashboard",
  "description": "Track key sales metrics",
  "niche_domain": "ecommerce",
  "refresh_frequency": "daily",
  "data_source_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "custom_metrics": [
    {
      "name": "Total Revenue",
      "type": "sum",
      "field": "revenue"
    }
  ]
}

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440021",
  "name": "Sales Dashboard",
  "status": "active",
  "created_at": "2025-01-13T10:00:00Z"
}
POST

Refresh Dashboard

POST /api/v1/dashboards/{id}/refresh/

Refresh dashboard data by re-analyzing connected data sources. This is a synchronous operation that consumes AI credits.

Required Permission: dashboards:refresh

Credit Consumption: Dashboard refresh consumes AI credits based on data sources and widget count.

Response

{
  "success": true,
  "message": "Dashboard data refreshed successfully",
  "dashboard_id": "550e8400-e29b-41d4-a716-446655440020",
  "job_id": "job-uuid-here",
  "credits_consumed": 23,
  "widgets_created": 0,
  "widgets_updated": 8,
  "last_refresh": "2025-01-13T10:30:00Z"
}
PATCH

Update Dashboard

PATCH /api/v1/dashboards/{id}/

Update dashboard metadata.

Required Permission: dashboards:update

Request Body

{
  "name": "Updated Dashboard Name",
  "description": "New description"
}
DELETE

Delete Dashboard

DELETE /api/v1/dashboards/{id}/

Permanently delete a dashboard and all its widgets.

Required Permission: dashboards:delete

Data Sources

GET

List Data Sources

GET /api/v1/data-sources/

Retrieve a list of active data sources for your organization. Only returns sources with status: active.

Required Permission: data_sources:read

Response

{
  "count": 5,
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Sales Database",
      "source_type": "database",
      "status": "active",
      "last_sync": "2025-01-13T08:00:00Z",
      "record_count": 15000,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}
GET

Get Data Source Details

GET /api/v1/data-sources/{id}/

Retrieve detailed information about a specific data source.

Required Permission: data_sources:read

Supported Data Source Types

file - File Upload
database - Database
api - REST API
google_sheets - Google Sheets
google_analytics - GA4
jira - Jira

Permissions

API keys are created with specific permissions. Each endpoint requires certain permissions to access.

Permission Description
reports:read List and view reports, download report files
reports:generate Generate new reports (consumes credits)
reports:delete Delete reports
dashboards:read List and view dashboards
dashboards:create Create new dashboards
dashboards:update Update dashboard metadata
dashboards:refresh Refresh dashboard data (consumes credits)
dashboards:delete Delete dashboards
data_sources:read List and view data sources
usage:read View credit usage and limits

Code Examples

Py

Python

import requests

API_KEY = "claribi_your_api_key"
BASE_URL = "https://claribi.com/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Check usage
usage = requests.get(
    f"{BASE_URL}/usage/",
    headers=headers
).json()
print(f"Credits: {usage['credits']['remaining']}")

# Generate a report
response = requests.post(
    f"{BASE_URL}/reports/generate/",
    headers=headers,
    json={
        "template_id": "your-template-uuid",
        "data_source_ids": ["source-uuid"],
        "output_format": "pdf"
    }
)
report = response.json()
print(f"Report: {report['report_id']}")
JS

JavaScript

const API_KEY = 'claribi_your_api_key';
const BASE_URL = 'https://claribi.com/api/v1';

const headers = {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
};

// Check usage
const usage = await fetch(
    `${BASE_URL}/usage/`,
    { headers }
).then(r => r.json());
console.log(`Credits: ${usage.credits.remaining}`);

// Refresh a dashboard
const result = await fetch(
    `${BASE_URL}/dashboards/${dashboardId}/refresh/`,
    { method: 'POST', headers }
).then(r => r.json());
console.log(`Credits used: ${result.credits_consumed}`);
$

cURL

# List dashboards
curl -H "Authorization: Bearer claribi_your_api_key" \
     https://claribi.com/api/v1/dashboards/

# Generate a report
curl -X POST \
     -H "Authorization: Bearer claribi_your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"template_id":"uuid","data_source_ids":["uuid"],"output_format":"pdf"}' \
     https://claribi.com/api/v1/reports/generate/

# Refresh a dashboard
curl -X POST \
     -H "Authorization: Bearer claribi_your_api_key" \
     https://claribi.com/api/v1/dashboards/{id}/refresh/

Next Steps