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

# Messaging API

> Send messages to Apollo-1 agents and receive responses with full trace visibility.

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

The Messaging API lets you programmatically interact with Apollo-1 agents: create conversation threads, send messages, regenerate interactions, and inspect the symbolic reasoning traces.

## Base URL

```
https://api.aui.io/v1/messaging
```

## Authentication

All requests require the `x-aui-api-key` header:

```bash theme={null}
x-aui-api-key: your-api-key
```

Additional scope headers:

```bash theme={null}
x-aui-organization-id: your-organization-id
x-aui-account-id: your-account-id
```

## Core Concepts

<CardGroup cols={2}>
  <Card title="Tasks (Threads)" icon="message">
    A task represents a conversation thread with an agent. Create a task to start a new conversation, then send messages within it.
  </Card>

  <Card title="Messages" icon="paper-plane">
    Send messages to an agent and receive responses, including follow-up suggestions. Optionally include your agent configuration bundle.
  </Card>

  <Card title="Rerun" icon="rotate-right">
    Regenerate a previous interaction with edited text or updated agent configuration to test changes.
  </Card>

  <Card title="Trace" icon="code">
    Access the complete symbolic reasoning trace for any interaction — intents, entities, rules evaluated, and decisions made.
  </Card>
</CardGroup>

## How It Works

1. **Create a thread** — `POST /v1/messaging/tasks` with `agent_id` and `user_id` to start a conversation. Receive a task ID and welcome message.
2. **Send messages** — `POST /v1/messaging/messages` with your message text. Optionally include `agent_settings_bundle` to test local configuration changes.
3. **Inspect traces** — `GET /v1/messaging/tasks/{task_id}/trace-info` to see the symbolic computation: rules evaluated, parameters extracted, decisions made.
4. **Regenerate** — `POST /v1/messaging/messages/rerun` to replay an interaction with edited text or updated configuration.

## Quick Start

```bash Create a thread theme={null}
curl -X POST "https://api.aui.io/v1/messaging/tasks" \
  -H "Content-Type: application/json" \
  -H "x-aui-api-key: your-api-key" \
  -H "x-aui-organization-id: your-org-id" \
  -H "x-aui-account-id: your-account-id" \
  -d '{
    "agent_id": "agent_abc123",
    "user_id": "user_xyz789"
  }'
```

```bash Send a message 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_123",
    "text": "I want to dispute a charge"
  }'
```

```bash Get trace theme={null}
curl "https://api.aui.io/v1/messaging/tasks/task_123/trace-info" \
  -H "x-aui-api-key: your-api-key"
```

## Key Features

### Agent Settings Bundle

Send your local agent configuration with messages to test changes without deploying:

```json theme={null}
{
  "task_id": "task_123",
  "text": "Your message",
  "agent_settings_bundle": {
    "agent": { /* agent.aui.json */ },
    "parameters": [ /* parameters.aui.json */ ],
    "entities": [ /* entities.aui.json */ ],
    "rules": [ /* rules.aui.json */ ],
    "tools": [ /* tools/*.aui.json */ ]
  }
}
```

The bundle is validated before execution — invalid configurations are rejected.

### Trace Visibility

Every interaction produces a complete symbolic trace:

* **Intent parsing** — How the user's message was understood
* **Entities resolved** — What values were extracted
* **Rules evaluated** — Which predicates fired or blocked actions
* **Parameters extracted** — What information was collected
* **Decisions made** — Which tools were invoked and why

Include `?include_trace=true` on message endpoints, or fetch traces separately.

## Explore the API

<CardGroup cols={2}>
  <Card title="Create Tasks" icon="plus" href="/messaging-api/tasks">
    Start conversation threads with agents.
  </Card>

  <Card title="Send Messages" icon="paper-plane" href="/messaging-api/send-message">
    Send messages and receive agent responses.
  </Card>

  <Card title="Get Trace" icon="code" href="/messaging-api/trace">
    Inspect symbolic reasoning traces for interactions.
  </Card>

  <Card title="Authentication" icon="key" href="/messaging-api/authentication">
    API keys and authentication headers.
  </Card>

  <Card title="Errors" icon="circle-exclamation" href="/messaging-api/errors">
    Error codes and response format.
  </Card>
</CardGroup>