Developer docs SDK
Tasks API
Create, await, and orchestrate project tasks, and answer approval gates — the orchestration primitives available from any script.
Python
create_task(identifier, ...) spawns a task instance; the remaining methods observe and orchestrate:
| Method | Description |
|---|---|
| create(identifier, options) | Spawn a task; with wait=true it blocks until settled |
| wait(task_id, timeout=300, poll_interval=2, on_feedback) | Blocks until settled and returns the task dict with "result" |
| feedback(task_id, message) | Answer a sub-task waiting in pending_approval |
| flush(timeout=300) | Join background on_complete threads before exit |
| list(status?, limit=50, offset=0) | List tasks — filter by status: pending / running / success / failed / pending_approval / rejected; limit up to 200 |
| get(task_id) | Snapshot of one task, with its result when finished |
from workflow import create_task, wait_task, feedback, flush_tasks
tid = create_task(
"summariser",
params={"url": "https://example.com"},
on_feedback=lambda task: feedback(task["id"], "deploy to staging"),
)
result = wait_task(tid, timeout=600)
flush_tasks()| Option | Default | Description |
|---|---|---|
| identifier | required | Meta-task identifier; must belong to the same project |
| name | {identifier}-{timestamp} | Kanban display name |
| params | {} | Values matching the meta-task param schema |
| wait | False | Block until the task settles and return its result |
| timeout | 300 | Max seconds for wait / callbacks |
| poll_interval | 2 | Status poll interval (seconds) |
| on_complete / on_error | None | Settle / failure callbacks (background threads); errors are silently ignored without a callback |
| on_feedback | None | Called each time the task enters pending_approval; task["current_phase"] carries the question or approval context |
| show_in_kanban | False in services | Whether the task appears on the kanban |
| workspace_slug | None | Run in a specific workspace |
TypeScript
createTask(identifier, options) mirrors the contract:
const tid = await createTask("summariser", {
params: { url: "https://example.com" },
onFeedback: (task) => feedback(task.id, "deploy to staging"),
});
const result = await waitTask(tid, { timeoutMs: 600_000 });
await flushTasks();| Option | Default | Description |
|---|---|---|
| name | {identifier}-{timestamp} | Kanban display name |
| params | {} | Values matching the meta-task param schema |
| wait | false | Block until the task settles and return its result |
| timeoutMs | 300000 | Max milliseconds for wait / callbacks |
| pollIntervalMs | 2000 | Status poll interval (milliseconds) |
| onComplete / onError | — | Settle / failure callbacks; errors are silently ignored without a callback |
| onFeedback | — | Called each time the task enters pending_approval; task.current_phase carries the question or approval context |
| showInKanban | false in services | Whether the task appears on the kanban |
| workspaceSlug | meta-task default | Run in a specific workspace |