Skip to main content
POST
/
agents
/
tasks
/
{task_id}
/
transition
Transition Task
curl --request POST \
  --url https://api.example.com/agents/tasks/{task_id}/transition \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "backlog"
}
'
{
  "organization_id": "<string>",
  "title": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "description": "<string>",
  "status": "backlog",
  "priority": 3,
  "assigned_to_type_id": "<string>",
  "assigned_to_instance_id": "<string>",
  "assigned_to_user_id": "<string>",
  "correlation_bucket_id": "<string>",
  "created_by": "<string>",
  "source": "manual"
}

Path Parameters

​
task_id
string
required

Body

application/json

Request body for transitioning a task to a new status.

Attributes: status: Target status.

​
status
enum<string>
required

Status of an agent task on the board.

Available options:
backlog,
assigned,
running,
review,
done

Response

Successful Response

An agent task representing a unit of work.

Subtask relationships are modeled as has_subtask graph edges in SurrealDB rather than a flat parent reference. Use TaskStorageService graph traversal methods to find parents and children.

Attributes: id: SurrealDB record ID (populated by database). organization_id: Owning organization. title: Short description of the task. description: Detailed description. status: Current task status. priority: Priority level (1=urgent, 2=high, 3=normal, 4=low). assigned_to_type_id: Agent type assigned to this task. assigned_to_instance_id: Agent instance working on this task. assigned_to_user_id: User assigned to this task. correlation_bucket_id: Correlation bucket for related events. created_by: User ID of the creator. source: How this task was created.

​
organization_id
string
required
​
title
string
required
​
created_at
string<date-time>
​
updated_at
string<date-time>
​
id
string | null
​
description
string | null
​
status
enum<string>
default:backlog

Status of an agent task on the board.

Available options:
backlog,
assigned,
running,
review,
done
​
priority
integer
default:3
Required range: 1 <= x <= 4
​
assigned_to_type_id
string | null
​
assigned_to_instance_id
string | null
​
assigned_to_user_id
string | null
​
correlation_bucket_id
string | null
​
created_by
string | null
​
source
enum<string>
default:manual

Origin of an agent task.

Available options:
triage,
conversation,
manual