Cavuno v1 REST API
The Cavuno API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Base URL
Production: https://api.cavuno.com/v1
All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
Authentication
The Cavuno API uses API keys to authenticate requests. You can view and manage your API keys in the Cavuno dashboard, under Settings → Developer → API keys.
Cavuno API keys have the prefix cavuno_live_. Your API keys carry many privileges, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication to the API is performed via Bearer auth. Provide your API key as the bearer token in the Authorization header:
curl https://api.cavuno.com/v1/jobs \
-H "Authorization: Bearer YOUR_SECRET_API_KEY"
API requests without authentication will fail.
Rate limits
The Cavuno API has rate limits in place to ensure stability and reliability. By default, API keys are limited to 100 requests per minute. If you exceed your limit, requests return an HTTP 429 response with a Retry-After header indicating when you can try again.
If you have a use case that needs a higher limit, contact support.
Idempotency
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a job fails due to a network connection error, you can safely retry the request with the same idempotency key, and we'll guarantee that only one job is created.
To perform an idempotent request, provide an additional Idempotency-Key header on any POST, PATCH, or DELETE request:
curl https://api.cavuno.com/v1/jobs \
-X POST \
-H "Authorization: Bearer cavuno_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "title": "Senior Engineer" }'
Errors
Cavuno uses conventional HTTP response codes to indicate the success or failure of an API request. In general: codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with Cavuno's servers (these are rare).
Error responses include a JSON body with details:
{
"error": {
"code": "validation_bad_request",
"message": "Field 'title' is required.",
"requestId": "req_..."
}
}
Some errors carry an additional details field with structured context, such as per-field validation issues.
When contacting support about a failed request, include the requestId value. It is the fastest way for us to find your request in our logs.