# Models

List and retrieve models available through the Xantly gateway. The response is OpenAI-compatible and works with any tool or SDK that calls `GET /v1/models`.

- **GET** `/v1/models`, List all available models
- **GET** `/v1/models/:model_id`, Retrieve a specific model
- **Auth:** `Authorization: Bearer <token>`

---

## Quick start

```bash
curl -sS https://api.xantly.com/v1/models \
  -H "Authorization: Bearer $XANTLY_API_KEY"
```

---

## Response body

```json
{
  "object": "list",
  "data": [
    {
      "id": "claude-3-5-sonnet-20241022",
      "object": "model",
      "created": 1700000000,
      "owned_by": "anthropic"
    },
    {
      "id": "deepseek-chat",
      "object": "model",
      "created": 1700000000,
      "owned_by": "deepseek"
    },
    {
      "id": "gpt-4o",
      "object": "model",
      "created": 1700000000,
      "owned_by": "openai"
    },
    {
      "id": "text-embedding-3-small",
      "object": "model",
      "created": 1700000000,
      "owned_by": "openai"
    }
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `object` | `string` | Always `"list"`. |
| `data` | `array` | All active models in the Xantly catalog. |
| `data[].id` | `string` | Model slug, use this as the `model` field in `/v1/chat/completions` or `/v1/embeddings`. |
| `data[].object` | `string` | Always `"model"`. |
| `data[].created` | `integer` | Unix epoch. |
| `data[].owned_by` | `string` | Provider name (`"openai"`, `"anthropic"`, `"deepseek"`, `"groq"`, `"google"`, `"nvidia"`). |

---

## Retrieve a single model

```bash
curl -sS https://api.xantly.com/v1/models/gpt-4o \
  -H "Authorization: Bearer $XANTLY_API_KEY"
```

```json
{
  "id": "gpt-4o",
  "object": "model",
  "created": 1700000000,
  "owned_by": "openai"
}
```

Returns `404` if the model slug is not found in the active catalog.

---

## Notes

- The response is **dynamic**: it reflects models currently active in the Xantly catalog. New providers or models configured by your account admin appear automatically.
- Use `model: "auto"` in `/v1/chat/completions` to let Xantly pick the optimal model automatically, rather than pinning to a specific ID from this list.
- Both chat/completion models and embedding models are included in the response.

---

## Code examples

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XANTLY_API_KEY"],
    base_url="https://api.xantly.com/v1",
)

models = client.models.list()
for model in models.data:
    print(f"{model.id} ({model.owned_by})")
```

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XANTLY_API_KEY,
  baseURL: "https://api.xantly.com/v1",
});

const models = await client.models.list();
for (const model of models.data) {
  console.log(`${model.id} (${model.owned_by})`);
}
```

---

## Next steps

- [Chat Completions](/docs/chat-completions), Use a model ID from this list as the `model` field
- [Embeddings](/docs/embeddings), Create vector embeddings using embedding models