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

# Chat with an AI Agent

> Send a message to an AI agent and receive a response

### Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Body

<ParamField body="messages" type="array" required>
  Array of message objects containing the conversation history

  <Expandable title="Message Object">
    <ParamField body="role" type="string" required>
      The role of the message sender (`user` or `assistant`)
    </ParamField>

    <ParamField body="parts" type="array" required>
      Array of content parts for the message

      <Expandable title="Part Object">
        <ParamField body="type" type="string" required>
          The type of part (`text`, `file`, etc.)
        </ParamField>

        <ParamField body="text" type="string">
          The text content (required when type is `text`)
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="agentId" type="number" required>
  The ID of the AI agent to chat with
</ParamField>

<ParamField body="threadId" type="string">
  Optional UUID for the conversation thread. If not provided, a new one will be generated
</ParamField>

<ParamField body="upstreamConversationId" type="string">
  Optional UUID to link this conversation to an upstream conversation
</ParamField>

### Headers

<ParamField header="X-Stream-Response" type="boolean" default="true">
  Controls whether the response is streamed. Set to `false` for non-streaming responses
</ParamField>

### Response

<ResponseField name="messages" type="array">
  Array of message objects containing the conversation, including the AI's response

  <Expandable title="Message Object">
    <ResponseField name="role" type="string">
      The role of the message sender (`user` or `assistant`)
    </ResponseField>

    <ResponseField name="parts" type="array">
      Array of content parts for the message

      <Expandable title="Part Object">
        <ResponseField name="type" type="string">
          The type of part (`text`, `tool-invocation`, `tool-result`, etc.)
        </ResponseField>

        <ResponseField name="text" type="string">
          The text content (when type is `text`)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="toolCalls" type="array">
      Optional array of tool calls made by the assistant
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="X-Thread-ID" type="string" required>
  The conversation thread ID (returned in headers)
</ResponseField>

### Examples

### Examples

<CodeGroup>
  ```curl theme={null}
  curl -X POST https://api.example.com/chat \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -H "X-Stream-Response: false" \
    -d '{
      "messages": [
        {
          "role": "user",
          "parts": [{"type": "text", "text": "Hello, how are you?"}]
        }
      ],
      "agentId": 123
    }'
  ```

  ```python theme={null}
  import requests

  url = "https://api.example.com/chat"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
      "X-Stream-Response": "false"
  }
  data = {
      "messages": [
          {
              "role": "user",
              "parts": [{"type": "text", "text": "Hello, how are you?"}]
          }
      ],
      "agentId": 123
  }

  response = requests.post(url, headers=headers, json=data)
  print(response.json())
  ```

  ```javascript theme={null}
  const response = await fetch('https://api.example.com/chat', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json',
      'X-Stream-Response': 'false'
    },
    body: JSON.stringify({
      messages: [
        {
          role: 'user',
          parts: [{ type: 'text', text: 'Hello, how are you?' }]
        }
      ],
      agentId: 123
    })
  });

  const data = await response.json();
  ```

  ```php theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.example.com/chat",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer YOUR_TOKEN",
      "Content-Type: application/json",
      "X-Stream-Response: false"
    ],
    CURLOPT_POSTFIELDS => json_encode([
      "messages" => [
        [
          "role" => "user",
          "parts" => [["type" => "text", "text" => "Hello, how are you?"]]
        ]
      ],
      "agentId" => 123
    ])
  ]);

  $response = curl_exec($curl);
  curl_close($curl);

  $data = json_decode($response, true);
  ```

  ```json theme={null}
  {
    "messages": [
      {
        "role": "user",
        "parts": [{"type": "text", "text": "Hello, how are you?"}]
      },
      {
        "role": "assistant",
        "parts": [{"type": "text", "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"}]
      }
    ]
  }
  ```
</CodeGroup>

### Error Codes

<ResponseField name="401" type="object">
  Unauthorized - Invalid or missing authentication
</ResponseField>

<ResponseField name="404" type="object">
  Not Found - Agent or organization not found
</ResponseField>

<ResponseField name="400" type="object">
  Bad Request - Invalid request body
</ResponseField>

<ResponseField name="500" type="object">
  Internal Server Error - Unexpected error occurred
</ResponseField>