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

# API Overview

> Overview of the Auriko API, endpoints, and response format.

The Auriko API is OpenAI-compatible. You can use the OpenAI SDK with a base URL change.

## Base URL

```
https://api.auriko.ai/v1
```

## Make a request

Send a chat completion request:

<CodeGroup>
  ```python Python OpenAI theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "What is the capital of France?"}]
  )

  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "What is the capital of France?" }],
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  import os
  from auriko import Client

  client = Client(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "What is the capital of France?"}]
  )

  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript Auriko theme={null}
  import { Client } from "@auriko/sdk";

  const client = new Client({
      apiKey: process.env.AURIKO_API_KEY,
      baseUrl: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "What is the capital of France?" }],
  });

  console.log(response.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "What is the capital of France?"}]
    }'
  ```
</CodeGroup>

To stream the response, set `stream` to `true`:

<CodeGroup>
  ```python Python OpenAI theme={null}
  stream = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Explain quantum computing in one paragraph."}],
      stream=True
  )

  for chunk in stream:
      if chunk.choices and chunk.choices[0].delta.content:
          print(chunk.choices[0].delta.content, end="", flush=True)
  ```

  ```typescript TypeScript OpenAI theme={null}
  const stream = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Explain quantum computing in one paragraph." }],
      stream: true,
  });

  for await (const chunk of stream) {
      if (chunk.choices[0]?.delta?.content) {
          process.stdout.write(chunk.choices[0].delta.content);
      }
  }
  ```

  ```python Python Auriko theme={null}
  stream = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Explain quantum computing in one paragraph."}],
      stream=True
  )

  for chunk in stream:
      if chunk.choices and chunk.choices[0].delta.content:
          print(chunk.choices[0].delta.content, end="", flush=True)
  ```

  ```typescript TypeScript Auriko theme={null}
  const stream = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Explain quantum computing in one paragraph." }],
      stream: true,
  });

  for await (const chunk of stream) {
      if (chunk.choices[0]?.delta?.content) {
          process.stdout.write(chunk.choices[0].delta.content);
      }
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "Explain quantum computing in one paragraph."}],
      "stream": true
    }'
  ```
</CodeGroup>

To optimize for cost, add routing options:

<CodeGroup>
  ```python Python OpenAI theme={null}
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Summarize the benefits of cloud computing."}],
      extra_body={"gateway": {"routing": {"optimize": "cost"}}}
  )

  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript OpenAI theme={null}
  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Summarize the benefits of cloud computing." }],
      gateway: { routing: { optimize: "cost" } },
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Summarize the benefits of cloud computing."}],
      gateway={"routing": {"optimize": "cost"}}
  )

  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript Auriko theme={null}
  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Summarize the benefits of cloud computing." }],
      gateway: { routing: { optimize: "cost" } },
  });

  console.log(response.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "Summarize the benefits of cloud computing."}],
      "gateway": {"routing": {"optimize": "cost"}}
    }'
  ```
</CodeGroup>

## Endpoints

| Endpoint                                                                                        | Method | Description                      |
| ----------------------------------------------------------------------------------------------- | ------ | -------------------------------- |
| [`/v1/chat/completions`](/api-reference/chat-completions)                                       | POST   | Create a chat completion         |
| [`/v1/responses`](/api-reference/create-response)                                               | POST   | Create a response (Response API) |
| [`/v1/models`](/api-reference/list-callable-models)                                             | GET    | List callable models             |
| [`/v1/models/{model_id}`](/api-reference/retrieve-callable-model)                               | GET    | Retrieve callable model          |
| [`/v1/me`](/api-reference/get-api-key-identity)                                                 | GET    | Get API key identity             |
| [`/v1/registry/providers`](/api-reference/provider-catalog)                                     | GET    | Provider catalog                 |
| [`/v1/registry/models`](/api-reference/canonical-model-records)                                 | GET    | Canonical model records          |
| [`/v1/directory/models`](/api-reference/model-directory)                                        | GET    | Model directory                  |
| [`/v1/byok/providers`](/api-reference/list-byok-providers)                                      | GET    | BYOK provider discovery          |
| [`/v1/byok/providers/{provider}/tiers`](/api-reference/get-byok-provider-tiers)                 | GET    | BYOK provider account tiers      |
| [`/v1/workspaces/{workspace_id}/api-keys`](/api-reference/list-api-keys)                        | GET    | List API keys                    |
| [`/v1/workspaces/{workspace_id}/api-keys/{api_key_id}`](/api-reference/get-api-key)             | GET    | Get API key                      |
| [`/v1/workspaces/{workspace_id}/api-keys/{api_key_id}/usage`](/api-reference/get-api-key-usage) | GET    | Get API key usage                |
| [`/v1/workspaces/{workspace_id}/api-keys`](/api-reference/create-api-key)                       | POST   | Create API key                   |
| [`/v1/workspaces/{workspace_id}/api-keys/{api_key_id}`](/api-reference/update-api-key)          | PATCH  | Update API key                   |
| [`/v1/workspaces/{workspace_id}/api-keys/{api_key_id}`](/api-reference/delete-api-key)          | DELETE | Revoke API key                   |
| [`/v1/workspaces/{workspace_id}/byok-keys`](/api-reference/list-byok-keys)                      | GET    | List BYOK keys                   |
| [`/v1/workspaces/{workspace_id}/byok-keys/{byok_key_id}`](/api-reference/get-byok-key)          | GET    | Get BYOK key                     |
| [`/v1/workspaces/{workspace_id}/byok-keys`](/api-reference/create-byok-key)                     | POST   | Create BYOK key                  |
| [`/v1/workspaces/{workspace_id}/byok-keys/{byok_key_id}`](/api-reference/update-byok-key)       | PATCH  | Update BYOK key                  |
| [`/v1/workspaces/{workspace_id}/byok-keys/{byok_key_id}`](/api-reference/delete-byok-key)       | DELETE | Delete BYOK key                  |
| [`/v1/workspaces/{workspace_id}/billing/balance`](/api-reference/get-credit-balance)            | GET    | Credit balance                   |

## OpenAI compatibility

Auriko supports the same request/response format as OpenAI. Switch to Auriko by changing two values:

1. **Base URL:** `https://api.openai.com/v1` → `https://api.auriko.ai/v1`
2. **API Key:** Use your Auriko API key (starts with `ak_`)

## Auriko extensions

Auriko responses carry additional fields beyond the OpenAI format.

### Response extensions

Every chat completion response includes a `routing_metadata` object with routing and cost details:

```json theme={null}
{
  "routing_metadata": {
    "provider": "openai",
    "provider_model_id": "gpt-4o-2024-08-06",
    "model_canonical": "gpt-4o",
    "routing_strategy": "balanced",
    "ttft_ms": 312,
    "cost": {
      "usd": 0.00015
    },
    "warnings": []
  }
}
```

When the gateway had to modify or ignore part of the request, `warnings` carries one or more structured entries:

```json theme={null}
{
  "routing_metadata": {
    "provider": "openai",
    "provider_model_id": "gpt-4o-2024-08-06",
    "model_canonical": "gpt-4o",
    "routing_strategy": "balanced",
    "warnings": [
      {
        "type": "unsupported_parameter",
        "code": "seed",
        "message": "Parameter 'seed' is not supported by the selected provider."
      }
    ]
  }
}
```

See [Response metadata](/contract/response-metadata) for the full field reference.

### Request extensions

Pass routing options to optimize your requests via the `gateway` field:

```json theme={null}
{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "Hello!"}],
  "gateway": {
    "routing": {
      "optimize": "cost",
      "max_ttft_ms": 1000
    }
  }
}
```

### Request metadata

Attach custom metadata to requests for tracking and observability via `gateway.metadata`. Auriko strips this metadata before forwarding to the provider.

```json theme={null}
{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "Hello!"}],
  "gateway": {
    "metadata": {
      "tags": ["production", "chatbot"],
      "user_id": "user_abc123",
      "trace_id": "trace_xyz789",
      "custom_fields": {
        "environment": "production",
        "feature": "customer-support"
      }
    }
  }
}
```

| Field           | Type                     | Limits                                                 |
| --------------- | ------------------------ | ------------------------------------------------------ |
| `tags`          | `string[]`               | Max 100 tags, each max 50 chars                        |
| `user_id`       | `string`                 | Max 255 chars                                          |
| `trace_id`      | `string`                 | Max 255 chars                                          |
| `custom_fields` | `Record<string, string>` | Max 10 fields, keys max 50 chars, values max 200 chars |

## Response headers

Every response carries custom headers. See [Response headers](/contract/response-headers) for the full reference.

<Card title="Authentication" icon="key" href="/api-reference/authentication">
  Learn how to authenticate your requests
</Card>