Start a task
const url = 'http://127.0.0.1:7700/api/tasks';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"title":"Summarise the meeting notes","prompt":"Read notes.md and write a five-line summary to summary.md.","workspace":"home","budgetCents":50}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://127.0.0.1:7700/api/tasks \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "title": "Summarise the meeting notes", "prompt": "Read notes.md and write a five-line summary to summary.md.", "workspace": "home", "budgetCents": 50 }'Creates a task and starts it straight away. The response is the task after it started, usually
running. If the task cannot start (for example, a Droid task when the vault has no
FACTORY_API_KEY), the task is returned as failed with an error.
Defaults: workspace is home, worker is droid, tools are empty and source is api. A task
that names no budgetCents gets Settings defaultBudgetCents (0 unless changed). A task that names
no hosts gets none, or Settings defaultHosts when networkDefault is allowlist. The workspace
must exist and every tool must be installed. A field the box does not know is a 400 that names it.
Host names are not checked here; the proxy checks them on every connection.
Personal (preview), owner only. Send folder, an absolute path to one of the owner’s folders, or
folders, a list of up to 10, instead of workspace. A folder must be in the owner’s home or in
Settings agentFolders, must not belong to root, and can never be the system or the box’s own state.
Links are followed to where they really go. One folder becomes a workspace named
owner-<folder name>-<hash>, where the hash comes from the full path. Several folders share one
workspace and show up side by side, each named after its real folder. The task works on a copy; the
real folders are not touched until the owner keeps the task.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
A short name for people.
What the worker should do. For the fake worker, one command per line.
A folder in BOX_HOME/workspaces. The task works on its own copy of it.
droid is Droid with Claude. fake runs scripted steps with no model, for tests.
Tool names the task may call through its broker, such as wallet.pay.
Hosts the task’s network may reach: example.com (any port), example.com:8080 (one port) or *.example.com (subdomains).
Spending above this, in US cents, pauses the task for an OK. Default Settings defaultBudgetCents, 0 unless changed.
Who started it, for the log and the portal: api, schedule, asi1, jira:BOX-12.
Personal: the first real folder the task works on a copy of.
Personal: every real folder the task works on.
Personal (preview), owner only: an absolute path to a real folder. Replaces workspace.
Personal (preview), owner only: several real folders in one task. Send folder or folders, not both.
Example
{ "title": "Summarise the meeting notes", "prompt": "Read notes.md and write a five-line summary to summary.md.", "workspace": "home", "budgetCents": 50}Responses
Section titled “Responses”The new task.
object
A short name for people.
What the worker should do. For the fake worker, one command per line.
A folder in BOX_HOME/workspaces. The task works on its own copy of it.
droid is Droid with Claude. fake runs scripted steps with no model, for tests.
Tool names the task may call through its broker, such as wallet.pay.
Hosts the task’s network may reach: example.com (any port), example.com:8080 (one port) or *.example.com (subdomains).
Spending above this, in US cents, pauses the task for an OK. Default Settings defaultBudgetCents, 0 unless changed.
Who started it, for the log and the portal: api, schedule, asi1, jira:BOX-12.
Personal: the first real folder the task works on a copy of.
Personal: every real folder the task works on.
queued created, not started. running the worker is working. waiting paused until an
approval is answered. done finished; its changes are part of the workspace. failed stopped with
an error; its changes are not applied. undone removed; its changes are gone and other tasks keep
theirs.
The Linux user the task runs as, box-<id>.
Finished tasks whose changes this task saw when it started, newest first.
Tool spending plus model cost, in US cents. Not rounded.
The latest step
Why it failed. A worker that exited with an error ends with its own last error line: worker exited with 1: Error: ....
Personal, for a task on real folders: done and waiting for the owner, kept, stopped by a conflict, or undone.
Example
{ "workspace": "home", "worker": "droid", "tools": [], "hosts": [], "source": "api", "id": "t3k9x2a1b2", "state": "queued", "user": "box-t3k9x2a1b2", "review": "pending"}A missing title or prompt, an unknown field, workspace, worker or tool, or a folder agents may not use.
object
What went wrong
Example
{ "error": "no workspace notes"}The owner’s route, called by someone who is not the box’s own screen or a device paired as the owner.
object
What went wrong
Example
{ "error": "only the box's own screen or the owner's paired device can do this"}GurtOS is open source under the Apache License 2.0.Source code on GitHub.