Skip to main content

​
Base URL

​
Authentication

All public API endpoints require an X-API-KEY header. Your workspace (client_id) is resolved server-side from the API key — you never send client_id yourself.
Find your API key in the RevyOps dashboard under Settings → Workspace.
Treat your API key like a secret. Anyone with this value can read and write data in your workspace.

​
Versioning

The API has two versions: All new integrations should use v2 endpoints.

​
Response Format

All responses are JSON, and the shape depends on the endpoint version. v2 list endpoints return a page envelope with no next/previous URLs — follow pagination with the page query parameter instead:
v1 list endpoints return a bare JSON array of results, with no envelope. On both versions, a search that matches nothing returns 200 with {"status": "No contacts found"} (or the equivalent for the resource you queried) instead of an empty results array — check for a status key before reading results.

​
Error Format

400 responses from create/update endpoints instead return a field-keyed validation error object, e.g. {"email": ["This field is required."]}. Common HTTP status codes:

​
Pagination

v2 list endpoints support pagination via page and page_size query parameters:
Default page size is 100. Maximum is 100 — values above that are silently capped. v1 list endpoints do not support pagination at all; they always return at most the first 100 results.

​
Rate Limits

The API does not currently enforce rate limits, but avoid sending more than 10 requests per second from a single client to prevent server-side throttling.