Tasks & Job System

Tasks are durable work records that agents, administrators, and external integrations can create and update. Use them when work must remain visible beyond one chat turn, needs approval before it starts, or depends on other work.

Tasks track work; they do not schedule or execute it by themselves. Agents use the built-in manage_tasks tool and administrators use Admin. SyntheticBrew does not currently provide cron or webhook scheduling endpoints.

Before you start

Assign the built-in manage_tasks tool to an agent if it should create or update tasks itself.
Use an API key with the tasks scope for programmatic task management.
Use UUID task IDs returned by the API. Do not add a textual prefix to them.
Set require_approval when an administrator must approve work before it becomes runnable.

Task lifecycle

require_approval=true:
  draft -> approved -> in_progress -> completed

require_approval=false:
  pending -> in_progress -> completed

While active:
  in_progress -> needs_input
  in_progress -> failed
  needs_input -> in_progress
  needs_input -> failed
  draft | approved | pending | in_progress | needs_input -> cancelled

Status	Meaning
`draft`	Waiting for approval. Created when `require_approval` is true.
`approved`	Approval was recorded; the task can be started.
`pending`	Ready to be picked up.
`in_progress`	Work has started.
`needs_input`	Work is paused until more information is available.
`completed`	Work finished successfully. Terminal state.
`failed`	Work stopped with an error. Terminal state.
`cancelled`	Work was cancelled. Terminal state.

The dedicated REST transition endpoints enforce lifecycle rules. Use them instead of trying to write arbitrary status values.

Describe and organize work

A task can include:

interactive or background mode;
priority 0 (normal), 1 (high), or 2 (critical);
acceptance criteria;
blockers in blocked_by;
a parent_task_id for subtasks;
an approval gate through require_approval.

The REST create request also requires agent_name, but tasks do not currently retain it as an assignment; see the limitation below.

Blockers and subtasks make a larger objective visible as a dependency graph. A ready-work query in the manage_tasks tool can then identify tasks whose blockers have cleared.

Let an agent manage tasks

Select the built-in manage_tasks tool for the agent in Admin, or include it in configuration:

agents:
  project-manager:
    model: primary-model
    tools:
      - manage_tasks
    system: |
      Track durable work as tasks. Keep status, priority, dependencies,
      and completion results current.

The tool supports creating tasks and subtasks, reading and listing work, finding ready work, updating task details, and completing, failing, or cancelling work. Its current assign action starts a pending or approved task but does not persist the supplied agent ID. The agent chooses an action based on its instructions and the current conversation.

Expected result: tasks created by the agent appear in Admin -> Tasks and can also be queried through GET /api/v1/tasks.

Assignment and source limitation

POST /api/v1/tasks currently requires a non-empty agent_name, and list requests accept agent_name and source query parameters. Tasks do not currently retain assignment or source, so:

list/detail responses return empty agent_name and source fields;
agent_name and source do not currently narrow list results;
the source and agent filters shown in Admin do not currently narrow the list;
an external scheduler may create a task, but it cannot persist cron or webhook provenance through the current public request body.

Use session events and Tool Call Log for current execution attribution. Task source and agent-assignment values are not retained at present, so do not use them for customer-facing logic.

Operational cautions

Task titles are limited to 256 characters and descriptions to 8,192 characters.
A task accepts at most 64 acceptance criteria and 32 blockers; each acceptance criterion is limited to 512 characters.
Task request bodies are limited to 64 KB.
Cancelling a task uses DELETE /api/v1/tasks/{id}; deletion means lifecycle cancellation, not silent erasure of its history.
agent_name is required on REST create, but the task does not retain that assignment.