Skip to main content
v1Stable
A task represents a conversation thread with an Apollo-1 agent. Create a task before sending messages, and use the task ID to scope all interactions within that thread.

​
Create a Task

Creates a new conversation thread and returns a welcome message from the agent.
cURL
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",
    "task_origin_type": "web-widget"
  }'

​
POST /v1/messaging/tasks

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

​
Headers

HeaderRequiredDescription
x-aui-api-keyYesYour API key
x-aui-organization-idYesOrganization identifier
x-aui-account-idYesAccount identifier
Content-TypeYesMust be application/json

​
Request Body

​
agent_id
string
required
The agent management ID. Apollo resolves the network and active version from this.
​
user_id
string
required
Unique identifier for the user starting the conversation.
​
task_origin_type
string
default:"web-widget"
Origin of the conversation. Common values: web-widget, api, third-party.
​
version_id
string
Pin the thread to a specific draft version. If omitted, uses the agent’s active version.
​
version_tag
string
Pin the thread to a specific revision tag (e.g., v8.14).

​
Response

​
id
string
Unique task identifier. Use this as task_id when sending messages.
​
user_id
string
The user identifier provided in the request.
​
title
string
Auto-generated task title.
​
welcome_message
string
The agent’s initial greeting message.
​
followup_suggestions
array
AI-generated conversation starter suggestions.
{
  "id": "task_68e78d0dc5a4b19a030d03d6",
  "user_id": "user_xyz789",
  "title": "New Conversation",
  "welcome_message": "Hi! I'm here to help you with your account. What can I assist you with today?",
  "followup_suggestions": [
    "Check my recent transactions",
    "Dispute a charge",
    "Update my contact information"
  ]
}

​
Code Examples

const response = await fetch(
  "https://api.aui.io/v1/messaging/tasks",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-aui-api-key": "your-api-key",
      "x-aui-organization-id": "your-org-id",
      "x-aui-account-id": "your-account-id"
    },
    body: JSON.stringify({
      agent_id: "agent_abc123",
      user_id: "user_xyz789",
      task_origin_type: "api"
    }),
  }
);

const task = await response.json();
console.log(task.id);               // Use as task_id for messages
console.log(task.welcome_message);

​
Get Task Trace

Retrieve the complete reasoning trace for all interactions in a task.
cURL
curl "https://api.aui.io/v1/messaging/tasks/task_123/trace-info" \
  -H "x-aui-api-key: your-api-key"

​
GET /v1/messaging/tasks/{task_id}/trace-info

Returns an array of interaction traces — one per message exchange in the thread. Each trace contains:
  • Intent parsing results
  • Entities resolved
  • Rules evaluated
  • Parameters extracted
  • Tools invoked
  • Decisions made
​
task_id
string
required
The task identifier.

​
Query Parameters

​
interaction_id
string
Optional. Fetch a single interaction’s trace instead of all traces.
[
  {
    "interaction_id": "int_507f1f77bcf86cd799439011",
    "intent": "dispute_charge",
    "entities": {
      "transaction_id": "txn_abc123",
      "transaction_date": "2026-05-30"
    },
    "rules_evaluated": [
      {
        "rule_id": "rule_dispute_window",
        "predicate": "today - txn.date <= 8 days",
        "result": "blocked",
        "reason": "Transaction is 10 days old, exceeds 8-day dispute window"
      }
    ],
    "tools_considered": ["create_dispute"],
    "tools_invoked": [],
    "decision": "block_with_explanation"
  }
]

​
Errors

StatusDescription
401Missing or invalid x-aui-api-key header
403Insufficient permissions for the specified agent
422Validation error — invalid request parameters
401
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
422
{
  "error": "Validation Error",
  "details": [
    {
      "field": "agent_id",
      "message": "agent_id is required"
    }
  ]
}