Developer Guide · REST API
REST API Examples
Use the Bear Lumen REST API directly with cURL, Postman, or any HTTP client. No SDK required. Every example is a plain HTTP request that works from any language or runtime.
Authentication
All API requests carry an SDK API key in the Authorization: Bearer sk_test_... header. Keys are scoped with specific permissions, for example usage:write and costs:read.
Verify your key
GET/v1/ping
# Get your API key from the Bear Lumen dashboard
# API keys start with sk_ and require specific scopes
curl https://api.bearlumen.com/v1/ping \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"
Keep your keys secret
Never commit API keys to version control. Load them from environment variables in production, and rotate any key that may have been exposed.
Usage Tracking
Record AI usage events to track costs. Each event captures the model, provider, and token count. The metadata object also accepts any custom attributes you define (environment, customer tier, team, workflow phase), so you can group cost by any dimension that matters to your business. Requires the usage:write scope.
Record Usage Event
POST/v1/usage-events
# The cost-aware ingestion route requires an HMAC-SHA256 signature over
# the string "{timestamp}.{raw body}", keyed with your API key.
API_KEY="sk_test_YOUR_API_KEY"
TS=$(date +%s)
BODY='{"idempotency_key":"3f9a2b1c-8d7e-4f6a-9b2c-1a2b3c4d5e6f","model":"gpt-4o","input_tokens":1500,"output_tokens":420,"event_invoked_at":"2026-01-15T10:30:00.000Z","user_id":"usr_8a2f19","provider":"openai","feature":"ticket_summary"}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$API_KEY" -r | cut -d' ' -f1)
curl -X POST https://api.bearlumen.com/v1/usage-events \
-H "Authorization: Bearer $API_KEY" \
-H "X-Timestamp: $TS" \
-H "X-Signature: v1=$SIG" \
-H "Content-Type: application/json" \
-d "$BODY"
View response 202
{
"event_id": "7f6c1d68-3a4e-5b2c-9f8d-2e7a4c1b9d3f",
"status": "accepted",
"message": "Event accepted for processing"
}
Record Batch Usage Events (up to 100)
POST/v1/usage-events/batch
API_KEY="sk_test_YOUR_API_KEY"
TS=$(date +%s)
BODY='{"events":[{"idempotency_key":"7c1d4e2f-9a8b-4c3d-8e7f-6a5b4c3d2e1f","model":"claude-3-5-sonnet","input_tokens":1200,"output_tokens":310,"event_invoked_at":"2026-01-15T10:31:00.000Z","provider":"anthropic","feature":"chat"},{"idempotency_key":"9a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d","model":"gpt-4o-mini","input_tokens":800,"output_tokens":150,"event_invoked_at":"2026-01-15T10:32:00.000Z","provider":"openai","feature":"chat"}]}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$API_KEY" -r | cut -d' ' -f1)
curl -X POST https://api.bearlumen.com/v1/usage-events/batch \
-H "Authorization: Bearer $API_KEY" \
-H "X-Timestamp: $TS" \
-H "X-Signature: v1=$SIG" \
-H "Content-Type: application/json" \
-d "$BODY"
Idempotency
Generate a UUID and send it as idempotency_key on every event. Retries with the same key return the same event and are never double counted.
Timestamps & backfill
Two timestamps do two different jobs. The X-Timestamp request-signing header must be current: requests whose signing timestamp is more than 5 minutes from server time are rejected with a 401. That is HMAC replay protection, not a limit on how old your data can be.
The event_invoked_at body field records when the event itself happened, and it may be backdated to record historical usage, so backfilling older events is supported. Events whose event_invoked_at is more than 24 hours old are still accepted, just flagged with status: "accepted_flagged".
Cost Data
Query aggregated cost data across your organization. Requires the costs:read scope.
Get Cost Summary
GET/v1/cost-data/summary
curl "https://api.bearlumen.com/v1/cost-data/summary?time_window=current-period" \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"
View response 200
{
"currentPeriodCost": "1234.56",
"previousPeriodCost": "1100.00",
"changeAmount": "134.56",
"changePercent": 12.23,
"periodStart": "2026-01-01T00:00:00.000Z",
"periodEnd": "2026-01-31T23:59:59.999Z",
"eventCount": 48210,
"statusCounts": { "completed": 48210, "pending": 0, "pendingRateCard": 12, "failed": 3 }
}
Cost Breakdown by Model
GET/v1/cost-data/by-model
curl "https://api.bearlumen.com/v1/cost-data/by-model?start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"
View response 200
{
"models": [
{ "modelSlug": "gpt-4o", "providerSlug": "openai", "totalCost": "580.25", "inputTokens": 3400000, "outputTokens": 820000, "eventCount": 12500, "percentOfTotal": 47.0 },
{ "modelSlug": "claude-3-5-sonnet", "providerSlug": "anthropic", "totalCost": "350.10", "inputTokens": 1900000, "outputTokens": 540000, "eventCount": 8200, "percentOfTotal": 28.4 },
{ "modelSlug": "gpt-4o-mini", "providerSlug": "openai", "totalCost": "304.21", "inputTokens": 5200000, "outputTokens": 1100000, "eventCount": 45000, "percentOfTotal": 24.6 }
],
"totalCost": "1234.56"
}
Cost Breakdown by Provider
GET/v1/cost-data/by-provider
curl "https://api.bearlumen.com/v1/cost-data/by-provider?start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"
Cost Trend (Time Series)
GET/v1/cost-data/trend
curl "https://api.bearlumen.com/v1/cost-data/trend?start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"
End User Costs
Query costs scoped to a specific end user by their external ID (the userId set in SDK track options). Requires the costs:read scope.
End User Cost Summary
GET/v1/end-user-costs/{userId}/summary
curl "https://api.bearlumen.com/v1/end-user-costs/user_123/summary?start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"
View response 200
{
"endUserId": "euid_abc123",
"endUserExternalId": "user_123",
"endUserName": "Acme Corp",
"currentPeriodCost": "245.80",
"previousPeriodCost": "210.50",
"changeAmount": "35.30",
"changePercent": 16.77,
"eventCount": 3820,
"periodStart": "2026-01-01T00:00:00.000Z",
"periodEnd": "2026-01-31T00:00:00.000Z"
}
End User Cost by Model
GET/v1/end-user-costs/{userId}/by-model
curl "https://api.bearlumen.com/v1/end-user-costs/user_123/by-model?start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"
Error Handling
Every error response includes a human-readable correlationId you can quote in a support request to pin down the exact call.
| Status | Meaning |
|---|---|
| 200 | OK. Request succeeded. |
| 202 | Accepted. Usage event queued for cost calculation. |
| 400 | Bad Request. Invalid parameters or request body. |
| 401 | Unauthorized. Missing or invalid API key. |
| 403 | Forbidden. API key lacks the required scope. |
| 404 | Not Found. End user or resource doesn't exist. |
| 429 | Too Many Requests. Rate limit exceeded. |
| 500 | Server Error. Something went wrong on our end. |
Error Response Format
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid time_window: weekly. Valid options: current-period, last-period, last-7-days, last-30-days, last-90-days, ytd, last-year",
"correlationId": "OLIVE-DINOSAUR-1b2fE4",
"details": {
"retryable": false
}
},
"meta": {
"timestamp": "2026-01-13T10:35:00.000Z",
"path": "/v1/cost-data/summary",
"method": "GET"
}
}