REST API

Creating a task

POST /api/tasks queues a task and returns its uuid right away. Processing happens in the background.

POST /api/tasks

Request body

Field	Type	Description
`assistant_id`	integer	Required. Assistant ID in Aist Backend — the available ones are listed by `GET /api/assistants`.
`input`	array	Required. 1+ items. See Input formats.
`turns`	array	Conversation history for context. See Multi-turn.
`llm_model_id`	integer	Explicitly selects one of the assistant's LLM model configurations.
`image_generator_id`	integer	Explicitly selects an image generator.
`callback_url`	string (url)	URL the result is delivered to via webhook. Up to 2048 characters.
`callback_secret`	string	Secret for the webhook's HMAC signature. Up to 255 characters.
`client_tools`	array	Client-side tools. See Client tools.
`max_execution_time`	integer	Maximum execution time in seconds. The clock starts when the task is created, so time spent waiting in the queue counts. Default and maximum — 86400 s; anything larger gets `422`.

POST /api/tasks — body

{
  "assistant_id": 1,
  "input": [
    { "type": "text", "text": "Analyze this document" }
  ],
  "callback_url": "https://yourapp.com/hook",   // optional
  "llm_model_id": 12                          // optional
}

Response

{ "uuid": "550e8400-…", "status": "pending", "max_execution_time": 86400 }

Keep the uuid — you use it to poll the status (Result and statuses) or to match an incoming webhook. If you lose a uuid, you can find it in the task list.

Choosing a model

llm_model_id and image_generator_id are configuration IDs on the assistant, not model name strings. If the ID isn't among the assistant's models, Aist Backend silently falls back to the default model. IDs let you pick a configuration unambiguously when the assistant has several variants of the same model (different thinking profiles or temperatures).

Maximum execution time

A task that doesn't finish within max_execution_time is cut off: its status becomes failed and error reads Task exceeded maximum execution time (Ns). At the same time the engine is asked to wind down, so no tokens are burned for nothing. Whatever the model managed to produce stays in turn — a task that was cut off may have a partial result.

Active task limit

A user can have at most 5 active tasks at a time (in the Pending / Processing / Interrupted statuses). Exceeding it returns 429. An abandoned interrupted task holds its slot until it's canceled (POST /api/tasks/{uuid}/cancel or POST /api/tasks/cancel-interrupted for all at once). The check and the insert are atomic (a per-user Redis lock). More in Errors and limits.