API Reference

The contracts here cover what's callable today. Planned capabilities live in the Roadmap until they appear in the OpenAPI spec.

API conventions

These hold across every endpoint.

Convention	Value
Base URL	`https://api.beatra.ai/v1`
Auth	`Authorization: Bearer <api_key>` on every request
Content type	`application/json` for request and response bodies
Versioning	All current endpoints live under `/v1`. Breaking changes ship under a new prefix.
Idempotency	`Idempotency-Key` on create-style `POST`; same key on retries; 24h dedup window
Correlation	`X-Request-Id` is echoed in every response. Send your own or let beatra generate one.

Status codes

Code	Meaning
`200`	Success — synchronous result in the body
`202`	Accepted — async work created, see body for `task_id`
`400`	Validation error — fix the request and resend
`401`	Missing or invalid `Authorization`
`403`	API key authenticated but not permitted for this resource
`404`	Resource or endpoint not found
`409`	`Idempotency-Key` reused with a different body, or job already in a terminal state
`429`	Rate limited — back off and retry with the same `Idempotency-Key`
`5xx`	Transient server-side; retry with backoff

Error envelope

Every non-2xx response uses this shape:

{
  "error": {
    "code": "rate_limited",
    "message": "Request budget exhausted; retry later.",
    "retryable": true,
    "request_id": "req_01J5..."
  }
}