> ## Documentation Index
> Fetch the complete documentation index at: https://docs.run-lunar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Authentication, pagination, idempotency, and errors for the Lunar REST API.

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:

```bash theme={null}
export LUNAR_API_URL="http://127.0.0.1:8000"
```

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.

```bash theme={null}
curl --fail-with-body "$LUNAR_API_URL/v1/me" \
  -H "Authorization: Bearer $LUNAR_API_KEY"
```

| Credential | Use it for | Limits |
| - | - | - |
| User session | Console and interactive CLI access | The CLI manages secure storage and token renewal. |
| API key | CI, scripts, and servers | Keys cannot list, create, or revoke keys, or update budgets. |

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.

```bash theme={null}
curl --fail-with-body "$LUNAR_API_URL/v1/jobs" \
  -H "Authorization: Bearer $LUNAR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hello-lunar-001" \
  -d '{"name":"hello-lunar","gpu":"none","image":"python:3.12-slim","entrypoint":["python","main.py"]}'
```

The image, entrypoint, and GPU fields are currently orchestration metadata; the mock provider does not execute them.

| Request | Response |
| - | - |
| New key and job body | `201 Created` with the new job. |
| Same account, key, and body | `200 OK` with the original job. |
| Same account and key, different body | `409 Conflict`, code `idempotency_conflict`. |

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`.

| Endpoints | Order | Cursor | Page size |
| - | - | - | - |
| Projects, jobs, API keys, usage records | Newest first | Opaque string | Default 50; maximum 100. |
| Job events and logs | Sequence, oldest first | Event sequence, starting at `0` | Default 100; maximum 500. |

`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:

```json theme={null}
{
  "error": {
    "code": "idempotency_conflict",
    "message": "The idempotency key was already used for another request."
  },
  "request_id": "request-example"
}
```

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.

| Status | Meaning | Next step |
| - | - | - |
| `401` | Missing, invalid, expired, or revoked credential | Sign in again or check your API key. |
| `403` | The credential cannot perform the operation | Use a user session for key management or budget changes. |
| `404` | The resource is unavailable to this account | Check the ID and active account. |
| `409` | Idempotency, job state, or an account limit prevents the request | Inspect `error.code` and the job or account state. |
| `422` | Request validation failed | Check `error.details` and the endpoint schema. |
| `429` | Request rate exceeded | Wait for the `Retry-After` interval before retrying. |
| `503` | A service dependency is unavailable | Retry later; retain the request ID if the issue persists. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.