REST API Reference

REST API endpoints, authentication methods, rate limits, and error handling. All SDK methods map to these endpoints.

Base URL

https://YOUR_API_DOMAIN/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 Authentication

Used by the React SDK, Headless SDK, and server-side integrations. Pass your API key in the X-API-Key header.

curl -X GET https://YOUR_API_DOMAIN/api/v1/public/eligibility \
  -H "X-API-Key: bq_live_your_key_here" \
  -H "Content-Type: application/json"

Key format: bq_live_ (production) or bq_test_ (testing) followed by 32 hex characters. Keys are hashed server-side — the plaintext is shown once on creation.

Session-Based (Anonymous)

Public endpoints for participant-facing operations use session-based identification. No API key required — the session ID is passed as a query parameter or in the request body.

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

Rate Limits

All API endpoints are rate-limited at three levels: per-IP, per-API key, and per-tenant.

Scope	Limit	Window
Per IP	100 requests	60 seconds
Per API Key	1,000 requests	60 seconds
Per Tenant	200 requests	60 seconds
Burst (Ingestion)	100 requests	1 second

Every response includes rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1707700800

# When rate limited (429):
Retry-After: 45

Error Responses

All API errors follow a consistent JSON format:

{
  "detail": "Human-readable error message"
}

// Common status codes
400  Bad Request       — Invalid parameters or body
401  Unauthorized      — Missing or invalid API key
403  Forbidden         — Key lacks required scope
404  Not Found         — Resource does not exist
409  Conflict          — Duplicate action (already enrolled)
429  Too Many Requests — Rate limit exceeded
500  Internal Error    — Server error

API Key Management

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

Method	Endpoint	Description
POST	`/events/api-keys`	Create a new API key. Returns the plaintext key (shown once).
GET	`/events/api-keys`	List all API keys for the tenant (prefixes only).
PATCH	`/events/api-keys/{id}`	Update key name, scopes, or rate limit.
DELETE	`/events/api-keys/{id}`	Revoke an API key. Takes effect immediately.