Tracks

Tasks and goals for active work.

Tracks represent work that is moving toward completion. Use tracks when something has status, ownership, a due date, dependencies, or progress.

Track types

Type	Use for	Status values
`task`	Concrete units of work	`backlog`, `todo`, `in_progress`, `done`
`goal`	Outcomes with progress	`not_started`, `on_track`, `at_risk`, `postponed`, `completed`

Tasks are operational. Goals are outcome-oriented. A task can link to a goal through goalId.

Task and goal dueDate values use YYYY-MM-DD. On update, passing an empty string clears optional date fields. Task status, parentId, and goalId can also be cleared with an empty string where supported.

Task fields

Tasks can include:

Field	Meaning
`status`	Current task state
`dueDate`	Date in `YYYY-MM-DD` format
`assignee`	Workspace user ID or installed agent ID
`parentId`	Parent task ID
`dependsOn`	IDs of tasks that must happen first
`goalId`	Goal this task contributes to

{
	"type": "task",
	"title": "Review API docs",
	"scope": { "type": "personal" },
	"task": {
		"status": "todo",
		"dueDate": "2026-06-05"
	}
}

Goal fields

Goals include status, dueDate, and progress. Progress is an integer from 0 to 100.

{
	"type": "goal",
	"title": "Ship docs v1",
	"scope": { "type": "projects", "ids": ["project-id"] },
	"goal": {
		"status": "on_track",
		"progress": 40
	}
}

Bulk planning

Use bulk apply when an agent or script needs to create multiple related tracks. Non-UUID draft IDs create new records and can be referenced by other drafts in the same request.

{
	"scope": { "type": "personal" },
	"updateDrafts": [
		{ "id": "t001", "title": "Task A", "task": { "status": "todo" } },
		{ "id": "t002", "title": "Task B", "task": { "status": "todo", "dependsOn": ["t001"] } }
	]
}

The server resolves t001 and t002 into real UUIDs after creation.

Type inference in bulk apply

In updateDrafts, the server infers the track type from the presence of task or goal. Include task and omit goal for a task. Include goal and omit task for a goal. Passing both in the same draft is invalid.

New drafts require title. Existing UUID drafts use PATCH semantics: omitted fields keep their current value.