Skip to main content
The Lunar Control Plane exposes a versioned REST API under /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 is http://127.0.0.1:8000. Set it once for the examples on this page:
Replace that value with your environment’s HTTPS origin when connecting remotely. The origin does not include /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.
The image, entrypoint, and GPU fields are currently orchestration metadata; the mock provider does not execute them. 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 include items 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:
Use 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.