# Chat completions (OpenAI shape)

Source: https://immiscible.fly.dev/docs/api/post-v1-chat-completions

`POST /v1/chat/completions`

The OpenAI chat completions API, governed: routed under your policy, checked against budgets before the call, recorded. Streaming, tools and images pass through. The response is the provider's own plus an `immiscible` field and `x-immiscible-*` [headers](https://immiscible.fly.dev/docs/api/errors.md#headers). Send `x-immiscible-task-class` to say what the work is.

## Authentication

Workspace key. A gateway key (`ask_...`) issued under Keys in the console, sent as `Authorization: Bearer` or `x-api-key`. It binds traffic to a person or service, a team and optionally a task class.

## Request

curl:

```bash
curl -X POST "https://immiscible.fly.dev/v1/chat/completions" \
  -H "authorization: Bearer $IMMISCIBLE_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": "Categorise: card declined."
      }
    ]
  }'
```

Node:

```ts
const res = await fetch('https://immiscible.fly.dev/v1/chat/completions', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.IMMISCIBLE_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5.5',
    messages: [
      {
        role: 'user',
        content: 'Categorise: card declined.',
      },
    ],
  }),
});
const data = await res.json();
console.log(res.status, data);
```

Python:

```python
import os
import requests

res = requests.post(
    "https://immiscible.fly.dev/v1/chat/completions",
    headers={
        "authorization": f"Bearer {os.environ['IMMISCIBLE_KEY']}",
        "content-type": "application/json",
    },
    json={
        "model": "gpt-5.5",
        "messages": [
            {
                "role": "user",
                "content": "Categorise: card declined.",
            },
        ],
    },
)
print(res.status_code, res.json())
```

## Response

```json
{
  "id": "chatcmpl-9x",
  "object": "chat.completion",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "payments.declined" }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 14, "completion_tokens": 4, "total_tokens": 18 },
  "immiscible": { "taskId": "tsk_b5f8c335e4a6", "costMicros": 183, "routedTo": "openai/gpt-5.5", "enforcement": "shadow" }
}
```