Create Tasks

Start conversation threads with Apollo-1 agents.

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

Header	Required	Description
x-aui-api-key	Yes	Your API key
x-aui-organization-id	Yes	Organization identifier
x-aui-account-id	Yes	Account identifier
Content-Type	Yes	Must 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.

201

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

Node.js

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.

200

[
  {
    "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

Status	Description
401	Missing or invalid x-aui-api-key header
403	Insufficient permissions for the specified agent
422	Validation 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"
    }
  ]
}