---
title: POST /v1/chat/completions
description: "Create a chat completion — An OpenAI-compatible, stateless chat completion."
full: true
---

**Auth:** required. Send an `ivy_` API key (`Authorization: Bearer ivy_…`). See [Authentication](/docs/api/authentication).

An OpenAI-compatible, stateless chat completion. Your messages go straight to the model you name, with no .bloom* tools or conversation history added, so it works with OpenAI-compatible clients and evaluation frameworks. Set `stream` to `true` to receive server-sent events that end with `data: [DONE]`. Requires an `ivy_` API key; a signed-in session token is refused.

## Request

### Request body

- `model` (string) —
Model id. It is matched against the available models, then routed by its name.

- `messages` (object[]) —

- `stream` (boolean) —

- `max_tokens` (number) —

- `temperature` (number) —

- `tools` (object[]) —

- `tool_choice` (enum (&quot;auto&quot; | &quot;none&quot; | &quot;required&quot;) | object) —
`auto`, `none`, `required`, or a specific function.

## Responses

### `200` OK

The completion. With `stream: true` the body is `text/event-stream` instead.

Response shape:

- `id` (string) —

- `object` (enum (&quot;chat.completion&quot;)) —

- `created` (integer) —
Unix time in seconds.

- `model` (string) —
The model id you sent.

- `choices` (object[]) —

- `usage` (object) —

#### usage properties

- `prompt_tokens` (integer) —

- `completion_tokens` (integer) —

- `total_tokens` (integer) —

### `400` Bad Request

`model` is missing, `messages` is empty, or a message has no `role`

Response shape: `object`

### `401` Unauthorized

An `ivy_` API key is required

Response shape: `object`

### `405`

Only POST is allowed

Response shape: `object`

### `429` Too Many Requests

Rate limit exceeded

Response shape: `object`

### `502` Bad Gateway

The model provider call failed

Response shape: `object`

**curl**

```bash
curl -X POST 'https://ivybiosciences.com/api/v1/chat/completions' \
  -H "Authorization: Bearer $IVY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "",
  "messages": [
    {
      "role": "system"
    }
  ]
}'
```

**JavaScript**

```js
const res = await fetch('https://ivybiosciences.com/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.IVY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "model": "",
  "messages": [
    {
      "role": "system"
    }
  ]
}),
});
const data = await res.json();
```

**Python**

```python
import os, requests

res = requests.post(
    "https://ivybiosciences.com/api/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['IVY_API_KEY']}"},
    json={
  "model": "",
  "messages": [
    {
      "role": "system"
    }
  ]
},
)
data = res.json()
```
