Endpoint Reference: Data Sources, Reports, Dashboards

Overview

This is the complete endpoint reference for the clariBI REST API. All endpoints use the base URL https://claribi.com/api/ and require authentication via JWT token or API key.

For setup instructions, see API Quick Start: Base URL, Auth, First Request.

Authentication Endpoints

POST /api/auth/login/

Authenticate a user and receive JWT tokens.

Request:

{
  "email": "user@example.com",
  "password": "your-password"
}

Response (200):

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

If MFA is enabled, the response includes an mfa_required flag and the login is not complete until the TOTP code is verified.

POST /api/auth/token/refresh/

Get a new access token using a refresh token.

Request:

{
  "refresh": "eyJ0eXAiOiJKV1Q..."
}

Response (200):

{
  "access": "eyJ0eXAiOiJKV1Q..."
}

GET /api/auth/status/

Get the current user's profile and organization status.

Response (200):

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

Data Sources

GET /api/data-sources/

List all data sources for the current organization.

Query Parameters:

Response (200):

{
  "count": 8,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Production PostgreSQL",
      "type": "database",
      "engine": "postgresql",
      "status": "active",
      "last_synced_at": "2025-07-15T08:00:00Z",
      "created_at": "2025-03-10T14:20:00Z"
    },
    {
      "id": 2,
      "name": "Google Analytics",
      "type": "api",
      "engine": "google_analytics",
      "status": "active",
      "last_synced_at": "2025-07-15T06:00:00Z",
      "created_at": "2025-04-01T09:15:00Z"
    }
  ]
}

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

Get details for a specific data source.

Response (200):

{
  "id": 1,
  "name": "Production PostgreSQL",
  "type": "database",
  "engine": "postgresql",
  "status": "active",
  "configuration": {
    "host": "db.example.com",
    "port": 5432,
    "database": "analytics",
    "schema": "public"
  },
  "sync_frequency": "daily",
  "last_synced_at": "2025-07-15T08:00:00Z",
  "tables": ["orders", "customers", "products", "sessions"],
  "created_at": "2025-03-10T14:20:00Z",
  "updated_at": "2025-07-10T11:30:00Z"
}

POST /api/data-sources/

Create a new data source connection.

Request:

{
  "name": "Staging Database",
  "type": "database",
  "engine": "postgresql",
  "configuration": {
    "host": "staging-db.example.com",
    "port": 5432,
    "database": "analytics_staging",
    "username": "readonly_user",
    "password": "secure-password",
    "ssl": true
  },
  "sync_frequency": "daily"
}

Response (201): Returns the created data source object.

POST /api/data-sources/{id}/sync/

Trigger a manual sync for a data source.

Response (202):

{
  "message": "Sync started",
  "task_id": "abc123-def456",
  "estimated_duration": "2 minutes"
}

DELETE /api/data-sources/{id}/

Delete a data source. Requires Analyst role or above.

Response (204): No content.

Dashboards

GET /api/dashboards/

List all dashboards accessible to the current user.

Query Parameters:

Response (200):

{
  "count": 12,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Revenue Overview",
      "description": "Monthly revenue tracking and KPIs",
      "workspace_id": 3,
      "widget_count": 6,
      "is_public": false,
      "created_by": {"id": 1, "name": "Jane Smith"},
      "created_at": "2025-05-20T10:00:00Z",
      "updated_at": "2025-07-14T16:45:00Z"
    }
  ]
}

GET /api/dashboards/{id}/

Get a dashboard with all its widgets.

Response (200):

{
  "id": 1,
  "name": "Revenue Overview",
  "description": "Monthly revenue tracking and KPIs",
  "workspace_id": 3,
  "is_public": false,
  "widgets": [
    {
      "id": 101,
      "type": "kpi",
      "title": "Monthly Revenue",
      "position": {"x": 0, "y": 0, "w": 4, "h": 2},
      "data_source_id": 1,
      "query": "SELECT SUM(amount) FROM orders WHERE created_at >= DATE_TRUNC('month', NOW())",
      "configuration": {"format": "currency", "currency": "USD"}
    },
    {
      "id": 102,
      "type": "line_chart",
      "title": "Revenue Trend",
      "position": {"x": 4, "y": 0, "w": 8, "h": 4},
      "data_source_id": 1,
      "query": "SELECT DATE(created_at), SUM(amount) FROM orders GROUP BY 1 ORDER BY 1",
      "configuration": {"x_axis": "date", "y_axis": "sum"}
    }
  ],
  "created_by": {"id": 1, "name": "Jane Smith"},
  "created_at": "2025-05-20T10:00:00Z",
  "updated_at": "2025-07-14T16:45:00Z"
}

POST /api/dashboards/

Create a new dashboard.

Request:

{
  "name": "Marketing Funnel",
  "description": "Track marketing funnel metrics",
  "workspace_id": 3
}

Response (201): Returns the created dashboard object.

PUT /api/dashboards/{id}/

Update a dashboard's name, description, or configuration.

DELETE /api/dashboards/{id}/

Delete a dashboard. Requires edit access.

Response (204): No content.

Reports

GET /api/reports/

List all reports accessible to the current user.

Query Parameters:

Response (200):

{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Weekly Sales Summary",
      "status": "published",
      "template": "sales_summary",
      "schedule": "weekly",
      "last_generated_at": "2025-07-14T00:00:00Z",
      "created_by": {"id": 1, "name": "Jane Smith"},
      "created_at": "2025-04-10T09:00:00Z"
    }
  ]
}

GET /api/reports/{id}/

Get a specific report with its content.

POST /api/reports/

Generate a new report. Costs 2-5 AI credits depending on complexity.

Request:

{
  "name": "Monthly Revenue Report",
  "template": "revenue_analysis",
  "data_source_ids": [1, 3],
  "parameters": {
    "date_range": "last_30_days",
    "group_by": "week"
  }
}

Response (202):

{
  "id": 15,
  "name": "Monthly Revenue Report",
  "status": "generating",
  "task_id": "xyz789",
  "credits_used": 3,
  "estimated_completion": "30 seconds"
}

DELETE /api/reports/{id}/

Delete a report.

Response (204): No content.

Analytics Queries

POST /api/analytics/query/

Run an AI-powered analytics query. Costs 1 AI credit.

Request:

{
  "query": "What were our top 5 products by revenue last month?",
  "data_source_ids": [1],
  "format": "table"
}

Response (200):

{
  "query": "What were our top 5 products by revenue last month?",
  "results": [
    {"product_name": "Enterprise Plan", "revenue": 45000.00},
    {"product_name": "Professional Plan", "revenue": 32000.00},
    {"product_name": "Starter Plan", "revenue": 18500.00},
    {"product_name": "Add-on: Extra Credits", "revenue": 7200.00},
    {"product_name": "Annual Upgrade", "revenue": 5400.00}
  ],
  "summary": "Enterprise Plan was the top revenue product last month at $45,000, followed by Professional Plan at $32,000.",
  "visualization_suggestion": "bar_chart",
  "credits_used": 1,
  "credits_remaining": 1346
}

Query Parameters for format: - table -- Structured data in rows and columns - summary -- Text summary only - chart -- Includes a chart visualization suggestion

Billing and Usage

GET /api/billing/usage/

Get the current billing period's usage statistics.

Response (200):

{
  "billing_period": {
    "start": "2025-07-01",
    "end": "2025-07-31"
  },
  "plan": "professional",
  "ai_credits": {
    "total": 1500,
    "used": 153,
    "remaining": 1347
  },
  "data_sources": {
    "limit": 15,
    "used": 8
  },
  "users": {
    "limit": 15,
    "active": 11
  }
}

GET /api/billing/pricing-config/

Get the current pricing configuration for all plans.

Response (200):

{
  "plans": [
    {
      "slug": "trial",
      "name": "Trial",
      "price": 0,
      "duration_days": 14,
      "users": 1,
      "ai_credits": 50,
      "data_sources": 3
    },
    {
      "slug": "starter",
      "name": "Starter",
      "price": 99,
      "users": 3,
      "ai_credits": 500,
      "data_sources": 10
    },
    {
      "slug": "professional",
      "name": "Professional",
      "price": 199,
      "users": 15,
      "ai_credits": 1500,
      "data_sources": 50,
      "features": ["rbac", "scheduled_reports", "priority_support"]
    },
    {
      "slug": "enterprise",
      "name": "Enterprise",
      "price": 999,
      "users": 100,
      "ai_credits": 5000,
      "data_sources": 100,
      "features": ["rbac", "custom_roles", "sso", "audit_log", "dedicated_support"]
    }
  ]
}

Common Query Parameters

These parameters work across most list endpoints:

Error Responses

All errors follow a consistent format:

{
  "error": "error_code",
  "message": "Human-readable description",
  "detail": "Additional context (optional)"
}

Error Codes

Webhooks

clariBI can send webhook notifications for certain events. Configure webhooks in Settings > Integrations > Webhooks.

Supported Events

• data_source.sync_completed -- A data source sync finished
• data_source.sync_failed -- A data source sync failed
• report.generated -- A report finished generating
• goal.milestone_reached -- A goal milestone was reached
• billing.credits_low -- AI credits are below 10%

Webhook Payload Example

{
  "event": "data_source.sync_completed",
  "timestamp": "2025-07-15T08:00:00Z",
  "data": {
    "data_source_id": 1,
    "data_source_name": "Production PostgreSQL",
    "records_synced": 15420,
    "duration_seconds": 45
  }
}

SDKs and Libraries

Official SDKs are in development. In the meantime, the API works with any HTTP client. Example libraries:

• Python: requests or httpx
• JavaScript: fetch, axios, or node-fetch
• Ruby: httparty or faraday
• Go: net/http

Related Articles

• API Quick Start: Base URL, Auth, First Request
• Authentication: JWT Tokens vs. API Keys
• External Automation: Using the clariBI API With Third-Party Tools
• API Keys: Create, Scope, Rotate, Revoke