Tasks over the API
Create a task from code, change it without overwriting anyone else's change, start it with input, and read how the run went.
What a task is, and what each part of it does, is on Tasks. This page is the same task as JSON.
Creating or changing a task needs tasks:write. Starting through POST /v1/runs needs runs:write;
the original task-specific start route needs tasks:write. Reading runs needs runs:read. See
Authentication.
A task as JSON
{
"name": "Triage new issues",
"assigneeRole": "support-engineer",
"goal": "Every new issue is labelled and answered within a day.",
"metric": { "text": "Share of new issues labelled within 24 hours" },
"guardrails": ["Never close an issue.", "Never promise a release date."],
"skillMd": "# Triage an issue\n\n1. Read the issue.\n2. Label it bug, feature or question.\n3. Reply once: thank the author and say what happens next.\n",
"tools": ["github.issue_read", "github.issue_write", "github.add_issue_comment"],
"gates": [{ "tool": "github.add_issue_comment", "owner": "ceo", "approval": "specific" }],
"inputs": [
{ "key": "repo", "label": "Repository", "type": "string", "required": true },
{ "key": "issue", "label": "Issue number", "type": "number", "required": true }
],
"spend": { "moneyUsdPerRun": 0.5, "maxModelTier": "mid" }
}
Only name is required. Everything else has a default, but a task with no assigneeRole has nobody to run it, and
cannot start a run.
| Field | What it is |
|---|---|
name |
Required. 1 to 200 characters. |
slug |
Unique in your enterprise; webhooks and other tasks' successors find the task by it. Made from name when you leave it out. Either way it is cleaned: lower case, accents dropped, and every run of characters other than letters and digits turned into one -. At most 80 characters. |
assigneeRole |
The slug of a role: each run goes to a member who holds that role and is free, on any team or on no team, the one who has waited longest first. A holder whose teams are all switched off is skipped. A task cannot be given to one member, nor to a team: a task belongs to a role, and a team has the tasks of the roles its members hold. A non-null teamId is refused with task_team_removed. See Roles. |
kind |
llm, the default, runs a model. deterministic runs none, and so may list no tools. |
status |
active, the default, or deprecated. A deprecated task starts no new runs, from the API, its webhook, a schedule or the portal, and answers task_not_runnable. Runs already under way finish. |
overlapPolicy |
skip, the default: a run waits while its member is busy with another. os: runs beside the member's other work, for a short check on a schedule that should never queue. |
serializeOn |
The input keys that split the task's work into lanes, such as ["repo", "issue"]. Runs in different lanes run at once; two runs in the same lane never do. Left out or null, the task has one lane: one run at a time. At most 8 keys of letters, digits, _, . and -. See Runs at once. |
goal |
One sentence: what the task is for. |
metric |
{ "text": "…" }: how you would know it works. |
guardrails |
Rules the model must not break, one string each. |
skillMd |
The skill, in Markdown: how to do the job. A heading with the slug until you write one. |
tools |
Every tool a run may call: a tool name, or an object { "name": "sentry", "optional": true }. A run goes ahead without an optional tool no connection serves, and uses it when one does (Optional tools); optional that is not true or false is refused as tool_entry_optional_invalid. See Gates and tool scopes, and Built-in tools for the OS's own. |
gates |
The calls that wait for you: tool, owner and approval. Leave it out and the task gets a CEO gate on every tool it holds that reaches outside the enterprise: see A task created without gates. Send gates: [] to create it with no gates, or a list, which is saved exactly as given. See Gates and tool scopes. |
inputs |
The fields a run starts with: key, label, type (string or number), and optionally required, default and placeholder. The portal's Start a run form is built from them. |
spend |
moneyUsdPerRun in US dollars, and which model runs it. Leave model out, or send "auto", and a model is chosen for each run, no higher than maxModelTier (economical, mid or frontier) when you set one. Send an exact model to use it for every run. spend.maxSteps is how many steps each run of the version gets, a whole number from 1 to 400. Leave it out for the default for the task's tools. A run's own input maxSteps and the operator's LLM_MAX_STEPS still win over it. See Spend and models. See Steps. |
workspace |
For a task that works in a repository: its branch, and which files it may write. See Workspaces. |
successors |
What runs after it: each a slug, with optionally on, when, delayMinutes, maxRunsPerIssue and resumeConversation. See Handoffs. |
toolSlots |
Slots the task's tools may be named by instead of one vendor's tool type: [{ "key": "codehost", "label": "Code host", "description": "…" }], at most 16. Each company fills a slot with one of its connections, and a run calls that connection's tools by its own tool type. Keys read like a tool type; os, workspace, memory and web are refused (tool_slot_key_reserved:<key>). A slot may declare actions ([{ "name": "pr.merge", "description": "…" }], at most 32, names of lowercase words joined by dots), which the task names under the key (codehost.pr.merge) and the filling connection maps to its own tools; refused as tool_slot_action_invalid:<key>.<name>, tool_slot_action_duplicate:<key>.<name> or tool_slot_actions_invalid:<key>. See Tool slots. |
callLimits |
How often one run may make a call: [{ "tool": "gitea.issue_write", "match": { "method": "create" }, "perRun": 2 }], at most 16. tool is one tool the task's tools reach, by its exact name; match names fields the call must carry to count, as a gate's does; perRun is a whole number of at least 1. A call past the limit is not sent, and the run reads call_limit_reached. Refused as call_limit_tool_invalid, call_limit_match_invalid:<tool>, call_limit_per_run_invalid:<tool> or call_limits_invalid. See Call limits. |
finishesOn |
The outcomes a run ends on that finish the work, as a list of outcome words: ["succeeded"] for a plain success. A run that ends on one, with nothing following it, is recorded as finished, so the work is not listed on Waiting. At most 16 words; failed and terminal are refused (finishes_on_invalid). Left out, nothing finishes the work but a person. See Finished work. |
maxRunsPerExecution |
The most times this task may run in one execution before its next start is logged or stopped for you, as a whole number of at least 1 (execution_cap_invalid otherwise, the same check as a successor's maxRunsPerIssue). Counted per task across the whole execution, whichever handoff started each run and whether or not it names an issue or pull request. Left out or null, the deployment's EXECUTION_MAX_TASK_RUNS applies (10 unless it says otherwise). It is never applied below the highest maxRunsPerIssue on a handoff into the task. A CEO decision, or your Retry, starts the count again. |
mailboxAction |
Where a mailbox offers the task as a one-click button, as { "on": "mailbox" | "mail", "label": "Clean inbox" }. mailbox is a button above the mailbox's list; mail is a button on one open message, which starts the run with that message's id as its emailId input, so the version has to declare an input with that key (mailbox_action_needs_email_input). The label is the button's words, at most 40 characters (mailbox_action_label_invalid); an unknown on is mailbox_action_invalid. A person's inbox offers every task of the enterprise that declares one, and every public template that does and nobody cloned; a member's page offers those that run as a role the member holds. Left out, the task puts no button anywhere. See A person's mailbox. |
Create a task
curl -X POST https://api.zerohuman.com/v1/tasks \
-H "Authorization: Bearer zhos_…" \
-H "content-type: application/json" \
-d @triage-new-issues.json
It answers 201 with the task, as GET /v1/tasks/{id} reads it:
| Field | What it is |
|---|---|
id |
The task's id. Every other call names the task by it. |
slug |
The slug it was given: triage-new-issues here. |
currentVersionId |
Its current version's id. Send it as baseVersionId when you change the task. |
currentVersion |
The current version's definition. |
skillMd |
The current skill. |
versions |
Every version, newest first, with how many runs used each. |
definitionIssues |
What the checks found that did not stop it saving. |
teams |
The teams that have the task, each { "id", "slug", "name" }: every team a member who holds its role sits on or leads. Read-only, and empty while nobody on a team holds the role. |
webhook |
The URL that starts it from another system, and the header your webhook secret goes in. See Webhooks. |
canEditDefinition |
false for a clone, whose definition belongs to the original's owner, and for the OS's own tasks, which are the same in every enterprise and change only with a release of the OS. |
| Status | Code | Why |
|---|---|---|
400 |
invalid_name |
name is empty, or longer than 200 characters. |
400 |
invalid_slug |
The slug is empty once cleaned, or longer than 80 characters. |
400 |
invalid_task_definition |
The definition fails one of the checks. |
400 |
llm_model_not_in_catalogue |
spend.model is not a model your connected provider offers. GET /v1/llm/models lists them. |
400 |
spend_max_steps_invalid |
spend.maxSteps is not a whole number from 1 to 400. |
400 |
assignee_member_removed |
The body names a member in assigneeMemberId. A task is given to a role: send assigneeRole. |
400 |
serialize_on_invalid |
serializeOn is not null or a list of up to 8 input keys. |
400 |
task_team_removed |
The body names a teamId. A task belongs to a role, not a team: seat a holder of its role on the team instead. |
409 |
task_slug_taken |
Your enterprise already has a task with that slug. |
A task that merges
A task that can merge a pull request must declare a gate on the merge. Mark the gate requiresSummary and hold
os.set_gate_summary so its run has to tell you what you are approving. Send all three in the same call:
{
"name": "Merge approved pull requests",
"assigneeRole": "release-engineer",
"tools": ["github.pull_request_read", "github.merge_pull_request", "os.set_gate_summary"],
"gates": [{ "tool": "github.merge_pull_request", "owner": "ceo", "approval": "specific", "requiresSummary": true }]
}
If you leave gates out, the task is given that gate along with its other defaults, so this refusal does not apply.
If you send gates without a gate on the merge, gates: [] included, the call is refused with
gate_required_for_tool.
That holds however tools reaches the merge:
by its name, or through github or github.*, which hold every GitHub tool. The gate must name
github.merge_pull_request itself: a gate on github or github.* does not count. If a task without that gate
reaches a run anyway, the run ends at the merge call with gate_required_for_tool, and nothing is merged.
The merge is on this rule because your GitHub connection marks it must-gate. Every connection carries such a list
(mustGate on GET /v1/tools/bindings), a GitHub connection starts with the merge on it, and only the CEO can change
it. Create, save and a new version are all checked against the lists of every connection your enterprise has. See
Gates.
The checks
Creating a task and saving a version both check the definition against your enterprise's other tasks. An error
refuses the call with a 400:
{
"error": "invalid_task_definition",
"message": "A deterministic task has no model to call its tools, so every run fails. Use kind \"llm\".",
"issues": [
{
"severity": "error",
"code": "deterministic_with_tools",
"message": "A deterministic task has no model to call its tools, so every run fails. Use kind \"llm\"."
}
]
}
message joins every error's sentence, and issues lists them one by one. A warning does not refuse the call: it
is listed in the task's definitionIssues (read the task after a save to see them) and, for an active task, on
GET /v1/blockers under taskProblems, until you fix it. A warning about a task your enterprise does not have
also carries missingTask, that task's slug, so you can look for it in the catalog (GET /v1/catalog/tasks?search=).
| Code | Severity | When |
|---|---|---|
gate_required_for_tool |
error | tools can reach a tool one of the enterprise's bindings marks must-gate (GitHub's github.merge_pull_request, when its binding carries the GitHub tool's defaults), by its name or through github or github.*, and gates declares no gate naming it; or tools lists os.mail_send and gates declares no gate on it; or tools lists os.write_plan and gates declares no gate on os.ask_ceo. Left out, gates gets each of these, so only a list you send can be refused. |
gate_summary_tool_required |
error | A gate is marked requiresSummary, or tools lists os.mail_reply, but tools does not list os.set_gate_summary. |
deterministic_with_tools |
error | kind is deterministic and tools is not empty. |
successor_when_unknown |
error | A successor's when is not has_issue, has_pr, no_pr, has_work_item or no_work_item. |
successor_cap_invalid |
error | A successor's maxRunsPerIssue is not a whole number of at least 1. |
execution_cap_invalid |
error | maxRunsPerExecution is set and is not a whole number of at least 1. |
successor_delay_invalid |
error | A successor's delayMinutes is not more than 0 and at most 1440. |
unconditional_loop |
error | Successors on terminal lead back to this task, so it would restart for ever. |
call_limit_tool_not_declared |
error | A call limit names a tool the task's tools do not reach, so it would limit nothing. |
successor_unknown_slug |
warning | A successor names a task your enterprise does not have, so the work stops there. |
tool_slot_unused |
warning | A slot is declared in toolSlots, but no tool or gate is named by it, so filling it changes nothing. |
tool_slot_action_undeclared |
warning | A tool or gate is named under a slot that declares actions, but it is not one of them, so it is one server's own tool name and the task runs only where that server fills the slot. |
outcome_not_routed:<word> |
warning | skillMd tells a run to end on {"outcome":"<word>"}, and no successor routes that word, finishesOn does not list it, and it is not succeeded or ok, so a run that ends on it stops as a dead end. One per word. An outcome finishesOn lists always finishes the work, so it is never one. |
self_loop_unconditional |
warning | A successor names the task's own slug on succeeded (or with no on) or on a named outcome, with no delayMinutes, so every run that ends that way starts another. ceo_approved, ceo_changes_requested and a delayed successor are not. |
asks_ceo_without_resume |
warning | tools reach os.ask_ceo, skillMd names another of the task's tools after it, and no successor on ceo_approved names the task's own slug, so nothing resumes the work once the CEO answers. |
These three are warnings on POST /v1/tasks and POST /v1/tasks/{id}/versions: the task or version is saved and
definitionIssues lists them. A create made through the OS's own MCP server (os.create_task) is refused with 400
and error: "definition_issues", listing each in issues, and nothing is saved.
Change a task
POST /v1/tasks/{id}/versions publishes the task's next version. Send only what changes: every field you leave
out keeps its value from the current version, skillMd included. To clear inputs, workspace, successors,
finishesOn, toolSlots, callLimits, mailboxAction or maxRunsPerExecution, send null.
Send baseVersionId too: the currentVersionId you read before you made your change. It is required: a save
without one is refused, and the task is left as it was:
{
"error": "base_version_required",
"message": "base_version_required: name the version this change was made from (baseVersionId). Read the task and send its currentVersionId.",
"statusCode": 400
}
curl -X POST https://api.zerohuman.com/v1/tasks/$TASK_ID/versions \
-H "Authorization: Bearer zhos_…" \
-H "content-type: application/json" \
-d '{
"baseVersionId": "0b7c4a52-3d1e-4f6a-8c2b-9e5d7a1f3c60",
"guardrails": ["Never close an issue.", "Never promise a release date.", "Reply in English."]
}'
It answers 201 with the new version: its id, its version number, its definition and "unchanged": false.
That id is your next baseVersionId.
A save whose definition and skill are the same as the current version's publishes nothing. It answers 201 with
the current version and "unchanged": true: the version history records decisions, and that save decided nothing.
If someone published a version after the one you read (a person, a script, a plan, or a self-improvement change you approved), your save is refused, so it cannot put the older definition back over theirs. The refusal names the version that is current now:
{
"message": "task_version_conflict",
"error": "Conflict",
"statusCode": 409,
"currentVersionId": "5d1f0c3e-7a2b-4e8d-9c6f-1b3a5e7d9f20",
"currentVersion": 4
}
Read that version, make your change to what is there now, and save against its id. Two saves made from the same read at the same moment give one new version and one refusal.
The same call takes the task's own fields: name, slug, assigneeRole, serializeOn, status and kind. These are
not part of a version. They change the task at once, and the version history does not record them; a save that
changes only these publishes no version. A new slug changes the task's webhook URL, and successors that name the
old slug no longer find it. It is cleaned as it is when you create a task: lower case, accents dropped, every run of
characters other than letters and digits turned into one -, at most 80 characters. A slug another task of your
enterprise has is refused, and the task is left as it was: no new version, and no other field of the save applied.
Sending the slug the task already has, exactly as you read it, is no rename: it is neither cleaned nor checked.
| Status | Code | Why |
|---|---|---|
400 |
base_version_required |
The body names no baseVersionId. |
400 |
invalid_slug |
The new slug is empty once cleaned, or longer than 80 characters. |
400 |
invalid_task_definition |
The new version fails one of the checks. |
400 |
assignee_member_removed |
The body names a member in assigneeMemberId. A task is given to a role: send assigneeRole. |
400 |
task_team_removed |
The body names a teamId. A task belongs to a role, not a team. |
400 |
serialize_on_invalid |
serializeOn is not null or a list of up to 8 input keys. |
400 |
skillMd_required |
The skill would be empty. |
400 |
llm_model_not_in_catalogue |
spend.model is not a model your connected provider offers. |
400 |
spend_max_steps_invalid |
spend.maxSteps is not a whole number from 1 to 400. |
403 |
task_definition_read_only |
The task is a clone: its definition belongs to the original's owner. Copy it to make your own. |
404 |
task_not_found |
No task with that id in your enterprise. |
409 |
task_version_conflict |
Someone published a newer version than your baseVersionId. The body names it: currentVersionId, currentVersion. |
409 |
task_slug_taken |
Another task in your enterprise already has the new slug, once cleaned. |
409 |
os_task_immutable |
It is one of the OS's own tasks: the same in every enterprise, changed only with a release of the OS, never through the API. |
Saving a version declines any self-improvement recommendation still waiting on the task, since it was written against the version before. See Self-improvement.
Publishing to the catalogue
Add "visibility": "public" to a save to put the task in the catalogue, where other companies can clone it. It also
needs catalog:write, and a plan that includes catalog publishing. "visibility": "private" takes it out again;
companies that already cloned it keep what they have.
You publish once. From then on, every version you save, with no visibility, goes to the catalogue too, and companies
that cloned the task are offered it as an update. A quiet one, which changes no tool, gate, input or workspace, reaches
their clones automatically where they keep auto-update on (see Clone and copy).
A save that changes nothing sends nothing.
A version the catalogue turns down never stops your own save. The version is saved, the catalogue keeps the version
it had, and the answer's catalogPublication says why:
{
"id": "…",
"version": 8,
"unchanged": false,
"catalogPublication": {
"id": "…",
"visibility": "public",
"version": 3,
"sourceVersion": 7,
"updated": false,
"refusal": {
"error": "catalog_tenant_content",
"message": "Remove tenant-specific passages before publishing to the catalog: skillMd: …",
"passages": [{ "field": "skillMd", "identifier": "…", "passage": "…" }]
}
}
}
version is the catalogue's own version number and sourceVersion the version of yours it holds. updated is
true when this save reached the catalogue. When it is false, refusal says why, or is null when the save made
no new version. Fix what it names and save again, or send "visibility": "public", and the catalogue catches up.
| Code | Why the catalogue kept its version |
|---|---|
catalog_tenant_content |
The version names your company, a member, one of your domains or something a connection is bound to. passages lists each one. |
template_tools_missing |
The version names no tool. A clone needs to know what to connect. |
catalog_publish_not_in_plan |
Your plan no longer includes catalog publishing. upgradePath says where to change it. |
catalog_entry_deprecated |
You deprecated the catalogue entry. It stays as it is until you publish with "visibility": "public" again. |
A save that carries "visibility": "public" is refused outright for the same reasons, and then nothing is saved.
Versions
GET /v1/tasks/{id}/versions lists every version, newest first. GET /v1/tasks/{id}/versions/{versionId} reads
one as it was, with its skillMd, how many runs used it, and whether it is current. A version never changes
once saved. To go back to an earlier one, read it and publish its fields as a new version.
Start a run
POST /v1/tasks/{id}/runs starts a run on the task's current version. The body is the run's input, a JSON object:
curl -X POST https://api.zerohuman.com/v1/tasks/$TASK_ID/runs \
-H "Authorization: Bearer zhos_…" \
-H "content-type: application/json" \
-d '{"repo": "acme/web", "issue": 128}'
It answers 201 with the new run and its id. The run is queued, or pending when the task already has a run
under way or every member holding its role is busy: a pending run starts when the task and a holder of its role are
free. A run waiting at a gate does not make either busy.
The body becomes the run's input as sent. It is not checked against the task's inputs, and their defaults are
not filled in, so send every value the run needs.
{id} is the task's id. To find it from the slug, GET /v1/tasks?slug=triage-new-issues lists the tasks whose
slug contains it. A webhook starts a task by its slug instead, with your webhook secret
rather than a token.
| Status | Code | Why |
|---|---|---|
404 |
task_not_found |
No task with that id in your enterprise. |
404 |
task_not_runnable |
It cannot take new work: it is deprecated, or nobody can run it (it has no assigneeRole, or nobody holds that role). A deprecated task answers this even while a run of it is under way. |
404 |
task_disabled |
It is switched off: its run status is disabled. Nothing starts it, from the API, its webhook, a schedule, another task's handoff, a retry or the portal, until it is set back to active. A run made before it was switched off still goes ahead: one under way finishes, and one waiting for the task to be free or delayed until later still starts when its turn comes. A task that is also deprecated answers task_not_runnable instead. |
The same input sent again while its run is still pending answers with that run, not a second one. Once the run
has started, the same input starts another, so starting a run is not safe to repeat blindly: see
Safe retries.
Activation through MCP
External agents can use these MCP tools after publishing a task:
| Tool | Required scope | Effect |
|---|---|---|
os.set_task_run_status |
tasks:write |
Set runStatus to active or disabled. |
os.set_task_schedule |
tasks:write |
Replace a schedule with id, cron, and optional timezone, enabled, and input. |
os.remove_task_schedule |
tasks:write |
Remove a schedule without cancelling existing runs. |
os.set_task_input_values |
tasks:write |
Replace your enterprise's own input values with id and values, keyed by input key; {} clears them. Works on a linked clone. |
os.start_task |
runs:write |
Start by taskId or slug, with optional input and a required idempotencyKey. |
os.read_context |
enterprise:read |
Read one workflow bookkeeping key. |
os.write_context |
enterprise:write |
Replace that key's value with a JSON object of at most 16 KB. |
memory.ask |
memory:read |
Recall knowledge for a purpose, with optional teamId, projectId, and limit. |
The start tool calls POST /v1/runs with a structured envelope:
{
"slug": "triage-new-issues",
"input": { "repo": "acme/web", "issue": 128 },
"idempotencyKey": "triage-128-first-start"
}
Pass exactly one of taskId and slug. The key must be nonempty and at most 200 characters. Reusing it for the
same authenticated caller and task returns the original run even if the input differs; new work needs a new key.
The response is {runId, status, taskId, slug, origin}. Your enterprise's own input values, task input defaults,
planning, disabled-task checks, assignment and spend controls apply as they do to a requested start in the portal.
Enabling a task permits starts but does not start it. Setting a schedule on a disabled task leaves it unable to
run. A schedule fires only when the deployment's scheduler is running. Read it back with os.read_task_definition.
Context tools use GET and PUT /v1/enterprise/context/{key}. Writes replace the entire object and record the
authenticated caller, so read before changing selected fields. Context holds workflow state; knowledge belongs
in memory. memory.ask calls GET /v1/memory/ask and returns the existing answer, evidence and availability
envelope scoped to the caller's enterprise, without needing a task or run.
Read the run
GET /v1/runs/{id}, with runs:read, reads the run with its events and gates:
{
"run": {
"id": "5c0e9f7a-1b2d-4e3f-a4b5-c6d7e8f90a1b",
"status": "succeeded",
"input": { "repo": "acme/web", "issue": 128 },
"costUsdCents": 4,
"startedAt": "2026-09-28T09:00:03.000Z",
"finishedAt": "2026-09-28T09:01:41.000Z"
},
"events": [
{ "id": "…", "type": "run.succeeded", "payload": { "result": "…" }, "createdAt": "2026-09-28T09:01:41.000Z" }
],
"gates": []
}
The answer also carries the task and version it ran, what came before it and what it handed to, its execution, and its cost.
The API does not call you when a run ends, so read it until it has:
succeeded,failedorcancelled: it has ended. Arun.succeededevent carries itsresult, and arun.failedevent itsreason.waiting_on_gate: it waits for your decision, andgatesholds what it waits on. Decide it on Gates, or withPOST /v1/gates/{id}/decisionand a token scopedgates:write.blocked: it is held for a reason outside the task, such as a refused credential or a provider outage, andblockedReasonsays which. Most blocked runs resume by themselves. One held by an outage or a timeout is tried again five times, over about two hours, and then waits on Blockers for you to retry or cancel it.paused_spend: a spend cap was reached. It is queued again when the cap is raised or spend limits are turned off. See Spend and models.
Every status is on Runs. On later reads, send afterEventId with the id of the newest event you
hold, and only the events recorded since come back. A few from the same second may come again: skip the ids you
already have.
GET /v1/runs/{id}/log answers with the run's full log in body once it is stored, and 404 (log_not_found)
until then. GET /v1/runs?taskId=… lists a task's runs, newest first.