Skip to content
UltimateTeam.ai Docs

Send a message to an agent

POST
/api/v1/agents/{role}/chat

Queue a user-initiated chat message as a task for the agent.

Authorizations

Parameters

Path Parameters

role
required

The agent role to send a message to

string

The agent role to send a message to

Request Body required

Request body for POST /agents/{role}/chat.

Attributes: message: The user message to send to the agent. attachments: Optional list of file attachments (images/PDFs). thread_id: Existing conversation thread to append this turn to. persist_thread: Whether this route owns thread persistence.

object
attachments
Any of:
Array<object>
<= 5 items

A single file attachment in a chat request.

Attributes: data: Base64-encoded file content. mime_type: MIME type of the file (e.g. image/png). filename: Optional original filename for PII/security checks.

object
data
required

Base64-encoded file content

string
filename
Any of:
string
mime_type
required

MIME type such as image/png or image/jpeg

string
message
required
string
>= 1 characters <= 4096 characters
persist_thread

Set False by internal callers that already persist the turn themselves; leave True for direct UI clients.

boolean
default: true
thread_id
Any of:
string

Responses

202

Successful Response

Wrapper response for POST /agents/{role}/chat.

Attributes: data: The chat result payload.

object
data
required

Payload returned by POST /agents/{role}/chat.

Attributes: task_id: The ID of the created task. agent_role: The agent role handling the message. status: Initial task status (always "pending"). acknowledgment: Human-readable confirmation message.

object
acknowledgment
required
string
agent_role
required
string
status
required
string
task_id
required
string format: uuid

422

Validation Error

object
detail
Array<object>
object
ctx
object
input
loc
required
Array
msg
required
string
type
required
string