API Introduction
You can start using Cleavr’s API by creating a new API Token. To create a new token navigate to API Tokens page from the sidebar and click on Add New Token.
Cleavr’s API is available on an active trial or a Cleavr Business subscription.
Token Scopes
Each token has one of the following scopes:
Global Scope: Used by default if you’re not on a Cleavr Business subscription (no company or teams). Business company owners can create either Global or Team tokens. A global token uses the same access rules as the UI’s global view: it can reach all servers, sites, deployments, and connection profiles available to you at the account level - not only resources in a specific team.
Team Scope: Business company owners and team members can create team-scoped tokens for a team they belong to. These tokens can only access resources available to that team. Company members cannot create global tokens.
Abilities
Abilities control which HTTP methods a token may use. Choose at least one when creating a token.
| Ability | Methods |
|---|---|
| read | GET , HEAD |
| write | POST , PUT , PATCH |
| delete | DELETE |
Scope and abilities work together. Scope limits which resources a token can access. Abilities limit which actions it can take. Missing an ability returns 403 insufficient_scope.
API Base URL
https://app.cleavr.io/api/v1
Authenticated Token
GET Retrieve Authenticated Token Context
/api/v1/me To retrieve the authenticated token owner, token metadata, and team scope, send a GET request to /api/v1/me. The response never includes the token secret. team is null for a global token.
Rate Limiting
The API allows 60 requests per minute per API token on /api/v1. All methods share one bucket. Separate tokens have separate buckets.
Successful responses include X-RateLimit-Limit and X-RateLimit-Remaining.
Over the limit returns 429 with error.code rate_limit_exceeded and a Retry-After header (seconds). Wait that long before retrying.
For async work that returns 202, poll the resource GET-by-uuid every 5–10 seconds until a terminal status. Honor Retry-After on 429.