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

# Chat Completions Endpoint — POST /v1/chat/completions

> Send a list of messages to any A2Agent model and receive a completion. The endpoint is fully compatible with the OpenAI Chat Completions request format.

The chat completions endpoint is the primary way to interact with A2Agent's models. It accepts the same request format as the OpenAI Chat Completions API, so any code that already works with OpenAI will work here after a single base URL change — no request restructuring required.

## Endpoint

```text theme={null}
POST https://api.a2agent.me/v1/chat/completions
```

## Request Headers

| Header          | Required | Value                 |
| --------------- | -------- | --------------------- |
| `Authorization` | Yes      | `Bearer YOUR_API_KEY` |
| `Content-Type`  | Yes      | `application/json`    |

## Request Body Parameters

<ParamField body="model" type="string" required>
  The ID of the model to use. For example: `deepseek-v4-pro`, `glm-5`, `kimi-k2.5`. See [List Models](/api-reference/models-list) for the full list of available IDs.
</ParamField>

<ParamField body="messages" type="array" required>
  An ordered array of message objects representing the conversation history. Each object must contain:

  <Expandable title="Message object fields">
    <ParamField body="role" type="string" required>
      The role of the message author. One of `"system"`, `"user"`, or `"assistant"`.
    </ParamField>

    <ParamField body="content" type="string" required>
      The text content of the message.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="max_tokens" type="integer">
  The maximum number of tokens to generate in the response. Defaults vary by model. Setting a lower value reduces cost and latency.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature between `0` and `2`. Higher values produce more varied output; lower values produce more deterministic output. Defaults to `1`.
</ParamField>

<ParamField body="stream" type="boolean">
  When `true`, the API streams the response as server-sent events (SSE) rather than returning a single JSON object. Defaults to `false`. See [Streaming](#streaming) for usage details.
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus sampling threshold. The model considers only the tokens comprising the top `top_p` probability mass. Defaults to `1`. Use either `temperature` or `top_p`, not both.
</ParamField>

## Example Request

```bash title="curl — basic chat completion request" theme={null}
curl https://api.a2agent.me/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is 2 + 2?"}
    ],
    "max_tokens": 256
  }'
```

## Example Response

```json title="200 OK — successful completion response" theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1720000000,
  "model": "deepseek-v4-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "2 + 2 equals 4."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 10,
    "total_tokens": 30
  }
}
```

## Streaming

Set `"stream": true` in your request body to receive the response incrementally as server-sent events. Each event contains a `delta` with a partial `content` string. The stream ends with a `[DONE]` message.

```python title="OpenAI SDK — streaming chat completion" theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.a2agent.me/v1"
)

stream = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Tell me a short story."}],
    stream=True
)

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

## Response Fields

<ResponseField name="id" type="string">
  A unique identifier for this completion, prefixed with `chatcmpl-`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"chat.completion"` for non-streaming responses.
</ResponseField>

<ResponseField name="created" type="integer">
  The Unix timestamp (seconds) at which the completion was created.
</ResponseField>

<ResponseField name="model" type="string">
  The model ID that generated the response, confirming which model handled the request.
</ResponseField>

<ResponseField name="choices" type="array">
  An array of completion choices. Most requests return a single choice at index `0`.

  <Expandable title="Choice object fields">
    <ResponseField name="choices[].message.role" type="string">
      The role of the response author. Always `"assistant"` for model-generated messages.
    </ResponseField>

    <ResponseField name="choices[].message.content" type="string">
      The generated text produced by the model.
    </ResponseField>

    <ResponseField name="choices[].finish_reason" type="string">
      The reason the model stopped generating. Possible values:

      * `stop` — the model reached a natural stopping point
      * `length` — the `max_tokens` limit was reached
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage.prompt_tokens" type="integer">
  The number of tokens in the input messages.
</ResponseField>

<ResponseField name="usage.completion_tokens" type="integer">
  The number of tokens in the generated response.
</ResponseField>

<ResponseField name="usage.total_tokens" type="integer">
  The sum of `prompt_tokens` and `completion_tokens`. This is the value used for billing.
</ResponseField>