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

# Create Tasks

> Start conversation threads with Apollo-1 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 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.

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

<ParamField body="agent_id" type="string" required>
  The agent management ID. Apollo resolves the network and active version from this.
</ParamField>

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

<ParamField body="task_origin_type" type="string" default="web-widget">
  Origin of the conversation. Common values: `web-widget`, `api`, `third-party`.
</ParamField>

<ParamField body="version_id" type="string">
  Pin the thread to a specific draft version. If omitted, uses the agent's active version.
</ParamField>

<ParamField body="version_tag" type="string">
  Pin the thread to a specific revision tag (e.g., `v8.14`).
</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 201 theme={null}
  {
    "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"
    ]
  }
  ```
</ResponseExample>

***

## Code Examples

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

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

  response = requests.post(
      "https://api.aui.io/v1/messaging/tasks",
      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"
      },
      json={
          "agent_id": "agent_abc123",
          "user_id": "user_xyz789",
          "task_origin_type": "api"
      },
  )

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

***

## Get Task Trace

Retrieve the complete reasoning trace for all interactions in a task.

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

<ParamField path="task_id" type="string" required>
  The task identifier.
</ParamField>

#### Query Parameters

<ParamField query="interaction_id" type="string">
  Optional. Fetch a single interaction's trace instead of all traces.
</ParamField>

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

***

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

```json 401 theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

```json 422 theme={null}
{
  "error": "Validation Error",
  "details": [
    {
      "field": "agent_id",
      "message": "agent_id is required"
    }
  ]
}
```