> ## 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.

# Anthropic Messages API — POST /v1/messages

> Send a conversation to an A2Agent model using the Anthropic Messages API format and receive a message response.

A2Agent uses the Anthropic Messages request and response shape at this endpoint. The examples below use Bearer Token authentication, as required by A2Agent. The model IDs are A2Agent model IDs and may be aliases controlled by A2Agent routing configuration.

## Endpoint

```http theme={null}
POST https://api.a2agent.me/v1/messages
```

## Request Headers

| Header | Required | Value |
| - | - | - |
| `Authorization` | Yes | `Bearer YOUR_API_KEY` |
| `anthropic-version` | Yes | `2023-06-01` |
| `Content-Type` | Yes | `application/json` |

Replace `YOUR_API_KEY` with the API key created in the A2Agent console.

> A2Agent uses `Authorization: Bearer` for this compatibility endpoint. Do not replace it with `x-api-key` unless A2Agent explicitly instructs you to do so.

## Request Body Parameters

<ParamField body="model" type="string" required>
  The ID of the model to use. For example: `deepseek-v4-pro`, `deepseek-v4-flash`, qwen3.8-max. See [List Models](https://a2agent.me/models) 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 a `role` and `content`.

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

    <ParamField body="content" type="string" required>
      The text content of the message, or an array of supported Anthropic content blocks.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="max_tokens" type="integer">
  Maximum output tokens. This field is required; a low value may end generation with `stop_reason: "max_tokens"`. The allowed maximum depends on the model and account.
</ParamField>

<ParamField body="temperature" type="number">
  Controls randomness: lower values are more deterministic and higher values more varied. The range and default depend on the model; use it or `top_p`, not both.
</ParamField>

<ParamField body="stream" type="boolean">
  When `true`, returns an SSE stream; when omitted or `false`, returns one complete JSON response. Anthropic streams use message/content-block events.
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus-sampling threshold. Lower values focus the output and higher values allow more candidates. The range and default depend on the model; use it or `temperature`, not both.
</ParamField>

### Message Object

Each item in `messages` must contain:

| Field | Type | Required | Description |
| - | - | - | - |
| `role` | string | Yes | `user` or `assistant`. |
| `content` | string or array | Yes | Plain text or Anthropic content blocks. |

For a basic text request, use a string:

```json theme={null}
{
  "role": "user",
  "content": "Hello"
}
```

## Example Request

```bash theme={null}
curl https://api.a2agent.me/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "max_tokens": 256,
    "messages": [
      {
        "role": "user",
        "content": "What is 2 + 2?"
      }
    ]
  }'
```

Use the exact model ID returned by `GET /v1/models`. Model IDs are case-sensitive.

## Example Response

````json theme={null}
```json
{
  "id": "chatcmpl-90a02bbe-f7a5-9cc6-9046-5a1251672edc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let’s work through this step by step.  
       We start with:  2 + 2
       When you add 2 and 2 together, you combine their values:2, then count 2 more: 3, 4. 
       So:  2 + 2 = 4.
       Final answer:  [boxed{4}]"
    }
  ],
  "model": "deepseek-v4-pro",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 78,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}
````

This is an observed response sample from A2Agent. The `id`, generated text, and token counts vary for each request. A2Agent may add, omit, or extend metadata fields over time.

## Reading the Text Response

Unlike an OpenAI Chat Completions response, the text is not located at `choices[0].message.content`. For a basic text response, read:

```text theme={null}
content[0].text
```

For example:

```javascript theme={null}
const text = response.content[0].text;
```

If a response contains multiple content blocks, inspect each block's `type` before reading its fields.

## Response Fields

The response follows the Anthropic message shape. The field path `content[]` refers to each content block in the `content` array.

| Field | Type | Description | How to use it |
| - | - | - | - |
| `id` | string | Unique identifier for the message. A2Agent may use an identifier such as `chatcmpl-...`. | Use for request tracing and support inquiries. |
| `type` | string | Message resource type, normally `"message"`. | Confirms that the response is a message object. |
| `role` | string | Role that produced the response, normally `"assistant"`. | Identifies the response as model output. |
| `content` | array | Ordered array of Anthropic content blocks. | Iterate through blocks to read text or other supported content. |
| `content[].type` | string | Content block type, such as `"text"`. | Check the block type before reading its fields. |
| `content[].text` | string | Text contained in a text content block. | Read this value for the model's text response. |
| `model` | string | Model ID associated with the request or response. | Useful for tracing the requested A2Agent model ID. It is not by itself proof of the final upstream model when A2Agent uses aliases or routing rules. |
| `stop_reason` | string or null | Reason generation stopped, such as `end_turn` or `max_tokens`. | Distinguish a normal completion from a token-limit stop. |
| `stop_sequence` | string or null | Stop sequence that ended generation, when returned. | Optional metadata; it may be omitted when no stop sequence was used. |
| `usage.input_tokens` | integer | Number of input tokens processed. | Use for usage reporting and cost estimation. |
| `usage.output_tokens` | integer | Number of output tokens generated. | Use for usage reporting and cost estimation. |
| `usage.cache_creation_input_tokens` | integer or null | Input tokens used to create a prompt cache, when supported. | Optional usage metadata. |
| `usage.cache_read_input_tokens` | integer or null | Input tokens read from a prompt cache, when supported. | Optional usage metadata. |

## Streaming

Set `"stream": true` to request server-sent events (SSE), if streaming is enabled for the selected model and account.

Anthropic streaming events are not the same as OpenAI `chat.completion.chunk` objects or the `[DONE]` marker. A standard Anthropic stream can contain events such as:

* `message_start`
* `content_block_start`
* `content_block_delta`
* `content_block_stop`
* `message_delta`
* `message_stop`

Text deltas are normally found in a `content_block_delta` event under a text delta object. Confirm the exact event sequence and fields against the A2Agent response before documenting streaming as generally available.