## Download

- **YAML (full spec):** [openapi-spec.yaml](/content/docs/02-api-reference/openapi-spec.yaml)
- Production base URL: `https://api.xantly.com/v1`
- Local dev base URL: `http://localhost:8085/v1`

```bash
# Local dev server copy
curl -O http://localhost:5173/content/docs/02-api-reference/openapi-spec.yaml
```

## Importing the spec

- **Postman / Insomnia:** Import from URL and paste the YAML link above.
- **Hoppscotch:** Collections → Import → From URL → YAML link above.
- **VS Code / IntelliJ HTTP client:** Add the YAML file to your workspace; tooling will offer request snippets.
- **cURL/HTTPie:** Use the YAML only to discover schema; requests are standard OpenAI-compatible `POST /v1/chat/completions`.

## Quick preview

```yaml
openapi: 3.1.0
info:
  title: Xantly Gateway API
  version: 1.0.0
servers:
  - url: https://api.xantly.com/v1
    description: Production
  - url: http://localhost:8085/v1
    description: Local development
paths:
  /chat/completions:
    post:
      summary: Create chat completion
    head:
      summary: Probe chat completion endpoint
  /models:
    get:
      summary: List available models
  /embeddings:
    post:
      summary: Create embeddings
components:
  schemas:
    ChatCompletionRequest: {...}
    ChatCompletionResponse: {...}
    XantlyOrchestration: {...}
    XantlyMetadata: {...}
    EmbeddingRequest: {...}
    EmbeddingResponse: {...}
    ListModelsResponse: {...}
```

## What’s included

- `POST /chat/completions` and `HEAD /chat/completions`
- `GET /models`, dynamic catalog listing
- `POST /embeddings`, vector embedding generation
- Full request/response schemas, including Xantly extensions:
  - `routing_hints`, `routing_override`, `xantly` orchestration block
  - Complete `xantly_metadata` with cost, savings, routing visibility, and BYOK attribution
  - Voice, memory, caching, reliability, tool-calling, and streaming options
- 402 Payment Required for quota/budget exceeded scenarios
- Error schema aligned with OpenAI-compatible shape

## Change management

- Source of truth is the live YAML linked above (kept in sync with backend and docs).
- If you need a pinned version, download the YAML and commit it to your client repo.