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

​
Create a Task

Creates a new conversation task and returns a welcome message from the agent.
cURL
curl -X POST "https://data-services.aui.io/api/ia-controller/api/v1/external/tasks" \
  -H "Content-Type: application/json" \
  -H "x-network-api-key: your-api-key" \
  -d '{"user_id": "user_123"}'

​
POST /api/v1/external/tasks

Base URL: https://data-services.aui.io/api/ia-controller

​
Headers

HeaderRequiredDescription
x-network-api-keyYesYour network API key
Content-TypeYesMust be application/json

​
Request Body

​
user_id
string
required
Unique identifier for the user starting the conversation.

​
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": "68e78d0dc5a4b19a030d03d6",
  "user_id": "user_123",
  "title": "New Conversation",
  "welcome_message": "Hi! I'm here to help you find the perfect product. What are you looking for today?",
  "followup_suggestions": [
    "Show me your best sellers",
    "I need help choosing a product",
    "What's on sale right now?"
  ]
}

​
Code Examples

const response = await fetch(
  "https://data-services.aui.io/api/ia-controller/api/v1/external/tasks",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-network-api-key": "your-api-key",
    },
    body: JSON.stringify({ user_id: "user_123" }),
  }
);

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

​
List Tasks

Retrieves a paginated list of tasks for a specific user.
cURL
curl "https://data-services.aui.io/api/ia-controller/api/v1/external/tasks?user_id=user_123&page=1&size=10" \
  -H "x-network-api-key: your-api-key"

​
GET /api/v1/external/tasks

​
Headers

HeaderRequiredDescription
x-network-api-keyYesYour network API key

​
Query Parameters

​
user_id
string
required
Filter tasks by user identifier.
​
page
integer
default:"1"
Page number for pagination.
​
size
integer
default:"10"
Number of tasks per page.

​
Response

​
tasks
array
List of task objects.
​
total
integer
Total number of tasks for this user.
​
page
integer
Current page number.
​
size
integer
Number of tasks per page.
{
  "tasks": [
    {
      "id": "68e78d0dc5a4b19a030d03d6",
      "user_id": "user_123",
      "title": "Product Search",
      "welcome_message": "Hi! How can I help you today?",
      "followup_suggestions": []
    }
  ],
  "total": 24,
  "page": 1,
  "size": 10
}

​
Code Examples

const params = new URLSearchParams({
  user_id: "user_123",
  page: "1",
  size: "10",
});

const response = await fetch(
  `https://data-services.aui.io/api/ia-controller/api/v1/external/tasks?${params}`,
  {
    headers: { "x-network-api-key": "your-api-key" },
  }
);

const { tasks, total } = await response.json();
console.log(`${total} tasks found`);

​
Get Task Messages

Retrieves all messages in a specific task (conversation history).
cURL
curl "https://data-services.aui.io/api/ia-controller/api/v1/external/tasks/68e78d0dc5a4b19a030d03d6/messages" \
  -H "x-network-api-key: your-api-key"

​
GET /api/v1/external/tasks/{task_id}/messages

​
Headers

HeaderRequiredDescription
x-network-api-keyYesYour network API key

​
Path Parameters

​
task_id
string
required
The task identifier (ObjectId format).

​
Response

Returns an array of ExternalTaskMessage objects — the same format as the Send Message response. 
[
  {
    "id": "507f1f77bcf86cd799439011",
    "created_at": "2026-03-09T14:20:00.000Z",
    "text": "I am looking for a built-in microwave with at least 20 liters capacity",
    "sender": {
      "id": "user_123",
      "type": "user",
      "email": "customer@example.com"
    },
    "receiver": {
      "id": "agent_abc123",
      "type": "agent",
      "email": "agent@aui.io"
    },
    "options": [],
    "variants_options": [],
    "followup_suggestions": []
  },
  {
    "id": "507f1f77bcf86cd799439012",
    "created_at": "2026-03-09T14:22:01.000Z",
    "text": "I found several built-in microwaves with 20+ liters capacity. Here are the top options for you:",
    "sender": {
      "id": "agent_abc123",
      "type": "agent",
      "email": "agent@aui.io"
    },
    "receiver": {
      "id": "user_123",
      "type": "user",
      "email": "customer@example.com"
    },
    "options": [],
    "variants_options": [],
    "followup_suggestions": [
      "What is the price range?",
      "Do any of these come in stainless steel?",
      "Which one has the best energy rating?"
    ]
  }
]

​
Code Examples

const taskId = "68e78d0dc5a4b19a030d03d6";

const response = await fetch(
  `https://data-services.aui.io/api/ia-controller/api/v1/external/tasks/${taskId}/messages`,
  {
    headers: { "x-network-api-key": "your-api-key" },
  }
);

const messages = await response.json();
messages.forEach((msg) => {
  console.log(`[${msg.sender.type}] ${msg.text}`);
});