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

# Tasks

> Create and manage conversation tasks with AUI agents.

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

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.

```bash cURL theme={null}
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

| Header              | Required | Description                |
| ------------------- | -------- | -------------------------- |
| `x-network-api-key` | Yes      | Your network API key       |
| `Content-Type`      | Yes      | Must be `application/json` |

#### Request Body

<ParamField body="user_id" type="string" required>
  Unique identifier for the user starting the conversation.
</ParamField>

#### Response

<ResponseField name="id" type="string">
  Unique task identifier. Use this as `task_id` when sending messages.
</ResponseField>

<ResponseField name="user_id" type="string">
  The user identifier provided in the request.
</ResponseField>

<ResponseField name="title" type="string">
  Auto-generated task title.
</ResponseField>

<ResponseField name="welcome_message" type="string">
  The agent's initial greeting message.
</ResponseField>

<ResponseField name="followup_suggestions" type="array">
  AI-generated conversation starter suggestions.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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?"
    ]
  }
  ```
</ResponseExample>

#### Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://data-services.aui.io/api/ia-controller/api/v1/external/tasks",
      headers={
          "Content-Type": "application/json",
          "x-network-api-key": "your-api-key",
      },
      json={"user_id": "user_123"},
  )

  task = response.json()
  print(task["id"])               # Use as task_id for messages
  print(task["welcome_message"])
  ```
</CodeGroup>

***

## List Tasks

Retrieves a paginated list of tasks for a specific user.

```bash cURL theme={null}
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

| Header              | Required | Description          |
| ------------------- | -------- | -------------------- |
| `x-network-api-key` | Yes      | Your network API key |

#### Query Parameters

<ParamField query="user_id" type="string" required>
  Filter tasks by user identifier.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="size" type="integer" default="10">
  Number of tasks per page.
</ParamField>

#### Response

<ResponseField name="tasks" type="array">
  List of task objects.
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of tasks for this user.
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number.
</ResponseField>

<ResponseField name="size" type="integer">
  Number of tasks per page.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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
  }
  ```
</ResponseExample>

#### Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  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`);
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://data-services.aui.io/api/ia-controller/api/v1/external/tasks",
      headers={"x-network-api-key": "your-api-key"},
      params={"user_id": "user_123", "page": 1, "size": 10},
  )

  data = response.json()
  print(f"{data['total']} tasks found")
  ```
</CodeGroup>

***

## Get Task Messages

Retrieves all messages in a specific task (conversation history).

```bash cURL theme={null}
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

| Header              | Required | Description          |
| ------------------- | -------- | -------------------- |
| `x-network-api-key` | Yes      | Your network API key |

#### Path Parameters

<ParamField path="task_id" type="string" required>
  The task identifier (ObjectId format).
</ParamField>

#### Response

Returns an array of `ExternalTaskMessage` objects — the same format as the [Send Message](/messaging-api/send-message) response.

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "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?"
      ]
    }
  ]
  ```
</ResponseExample>

#### Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  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}`);
  });
  ```

  ```python Python theme={null}
  task_id = "68e78d0dc5a4b19a030d03d6"

  response = requests.get(
      f"https://data-services.aui.io/api/ia-controller/api/v1/external/tasks/{task_id}/messages",
      headers={"x-network-api-key": "your-api-key"},
  )

  messages = response.json()
  for msg in messages:
      print(f"[{msg['sender']['type']}] {msg['text']}")
  ```
</CodeGroup>