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

# Send Messages

> Send messages to Apollo-1 agents and receive complete responses with traces.

<div style={{ display: 'flex', gap: '8px', marginBottom: '16px' }}>
  <span style={{ background: '#22C55E', color: '#fff', padding: '2px 10px', borderRadius: '12px', fontSize: '13px', fontWeight: 500 }}>v1</span>
  <span style={{ background: 'rgba(129,105,255,0.15)', color: '#8169FF', padding: '2px 10px', borderRadius: '12px', fontSize: '13px', fontWeight: 500 }}>Stable</span>
</div>

## Send a Message

Send a message to an Apollo-1 agent and receive the complete response, optionally including the symbolic reasoning trace.

```bash cURL theme={null}
curl -X POST "https://api.aui.io/v1/messaging/messages?include_trace=true" \
  -H "Content-Type: application/json" \
  -H "x-aui-api-key: your-api-key" \
  -d '{
    "type": "message",
    "task_id": "task_68e78d0dc5a4b19a030d03d6",
    "text": "I want to dispute a charge from May 30th"
  }'
```

### POST `/v1/messaging/messages`

**Base URL:** `https://api.aui.io`

#### Headers

| Header          | Required | Description                |
| --------------- | -------- | -------------------------- |
| `x-aui-api-key` | Yes      | Your API key               |
| `Content-Type`  | Yes      | Must be `application/json` |

#### Query Parameters

<ParamField query="include_trace" type="boolean" default="false">
  Include the symbolic reasoning trace in the response. Adds `trace_info` field.
</ParamField>

#### Request Body

<ParamField body="type" type="string" required>
  Message type. Must be `"message"`.
</ParamField>

<ParamField body="task_id" type="string" required>
  The task identifier (conversation thread).
</ParamField>

<ParamField body="text" type="string" required>
  The message content to send to the agent.
</ParamField>

<ParamField body="agent_settings_bundle" type="object">
  Optional agent configuration bundle to test local changes without deploying.

  <Expandable title="bundle structure">
    ```json theme={null}
    {
      "agent": { /* agent.aui.json */ },
      "parameters": [ /* parameters.aui.json */ ],
      "entities": [ /* entities.aui.json */ ],
      "rules": [ /* rules.aui.json */ ],
      "tools": [ /* tools/*.aui.json */ ],
      "integrations": [ /* integrations.aui.json */ ]
    }
    ```

    The bundle is validated before execution. Invalid configurations return a 422 error.
  </Expandable>
</ParamField>

#### Response

Returns a message response object containing the agent's reply.

<ResponseField name="id" type="string">
  Unique message identifier. This is also the interaction ID used for rerun and trace endpoints.
</ResponseField>

<ResponseField name="text" type="string">
  The agent's response message.
</ResponseField>

<ResponseField name="followup_suggestions" type="array">
  AI-generated follow-up question suggestions.
</ResponseField>

<ResponseField name="trace_info" type="object">
  Symbolic reasoning trace (only included when `?include_trace=true`).

  <Expandable title="trace structure">
    <ResponseField name="trace_info.intent" type="string">
      The parsed user intent.
    </ResponseField>

    <ResponseField name="trace_info.entities" type="object">
      Entities extracted from the conversation.
    </ResponseField>

    <ResponseField name="trace_info.rules_evaluated" type="array">
      Rules that were evaluated, including predicates and results.
    </ResponseField>

    <ResponseField name="trace_info.parameters_extracted" type="array">
      Parameters collected during the interaction.
    </ResponseField>

    <ResponseField name="trace_info.tools_invoked" type="array">
      Tools that were called to fulfill the request.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "msg_507f1f77bcf86cd799439011",
    "text": "I understand you want to dispute a charge from May 30th. However, our dispute policy allows disputes only within 8 days of the transaction date. Since today is June 9th, that transaction is 10 days old and falls outside our dispute window.",
    "followup_suggestions": [
      "What other options do I have?",
      "Can I speak to a supervisor?",
      "Show me my recent transactions"
    ],
    "trace_info": {
      "intent": "dispute_charge",
      "entities": {
        "transaction_date": "2026-05-30",
        "days_since_transaction": 10
      },
      "rules_evaluated": [
        {
          "rule_id": "rule_dispute_window",
          "predicate": "today - txn.date <= 8 days",
          "result": "blocked",
          "reason": "Transaction exceeds 8-day dispute window"
        }
      ],
      "parameters_extracted": ["transaction_date"],
      "tools_invoked": []
    }
  }
  ```
</ResponseExample>

***

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.aui.io/v1/messaging/messages?include_trace=true",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-aui-api-key": "your-api-key"
      },
      body: JSON.stringify({
        type: "message",
        task_id: "task_68e78d0dc5a4b19a030d03d6",
        text: "I want to dispute a charge from May 30th"
      })
    }
  );

  const message = await response.json();
  console.log(message.text);
  console.log(message.trace_info);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.aui.io/v1/messaging/messages",
      params={"include_trace": "true"},
      headers={
          "Content-Type": "application/json",
          "x-aui-api-key": "your-api-key"
      },
      json={
          "type": "message",
          "task_id": "task_68e78d0dc5a4b19a030d03d6",
          "text": "I want to dispute a charge from May 30th"
      }
  )

  message = response.json()
  print(message["text"])
  print(message["trace_info"])
  ```

  ```bash cURL with Bundle theme={null}
  curl -X POST "https://api.aui.io/v1/messaging/messages" \
    -H "Content-Type: application/json" \
    -H "x-aui-api-key: your-api-key" \
    -d '{
      "type": "message",
      "task_id": "task_123",
      "text": "Test message",
      "agent_settings_bundle": {
        "agent": {
          "name": "Test Agent",
          "description": "Testing configuration"
        },
        "rules": [
          {
            "id": "rule_test",
            "type": "policy",
            "predicate": "amount < 100",
            "action": "allow"
          }
        ]
      }
    }'
  ```
</CodeGroup>

***

## Rerun an Interaction

Regenerate a previous interaction with edited text or updated agent configuration.

```bash cURL theme={null}
curl -X POST "https://api.aui.io/v1/messaging/messages/rerun?include_trace=true" \
  -H "Content-Type: application/json" \
  -H "x-aui-api-key: your-api-key" \
  -H "x-aui-user-id: user_xyz789" \
  -d '{
    "task_id": "task_123",
    "interaction_id": "msg_507f1f77bcf86cd799439011",
    "text": "Actually, the charge was from June 1st",
    "agent_id": "agent_abc123"
  }'
```

### POST `/v1/messaging/messages/rerun`

#### Headers

| Header          | Required | Description                                  |
| --------------- | -------- | -------------------------------------------- |
| `x-aui-api-key` | Yes      | Your API key                                 |
| `x-aui-user-id` | Yes      | User identifier (acting user for this rerun) |
| `Content-Type`  | Yes      | Must be `application/json`                   |

#### Query Parameters

<ParamField query="include_trace" type="boolean" default="false">
  Include trace info in the regenerated response.
</ParamField>

#### Request Body

<ParamField body="task_id" type="string" required>
  The original task identifier.
</ParamField>

<ParamField body="interaction_id" type="string" required>
  The message ID to regenerate (from a previous send-message response).
</ParamField>

<ParamField body="text" type="string" required>
  The message to replay (can be the original or edited).
</ParamField>

<ParamField body="agent_id" type="string" required>
  The agent management ID.
</ParamField>

<ParamField body="version_id" type="string">
  Pin to a specific version for this rerun.
</ParamField>

<ParamField body="version_tag" type="string">
  Pin to a specific revision tag.
</ParamField>

<ParamField body="agent_settings_bundle" type="object">
  Optional agent configuration bundle to test changes.
</ParamField>

#### Response

<ResponseField name="regenerated_task_id" type="string">
  The new task ID created for the regenerated conversation branch.
</ResponseField>

<ResponseField name="message" type="object">
  The agent's response in the regenerated branch (same structure as send-message response).
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "regenerated_task_id": "task_new_abc789",
    "message": {
      "id": "msg_new_123",
      "text": "I can help you dispute that charge from June 1st. Since that was 8 days ago, it falls within our dispute window. Let me start the process.",
      "followup_suggestions": [
        "What's the dispute amount?",
        "Why are you disputing this charge?",
        "Show me the transaction details"
      ],
      "trace_info": {
        "intent": "dispute_charge",
        "entities": {
          "transaction_date": "2026-06-01",
          "days_since_transaction": 8
        },
        "rules_evaluated": [
          {
            "rule_id": "rule_dispute_window",
            "predicate": "today - txn.date <= 8 days",
            "result": "allowed",
            "reason": "Transaction is within 8-day dispute window"
          }
        ],
        "tools_invoked": ["start_dispute_process"]
      }
    }
  }
  ```
</ResponseExample>

***

## Errors

| Status | Description                                                      |
| ------ | ---------------------------------------------------------------- |
| `401`  | Missing or invalid `x-aui-api-key` header                        |
| `422`  | Validation error — invalid request parameters or agent bundle    |
| `400`  | Application error — may include moderation or processing details |

```json 401 theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

```json 422 - Invalid Bundle theme={null}
{
  "error": "Validation Error",
  "message": "Agent settings bundle failed validation",
  "details": [
    {
      "file": "rules.aui.json",
      "field": "predicate",
      "message": "Invalid predicate syntax"
    }
  ]
}
```

```json 422 - Missing Parameters theme={null}
{
  "error": "Validation Error",
  "details": [
    {
      "field": "task_id",
      "message": "task_id is required"
    }
  ]
}
```