API Reference

Base URL

https://api.bricqs.ai/api/v1

All API endpoints are relative to this base URL. Self-hosted deployments use your custom domain.

Authentication

The Bricqs API uses two authentication methods depending on the endpoint type.

# API Key header
curl -X GET https://api.bricqs.ai/api/v1/public/eligibility \
  -H "X-API-Key: bq_live_your_key_here" \
  -H "Content-Type: application/json"

# Session-based request
curl -X POST https://api.bricqs.ai/api/v1/activities/{activityId}/complete-with-actions \
  -H "Content-Type: application/json" \
  -d '{"session_id": "sess_abc123", "engagement_id": "eng_uuid", ...}'

Rate Limits & API Metering

All API endpoints are rate-limited to ensure fair usage and platform stability. Limits are enforced at three levels: per-IP, per-API key, and per-tenant.

Rate Limit Headers

Every API response includes rate limit information in the headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1707700800

# When rate limited:
HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1707700800

Plan-Based Usage Limits

API quotas scale with your plan. Rate limits, participant caps, and API key allocations increase with each tier.

Endpoint Reference

All endpoints called by the SDK. Public endpoints use session-based auth; protected endpoints require an API key.

curl -X POST https://api.bricqs.ai/api/v1/ingest/events \
  -H "X-API-Key: bq_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "purchase_completed",
    "participant_id": "user_123",
    "properties": {
      "amount": 49.99,
      "currency": "USD",
      "product_id": "prod_abc"
    },
    "timestamp": "2026-02-14T10:30:00Z"
  }'

# Response (< 50ms)
{
  "accepted": true,
  "message_id": "1707900600000-0"
}

curl -X POST https://api.bricqs.ai/api/v1/ingest/events/batch \
  -H "X-API-Key: bq_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"event_name": "page_view", "participant_id": "user_123", "properties": {"page": "/products"}},
      {"event_name": "add_to_cart", "participant_id": "user_123", "properties": {"product_id": "prod_abc"}},
      {"event_name": "purchase_completed", "participant_id": "user_123", "properties": {"amount": 49.99}}
    ]
  }'

API Key Management Endpoints

Manage API keys programmatically. These endpoints require JWT authentication (Builder admin login).

Error Responses

All API errors follow a consistent format:

// Error response format
{
  "detail": "Human-readable error message"
}

// Common HTTP status codes
400 Bad Request      — Invalid parameters or request body
401 Unauthorized     — Missing or invalid API key
403 Forbidden        — API key doesn't have required scope
404 Not Found        — Resource doesn't exist
409 Conflict         — Duplicate action (e.g., already enrolled)
429 Too Many Requests — Rate limit exceeded (check Retry-After header)
500 Internal Error   — Server error (please report)

SDK Error Handling

The SDK handles common error scenarios automatically. For custom error handling:

// React SDK
<BricqsEngagement
  id="YOUR_UUID"
  onError={(error) => {
    if (error.status === 429) {
      showToast('Please wait a moment and try again');
    } else if (error.status === 404) {
      showToast('This engagement is no longer available');
    } else {
      console.error('Bricqs error:', error);
    }
  }}
/>

// Headless SDK
const quiz = useQuiz({ engagementId: '...', activityId: '...', config });
// Errors are caught during submit()
try {
  await quiz.submit();
} catch (error) {
  // Handle submission errors
  console.error('Submit failed:', error);
}