Conventions and errors

Conventions

• JSON. Request and response bodies are JSON with camelCase fields, except CSV uploads (multipart/form-data) and the rewards export (CSV).
• IDs. Programs, rules, imports and adjustments have UUIDs. Participants are identified by your own externalId (1–128 characters), URL-encoded in paths. Periods are YYYY-MM. Rule keys and metric keys are lowercase snake_case (1–63 characters).
• Amounts are decimal strings, never JSON numbers: up to 6 decimal places in requests, exactly 6 in responses ("17.500000"). Rates are fractions with up to 18 decimal places ("0.035" = 3.5%).
• Dates and times are UTC. Dates are YYYY-MM-DD; timestamps are ISO 8601 (2026-10-13T16:03:31.676Z).
• Strict validation. Unknown body fields and unknown query parameters are rejected with 400.
• Wallet addresses are Solana addresses (base58, 32–44 characters).

Idempotency

Every POST, PATCH and DELETE requires an Idempotency-Key header (1–255 characters), so a retried request never runs twice.

• Repeating a request with the same key, method, URL and body within 24 hours returns the original response, with the header Idempotent-Replayed: true.
• Reusing a key with a different request returns 422 idempotency_key_reused.
• Repeating a request while the first is still running returns 409 idempotency_request_in_progress. Retry shortly.
• Successful responses and 4xx errors are stored and replayed. After fixing a request that failed with a 4xx, send it with a new key. 5xx errors are not stored, so you can retry them with the same key.
• Keys are scoped to your API key.

Versioning

PATCH /programs/{id} and PATCH /rules/{ruleId} require expectedVersion, the version you last read. If the record has changed since, the request returns 409; read it again and retry.

Pagination

Other lists return everything in one response.

Background processing

• Reward calculation runs in the background, usually within seconds. pendingRecalculation on rewards and pendingRecalculations on periods show work in progress.
• CSV imports are queued: the upload returns 202 with an importId, which you poll for status and results.
• Finalizing a period waits for its calculations to finish, so it can take up to about 60 seconds. Use a client timeout above that.
• There are no webhooks. Poll the read endpoints for changes; activity supports updatedSince for incremental sync.

Limits

Errors

Errors return a JSON body with an error field. Many also carry a message, and rule-definition errors carry a path pointing into your request.

{ "error": "Program not found" }
{ "error": "version_conflict", "message": "Rule is at version 2, not 1" }
{ "error": "tiers_gap", "message": "tier 1 must start at 10", "path": "definition.payout.tiers[1].from" }

• Validation errors (400) describe the first problem found, as "<field>: <problem>", for example "limit: Too big: expected number to be <=500".
• Some 409 errors start with a code followed by details, such as "grace_window_open: ends at 2026-11-06T00:00:00.000Z". Match on the text before the first colon.
• Batch endpoints (activity and imports) report problems per row in a 200 response instead of failing the whole request. See Activity.

The full list of codes is in Error codes.

Error codes

Endpoint index

Paths are relative to /api/v1/rewards. Read-only endpoints can be called with either key type; Admin endpoints need an admin key.