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

# API Introduction

> Astrolabe Cloud gateway endpoints, authentication, headers, and error model.

Astrolabe Cloud exposes an OpenAI-compatible hosted gateway at:

```text theme={null}
https://api.astrolabe.run/v1
```

The gateway supports both Responses and Chat Completions while applying the same Cloud auth, balance, stack, routing, billing, and trace runtime.

## Endpoints

* `GET /health`
* `GET /ready`
* `GET /v1/models`
* `GET /v1/lanes`
* `POST /v1/responses`
* `POST /v1/chat/completions`

## Authentication

Send an Astrolabe Cloud workspace API key with one of:

```bash theme={null}
Authorization: Bearer $ASTROLABE_CLOUD_KEY
```

```bash theme={null}
x-api-key: $ASTROLABE_CLOUD_KEY
```

Requests without a valid active key are rejected.

## Models

Use virtual model IDs for most requests:

* `astrolabe/auto`
* `astrolabe/coding`
* `astrolabe/research`
* `astrolabe/vision`
* `astrolabe/strict-json`
* `astrolabe/cheap`
* `astrolabe/safe`

Use `GET /v1/models` to inspect the public catalog.

## Stack metadata

Select a stack and set per-request preferences with `metadata.astrolabe`:

```json theme={null}
{
  "metadata": {
    "astrolabe": {
      "stack": "code-agent",
      "quality": "high",
      "cost_mode": "balanced",
      "latency_slo_ms": 3000,
      "verification": "strict",
      "fallback": true,
      "explain": true
    }
  }
}
```

## Response headers

Important headers:

* `x-astrolabe-cloud-request-id`
* `x-astrolabe-cloud-workspace`
* `x-astrolabe-cloud-key`
* `x-ratelimit-limit`
* `x-ratelimit-remaining`
* `x-ratelimit-reset`
* `x-astrolabe-model`
* `x-astrolabe-stack-id`
* `x-astrolabe-stack-name`
* `x-astrolabe-stack-version`
* `x-astrolabe-policy-status`
* `x-astrolabe-decision`
* `x-astrolabe-selected-provider`
* `x-astrolabe-selected-model`

## Error shape

Errors use:

```json theme={null}
{
  "error": {
    "code": "payment_required",
    "message": "Workspace balance must stay above 1.00 USD before routing.",
    "requestId": "req_..."
  }
}
```

Log the request id for support and route trace lookup.