Skip to main content
v1Stable
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: 
x-aui-api-key: your-api-key
Additional scope headers: 
x-aui-organization-id: your-organization-id
x-aui-account-id: your-account-id

​
Core Concepts

Tasks (Threads)

A task represents a conversation thread with an agent. Create a task to start a new conversation, then send messages within it.

Messages

Send messages to an agent and receive responses, including follow-up suggestions. Optionally include your agent configuration bundle.

Rerun

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

Trace

Access the complete symbolic reasoning trace for any interaction — intents, entities, rules evaluated, and decisions made.

​
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

Create a thread
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"
  }'
Send a message
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"
  }'
Get trace
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: 
{
  "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

Create Tasks

Start conversation threads with agents.

Send Messages

Send messages and receive agent responses.

Get Trace

Inspect symbolic reasoning traces for interactions.

Authentication

API keys and authentication headers.

Errors

Error codes and response format.