Skip to main content
POST
/
v1
/
chat
/
tasks
Create Chat Task
curl --request POST \
  --url https://api.example.com/v1/chat/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": 123,
  "message": {
    "content": "<string>",
    "role": "user"
  },
  "metadata": {}
}
'
{
  "task_id": 123,
  "agent_id": 123,
  "status": "<string>",
  "created_at": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Body for POST /v1/chat/tasks.

agent_id is required and must match the agent bound to the presented API key; the server enforces body.agent_id == authed.agent.id and returns 404 agent_not_found on mismatch.

​
agent_id
integer
required

Target agent's primary key. Must match the agent the presented API key is bound to.

​
message
MessageBody · object
required

First user message of the task.

​
metadata
Metadata · object

Free-form correlation data the SDK caller can pass through (trace_id, request_id, etc). Not interpreted server-side.

Response

Successful Response

POST /v1/chat/tasks -> 202 Accepted response.

The task has been persisted, claimed as RUNNING in the same transaction, and queued for background execution; callers poll GET /v1/chat/tasks/{task_id} to observe the transition running -> completed/failed.

​
task_id
integer
required

Newly created task primary key.

​
agent_id
integer
required

Agent the task is bound to.

​
status
string
required

Initial status, 'running' in the 202 response (the atomic claim inside POST commits the status flip before the response is sent). Use GET /v1/chat/tasks/{task_id} to observe later transitions.

​
created_at
string<date-time>
required

UTC creation timestamp.