API Integration Guide for Developers

Technical documentation for the clariBI External API v1. Generate reports, manage dashboards, and access analytics programmatically.

Base URL

All API requests use the base URL:
```
https://claribi.com/api/v1/
```

Authentication

API Key Setup

1. Go to Settings → API Keys in the clariBI app
2. Click Generate New Key
3. Select permissions for the key
4. Copy and store your API key securely (it cannot be retrieved later)

API keys are prefixed with `claribi_` and must be included in the Authorization header:
```
Authorization: Bearer claribi_your_api_key_here
```

Verify Your Key

Test your API key with:
```
GET /api/v1/auth/verify/
```

Returns your key info, permissions, and organization details.

Rate Limits

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

Generation requests include report generation and dashboard refresh operations.

Rate limit headers are included in every response:
```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1705142400
```

API Permissions

API keys are created with specific permissions:

Endpoints

Usage & Credits

```
GET /api/v1/usage/
```
Returns credit usage and limits for your organization.

Reports

```
GET /api/v1/reports/ # List reports (paginated)
POST /api/v1/reports/generate/ # Generate new report (sync, ~30-60s)
GET /api/v1/reports/{id}/ # Get report details
GET /api/v1/reports/{id}/download/ # Download report file
DELETE /api/v1/reports/{id}/ # Delete report
```

Dashboards

```
GET /api/v1/dashboards/ # List dashboards (paginated)
POST /api/v1/dashboards/ # Create dashboard
GET /api/v1/dashboards/{id}/ # Get dashboard with widgets
PATCH /api/v1/dashboards/{id}/ # Update dashboard
POST /api/v1/dashboards/{id}/refresh/ # Refresh data (consumes credits)
DELETE /api/v1/dashboards/{id}/ # Delete dashboard
```

Data Sources (Read-Only)

```
GET /api/v1/data-sources/ # List active data sources
GET /api/v1/data-sources/{id}/ # Get data source details
```

Code Examples

Python

```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 remaining: {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-1"],
"output_format": "pdf"
}
)
report = response.json()
print(f"Report ID: {report['report_id']}")
print(f"Credits used: {report['credits_consumed']}")
```

JavaScript

```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

```bash

Verify API key

curl -H "Authorization: Bearer claribi_your_api_key" \
https://claribi.com/api/v1/auth/verify/

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/
```

Error Handling

Error responses include details:
```json
{
"error": "Insufficient credits",
"message": "Need ~25 credits, have 10",
"credits_remaining": 10,
"estimated_cost": 25
}
```

Credits and Billing

Report generation and dashboard refresh operations consume AI credits:
- Credits are estimated before operations
- Actual consumption depends on data size and complexity
- Use `GET /api/v1/usage/` to check remaining credits
- 402 errors indicate insufficient credits

For complete API documentation, visit the API Reference.