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.
Plan upgrade hints
When an Operator API request is refused because of the board's Cavuno plan, the error also carries an upgrade object. It names the capability that blocked the request, the cheapest self-serve plan that unlocks it (when that can be told), and the hosted billing endpoints that start the upgrade:
{
"error": {
"code": "settings_plan_required_for_branding_removal",
"message": "Removing Cavuno branding requires a plan that includes branding removal.",
"requestId": "req_...",
"upgrade": {
"capability": "canRemoveBranding",
"requiredPlan": "basic",
"checkout": { "method": "POST", "path": "/v1/billing/checkout" },
"changePlan": { "method": "POST", "path": "/v1/billing/upgrade" }
}
}
}
Call GET /v1/billing/subscription first. With no active subscription, use checkout; with one, use changePlan. Send { "planKey": "<requiredPlan>" } and give the returned url to a person: both endpoints return a hosted page where a person confirms the purchase. Nothing is charged until they do. Each path is relative to the API origin (https://api.cavuno.com), like Location headers and list url fields, so do not join it to a base URL that already ends in /v1. Both endpoints need a key with billing.manage; a key without it should hand the person the dashboard's billing page instead. Board API errors never carry this field.
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.
Reporting problems
AI agents can report anything that got in the way of a task: a missing capability, unclear documentation, a surprising response, an unhelpful error, a bug or slow performance. POST /v1/feedback accepts Agent Feedback Protocol v0.1 reports, with or without an API key, and API error responses link to it in a Link: <https://api.cavuno.com/v1/feedback>; rel="agent-feedback" header. The discovery document is at https://api.cavuno.com/.well-known/agent-feedback.
curl https://api.cavuno.com/v1/feedback \
-X POST \
-H "Content-Type: application/json" \
-d '{ "type": "missing_capability", "goal": "What you were trying to do", "message": "What got in the way", "agent": { "name": "my-agent", "model": "model-name" } }'
type, goal and message are required. Each account or visitor can send 20 reports every 5 minutes. Never include credentials or personal data. Send the report, then continue with your task.