/v1. The endpoint reference is generated from the same OpenAPI contract used by the console’s TypeScript client and the CLI’s Python SDK.
Choose your API origin
Use the API URL provided with your environment access. For a local Control Plane, the origin ishttp://127.0.0.1:8000.
Set it once for the examples on this page:
/v1.
Authenticate requests
All/v1 endpoints require an Authorization: Bearer header. Use a Lunar API key for automation or a user access token from an authenticated session.
The health endpoints,
/health/live and /health/ready, do not require authentication.
Submit jobs safely
POST /v1/jobs requires an Idempotency-Key header. Use 1–128 characters containing letters, numbers, periods, underscores, colons, or hyphens.
Reuse the same key and body after an ambiguous network failure. Generate a new key for a new job. A missing header returns
422; an invalid key format returns 400.
Read paginated results
List responses includeitems and next_cursor. Pass a non-null next_cursor unchanged into the next request’s cursor parameter; stop when it is null.
GET /v1/usage returns period totals alongside its page of attempt records.
Handle errors
Errors include a stable code, a readable message, and a request ID:error.code to decide how to handle a failure. Message text can change. Validation errors can also include error.details, with field names and validation types; submitted values are not echoed.
Responses include
X-Request-ID; errors also include request_id in the body. Include that ID when contacting the Lunar team. Rate-limited responses currently include Retry-After: 60, in seconds.