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 model key,
ANTHROPIC_API_KEY or FACTORY_API_KEY, or a workspace that already holds 499 finished tasks), the
task is returned as failed with an error in plain words. A Droid task started while a new
computer is still downloading Droid stays queued and starts once Droid is there. While the agents
are paused, every new task stays queued.
Defaults: workspace is home, worker is droid, tools are empty and source is api. A task
that names no budgetCents gets Settings defaultBudgetCents (100 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.
The title is at most 200 characters, the prompt at most 100,000, budgetCents a whole number from 0
to 100000 ($1,000), and hosts at most 50 names. A host is a name like example.com,
*.example.com or example.com:8080; it is never localhost, a loopback or link-local address, or a
whole top-level domain. From a paired device, source is always phone:<the device's name>,
whatever the body says.
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). Never localhost, a loopback or link-local address, or a whole top-level domain.
Droid worker: the Claude model. haiku (cheap checks), sonnet (most work, the default), opus (hard tasks), or a full model id that starts with claude-. The task records the id it ran on.
Spending above this, in US cents, pauses the task for an OK. Default Settings defaultBudgetCents, 100 unless changed.
Who started it, for the log and the portal: api, schedule, asi1, jira:BOX-12. From a paired device it is always phone:<device name>.
The agent seat doing the work, such as Credit analyst. Shown in the audit.
How Droid works on it. Ignored by the fake worker.
object
Droid writes a plan first
low gets no network beyond the model and asks before any spending. medium keeps its hosts and a budget of at most $1. high keeps what the task asked for. The box enforces this too.
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.
Files shared to a new task, 1 to 8, 5 MB in all. They go to a new workspace of their own, so the task cannot also name a workspace, folder or folders. The log keeps names and sizes, never contents.
object
A plain file name
The file’s contents as base64.
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). Never localhost, a loopback or link-local address, or a whole top-level domain.
Droid worker: the Claude model. haiku (cheap checks), sonnet (most work, the default), opus (hard tasks), or a full model id that starts with claude-. The task records the id it ran on.
Spending above this, in US cents, pauses the task for an OK. Default Settings defaultBudgetCents, 100 unless changed.
Who started it, for the log and the portal: api, schedule, asi1, jira:BOX-12. From a paired device it is always phone:<device name>.
The agent seat doing the work, such as Credit analyst. Shown in the audit.
How Droid works on it. Ignored by the fake worker.
object
Droid writes a plan first
low gets no network beyond the model and asks before any spending. medium keeps its hosts and a budget of at most $1. high keeps what the task asked for. The box enforces this too.
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, as a sentence a person can read, such as Your Anthropic key was not accepted. Change it in Settings, Accounts & Keys.
Business: the id of the person who asked for the task. Set by the box, never by the caller.
The app whose box started the task, whatever source it gave. Set by the box, never by the caller.
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", "droid": { "autonomy": "low" }, "id": "t3k9x2a1b2", "state": "queued", "user": "box-t3k9x2a1b2", "review": "pending"}A missing title or prompt, a value over its limit, an unknown field, workspace, worker, model or tool, a host that is not a host name, 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 this computer's own screen or the owner's paired device can do this"}The body is over 10 MB.
object
What went wrong
Example generated
{ "error": "example"}