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

# Create a chat completion

> Start a turn with a Manyfold agent through the OpenAI-compatible Chat Completions shape.

Source: https://docs.manyfold.ai/api-reference/chat-completions/

```http
POST /api/v1/chat/completions
```

Auth: Bearer API token with chat.completions or api.full.
Quota: Counts against the monthly API request quota.

## Parameters

| Parameters | Required | Description |
| --- | --- | --- |
| `model` | Required | Manyfold agent id, for example agt_... |
| `messages` | Required | system/developer/user/assistant messages. A user message may include image_url and file content parts. |
| `stream` | Optional | Set true for Server-Sent Events. |
| `metadata.session_id` | Optional | Continue an existing Manyfold session returned by a previous turn. |
| `stream_options.include_usage` | Optional | When true, streaming can include a final usage chunk if usage is available. |

## Request

```bash
curl https://api.manyfold.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $MF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agt_your_agent_id",
    "messages": [
      { "role": "user", "content": "Summarize this repository." }
    ]
  }'
```

## Streaming

```bash
curl -N https://api.manyfold.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $MF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agt_your_agent_id",
    "stream": true,
    "stream_options": { "include_usage": true },
    "messages": [
      { "role": "user", "content": "Write a short release note." }
    ]
  }'
```

## Response

```json
{
    "object": "chat.completion",
    "model": "agt_your_agent_id",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "..."
            },
            "finish_reason": "stop"
        }
    ],
    "metadata": {
        "session_id": "cts_...",
        "assistant_message_id": "..."
    }
}
```

## Response

- Non-streaming responses return chat.completion with choices[0].message.content.
- metadata.session_id and x-session-id identify the Manyfold conversation.
- Streaming responses emit chat.completion.chunk events followed by data: [DONE].