Tasks API

The Tasks API allows you to create and manage tasks for users.

Create Task

Creates a new task for a user.

Endpoint

POST /api/v1/external/tasks

Headers

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

Request Body

{
  "user_id": "string"
}

Field	Type	Required	Description
user_id	string	Yes	Unique identifier for the user

Response

{
  "id": "string",
  "user_id": "string", 
  "title": "string",
  "welcome_message": "string",
  "followup_suggestions": ["string"]
}

Field	Type	Description
id	string	Unique task identifier
user_id	string	User identifier
title	string	Task title
welcome_message	string	Initial welcome message
followup_suggestions	array	Suggested follow-up questions

Example Request

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": "user123"
  }'

Example Response

{
  "id": "68e78d0dc5a4b19a030d03d6",
  "user_id": "user123",
  "title": "New Task",
  "welcome_message": "Hello! How can I help you today?",
  "followup_suggestions": [
    "What products are you looking for?",
    "Do you need help with specifications?"
  ]
}

List Tasks

Retrieves a paginated list of tasks for a specific user.

Endpoint

GET /api/v1/external/tasks

Headers

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

Query Parameters

Parameter	Type	Required	Default	Description
user_id	string	Yes	-	User identifier to filter tasks
page	integer	No	1	Page number for pagination
size	integer	No	10	Number of tasks per page

Response

{
  "tasks": [
    {
      "id": "string",
      "user_id": "string",
      "title": "string", 
      "welcome_message": "string",
      "followup_suggestions": ["string"]
    }
  ],
  "total": 0,
  "page": 0,
  "size": 0
}

Field	Type	Description
tasks	array	List of task objects
total	integer	Total number of tasks
page	integer	Current page number
size	integer	Number of tasks per page

Example Request

curl -X GET "https://data-services.aui.io/api/ia-controller/api/v1/external/tasks?user_id=user123&page=1&size=10" \
  -H "x-network-api-key: your-api-key"

Example Response

{
  "tasks": [
    {
      "id": "68e78d0dc5a4b19a030d03d6",
      "user_id": "user123",
      "title": "Microwave Search",
      "welcome_message": "Hello! How can I help you today?",
      "followup_suggestions": [
        "What products are you looking for?",
        "Do you need help with specifications?"
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "size": 10
}

Get Task Messages

Retrieves all messages for a specific task.

Endpoint

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

Headers

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

Path Parameters

Parameter	Type	Required	Description
task_id	string	Yes	Task identifier (ObjectId format)

Response

Returns an array of ExternalTaskMessage objects. See Response Schemas for detailed structure.

Example Request

curl -X GET "https://data-services.aui.io/api/ia-controller/api/v1/external/tasks/68e78d0dc5a4b19a030d03d6/messages" \
  -H "x-network-api-key: your-api-key"

Example Response

[
  {
    "id": "8af51ed1-0181-4bc8-bbc9-29949b8e26da",
    "created_at": "2025-10-09 12:26:07.576000",
    "text": "I found several built-in microwaves that meet your requirements...",
    "sender": {
      "id": "intelligent-agent",
      "type": "agent",
      "email": null
    },
    "receiver": {
      "id": "user123",
      "type": "user", 
      "email": null
    },
    "options": [],
    "variants_options": [],
    "followup_suggestions": [
      "Is installation hardware included?",
      "How loud is the vent fan?",
      "Any models with convection cooking?"
    ]
  }
]

Error Responses

401 Unauthorized

{
  "status_code": 401,
  "errors": [
    "Unauthorized"
  ]
}

403 Forbidden

{
  "status_code": 403,
  "errors": [
    "Forbidden"
  ]
}

422 Validation Error

{
  "status_code": 422,
  "errors": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Application Errors (4xx/5xx)

For any application-level errors (non-validation, non-auth):

{
  "status_code": 422,
  "description": "Unprocessable Entity",
  "message": "Task termination failed due to workflow constraints, please check extra_data for more context",
  "extra_data": {
    "method": "POST",
    "path": "/api/v1/external/message",
    "query": "",
    "task_id": "68e78d0dc5a4b19a030d03d6",
    "workflow_step": "generation"
  }
}

Dynamic Extra Data

The extra_data field is dynamic and its content will differ based on the specific error type and context. Always check this field for additional error details relevant to your specific situation.