Conventions

Authentication, the response envelope, rate limits, and error shapes shared across the API.

Base path

Every endpoint is mounted under /api. Paths in the reference already include it (e.g. POST /api/agencies).

Authentication

Public API requests use bearer API keys:

Authorization: Bearer YOUR_API_KEY

Create and manage keys from the API Keys page in the dashboard. Some endpoints also require a customer role, tenant boundary, project access, or module scope. Those constraints are noted on each operation.

CSRF

Public API requests authenticated with bearer API keys do not use CSRF tokens. CSRF protection applies to browser dashboard sessions, not API key requests.

Response envelope

Success responses use:

{ "success": true, "data": { } }

The payload key varies by endpoint (data, result, or a named field). Errors use:

{ "success": false, "error": "ERROR_CODE", "message": "Human-readable explanation" }

error is a short machine-readable code (for example Unauthorized, VALIDATION, or InsufficientScope); message is the human-readable explanation. Some errors add fields, such as requiredScope on InsufficientScope.

Common status codes

Status	Meaning
400	Validation failed / malformed request
401	Missing or invalid authentication
403	Authenticated but not permitted (role, tenant boundary, or missing API scope)
404	Resource not found
429	Rate limit exceeded
500	Unexpected server error

Rate limiting

All /api routes pass through shared source-IP rate limits. API-key requests also use API key and API key plus source-IP limits. Exceeding a limit returns 429 with the standard error envelope.