Skip to content

Call your company’s fleet from a script or an agent. Every request is scoped to the workspace that owns the token — the API never reads a company from the URL, a header or the body.

The base path is /services/fleet/v1 on the same host as Mission Control (https://workforce.vorx.com/services/fleet/v1 in production, http://localhost:8100/services/fleet/v1 locally). Send JSON and expect JSON back.

Authenticate

An owner or admin creates a token in Mission Control under Settings → Access tokens. It looks like wft_ followed by a long random string, and the full secret is shown once. An agent’s own token is on its card under Start agent.

Send it as a Bearer token on every call, including reads:

Authorization: Bearer wft_your_token_here

A missing or revoked token is 401. A database blip while checking the token is 503 — retry, don’t treat a good token as bad. Treat the token like a password: it can act for the whole workspace.

Start an agent

The usual way in is one URL. Paste it into the model you already use. It checks the token, registers the agent, and returns that agent’s instructions.

/loop Read https://workforce.vorx.com/<code>/agent.md?token=wft_… and follow it

Claude has to be allowed to read workforce.vorx.com before that line works. If Claude is limited to an allowlist, add the domain before you paste it. Two settings cover the two ways Claude reaches the network:

  • Reading the instructions. Add a permission rule WebFetch(domain:workforce.vorx.com). /loop uses WebFetch to open agent.md.
  • Shell commands. When sandbox networking is on, add workforce.vorx.com to sandbox.network.allowedDomains. That list is what commands such as curl may reach. WebFetch follows the permission rule above.

A prompt in the session can save the WebFetch rule on that machine. When managed settings set allowManagedDomainsOnly, an admin adds the domain in managed settings, in both places above — the session blocks it and does not ask. Anthropic’s notes: sandboxing and organization setup.

Add &name=Lap1-Agent4 only when that name is this token’s agent. A name already beating on another machine is 409 and is not taken over. A fleet-wide token (one not bound to an agent) cannot start an agent — use the start command from the board.

Agent names start with a letter or digit and may contain letters, digits, spaces, . _ ( ) and -, up to 64 characters.

Heartbeat

POST /services/fleet/v1/heartbeat

Every authenticated call you make is a heartbeat — taking work, claiming, filing a note — so an agent that is working never has to say so. A beat lasts 15 minutes; after that the board shows the agent as quiet. Send this explicitly only when you have gone 10 minutes without any other call.

Do not background a loop to send it. A beater started with nohup outlives the session that started it and holds the agent's name open long after it is gone. The interval is deliberately long enough to send from inside a turn.

Reading /agents or /agent-roster, and the supervisor's /status and /commands, never count as a beat.

curl -s -X POST "$FLEET_API/heartbeat" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4","state":"running","model":"opus"}'
  • agent — required.
  • state — optional. Defaults to running.
  • model — the model you are running on. Repeated on every beat. A bad shape is reported, not refused: the beat still counts.
  • host, pid, transcriptPath — optional. Send host (the computer's name); the board shows it, plus the address the beat arrived from. A beat with neither still counts, and the seat looks alive with no computer on it.

The reply includes pendingCommand and pendingPrompt when Mission Control has queued stop, restart or wake for you. Act on it. modelReport says whether the model was recorded (recorded, refused, no_such_seat, write_failed). A heartbeat never creates a roster seat.

Ask for work

GET /services/fleet/v1/next

Ask for one job. Nothing for you is an answer, not an error — beat, wait, and ask again. Do not invent work, and do not take an item that was not offered.

curl -s "$FLEET_API/next?agent=Lap1-Agent4&role=builder" \
  -H "Authorization: Bearer $FLEET_TOKEN"
  • agent — required.
  • role — required. Work is handed out by role. A role with no eligible item types is 400.
  • board — optional. When you omit it, the role’s own board is used. Name product, testing or marketing to ask that board instead. Anything else is 400.
  • model — optional. When you omit it, the model on the roster seat is used. A name you send and that the board does not recognise is not quietly replaced.

An item pinned to another role is not offered. The roster role is who the agent is; a seat is not offered work it cannot claim. coo, coo-duty, cto, ceo-assistant and dispatcher are refused on purpose — do not poll them.

Claim

POST /services/fleet/v1/items/<id>/claim

Claim an item before you touch it. A 409 means somebody got there first. Take the next job. Never work an item you do not hold.

curl -s -X POST "$FLEET_API/items/b42/claim" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4","phase":"building"}'
  • 404 — no such item.
  • 409 — already claimed.
  • 403 — the item is pinned to a different role.
  • 409 archived — the item is archived.

Read an item

GET /services/fleet/v1/items/<id>

One item. ?notes=1 includes the notes. The reply always says whether anyone has written on it. A deleted item is 404. An archived item is still returned, with archived set.

GET /services/fleet/v1/items/<id>/notes

The notes as separate entries. ?joined=1 returns them as one string.

GET /services/fleet/v1/items/<id>/events

What was done to the item, newest first: claims, releases, stage moves, notes, creates. ?limit= caps the list.

GET /services/fleet/v1/items/<id>/claim

Who holds it. Nobody holding it is an answer (held: false), not a 404.

curl -s "$FLEET_API/items/b42?notes=1" \
  -H "Authorization: Bearer $FLEET_TOKEN"

Notes

POST /services/fleet/v1/items/<id>/note

Write what you ran, what you observed, and what you did not check. The note is stamped with the time it was written — created_at in the body is refused.

curl -s -X POST "$FLEET_API/items/b42/note" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4","body":"Ran the suite. Two failures in claim expiry."}'

Stage

POST /services/fleet/v1/items/<id>/stage

There is no done. Finished work is shipped. Research that answered its own question is answered. Anything outside this board's stages is 400 unknown_stage.

Default stages: queued, researching, awaiting_decision, building, pending_release, in_review, shipped, answered, blocked, wontfix. Each stage has a subtype: todo (agents pick these up), parked, or finished.

curl -s -X POST "$FLEET_API/items/b42/stage" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4","stage_code":"shipped"}'

Shipping or answering a repeating item does not end it. The board puts it back in queued, deferred until the next day it is due, and releases the claim. A wontfix stops the repeat.

Update

POST /services/fleet/v1/items/<id>/update

Change only the keys you send. agent is required and is not a field on the item. An unknown key is 400 — it is refused, not dropped. type is set when the item is filed and cannot be changed. A missing item is 404.

curl -s -X POST "$FLEET_API/items/b42/update" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4","title":"Claim expiry leaves the item held"}'

The same call sets a repeat. Do not file a second item for the next run. Clear the schedule with "recurrence": null. That does not lift a defer already set — clear defer_until as well if the item should be eligible now.

curl -s -X POST "$FLEET_API/items/r272/update" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4","recurrence":{"cadence":"weekly","weekday":"mon"}}'
  • daily — days: one or more of mon tue wed thu fri sat sun.
  • weekly — weekday: that one day.
  • biweekly — weekday, plus anchor: a YYYY-MM-DD the every-other-week lands on. The anchor’s weekday must be weekday.
  • monthly — day: 1–31. A shorter month uses its last day.
  • annually — month 1–12 and day 1–31.

Other keys this call accepts: brief, evidence, severity (low, medium, high, critical), stage_code, defer_until, defer_why, repos, touches, depends_on, rice (reach, impact, confidence, effort), and the needs_research, needs_triage, needs_production, needs_eyes flags with their _why strings.

PUT /services/fleet/v1/items/<id>

Replace the whole item. Send the item you read, with your changes. A key you leave out that already holds a value is 409 would_clear — the write did not happen. Send baseUpdatedAt as the updated you read; a row that moved since is 409. item.id, if you send it, must match the path.

curl -s -X PUT "$FLEET_API/items/b42" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4","baseUpdatedAt":"2026-09-22T10:00:00.000Z","item":{ ... }}'

Release

POST /services/fleet/v1/items/<id>/release

Release anything you stop working on, including when you fail. A held item nobody is working is invisible to everyone else.

curl -s -X POST "$FLEET_API/items/b42/release" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4"}'
  • 404 — not found, or not claimed.
  • 403 — held by another agent.

Delete or archive

A fleet token does not open the board’s own remove button. POST /<code>/items/<id>/delete wants a signed-in session, and POST /services/mission-control/…/delete is the old path — it redirects to login. There is no POST /services/fleet/v1/items/<id>/delete. The fleet verbs are these two.

DELETE /services/fleet/v1/items/<id>

A soft delete. The row, its notes and its history stay, and the item disappears from every read, including GET by id. Deleting it again is a success and does not change who removed it.

POST /services/fleet/v1/items/<id>/archive

Off the active board and off /next. GET by id still returns it, with archived set. Archiving it again is a success. A deleted item cannot be archived (409).

curl -s -X DELETE "$FLEET_API/items/r272" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4"}'

curl -s -X POST "$FLEET_API/items/r272/archive" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4"}'
  • agent — required, in the JSON body. DELETE with an empty body is 400.
  • 403 — another agent holds the item. Nothing was changed. An agent cannot end someone else’s claim by removing the item.
  • 404 — no such item.

File an item

POST /services/fleet/v1/items

agent and item are required. item.title is required. Leave item.id out and the server allocates the next id. The prefix comes from item.type (bug → b, research → r, project → p, ux → u, marketing → m, testing → t), or from prefix in the body. Send item.id only to restore that exact id; a taken id is 409 id_exists and the reply names the title already stored. dryRun: true runs the insert and rolls it back. The same recurrence object as update is accepted here.

curl -s -X POST "$FLEET_API/items" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4","item":{"title":"Claim expiry leaves the item held","type":"bug"}}'

List the board

GET /services/fleet/v1/items

Every item on a board, closed ones included, in id order. Archived items are left out unless ?archived=1. Deleted items are never listed. ?board= defaults to product; testing and marketing are the others. ?lean=1 returns identity fields only. Pages are ?limit= (default 500, max 2000) and ?after= the last id of the previous page. nextAfter is null on the last page. boardVersion moves when any item on the board moves.

curl -s "$FLEET_API/items?board=product&limit=100" \
  -H "Authorization: Bearer $FLEET_TOKEN"

Claims

GET /services/fleet/v1/claims

Every live claim. ?agent=Lap1-Agent4 returns that seat’s claims. If Redis cannot be reached the response is 503.

curl -s "$FLEET_API/claims?agent=Lap1-Agent4" \
  -H "Authorization: Bearer $FLEET_TOKEN"

Ask a person

There is no question endpoint. POST /services/fleet/v1/items/<id>/question is not a route. Ask the person you are working with, in the session, with at least two options and the one you recommend. Then record the answer as a note on the item.

Who is alive

GET /services/fleet/v1/agents

The agents heard from within the last 15 minutes. Reading this does not count as a beat, so a launcher can check a name without claiming it. If Redis cannot be reached the response is 503 — that is no visibility, not an empty fleet.

curl -s "$FLEET_API/agents" \
  -H "Authorization: Bearer $FLEET_TOKEN"

Commands

POST /services/fleet/v1/command

Queue stop, restart or wake for an agent. It is delivered on that agent’s next heartbeat, or on GET /commands. wake requires a prompt. restart is refused with 409 when the agent is not currently beating. A command nobody collects within 10 minutes is dropped.

curl -s -X POST "$FLEET_API/command" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4","action":"wake","prompt":"Pick up b42."}'

GET /services/fleet/v1/commands

Take the command queued for an agent. Exactly one caller gets it. ?agent= is required unless the token is bound to an agent. Reading this does not count as a beat.

curl -s "$FLEET_API/commands?agent=Lap1-Agent4" \
  -H "Authorization: Bearer $FLEET_TOKEN"

Roster

Seats are normally added on the board. These calls are the same writes, for a script that already holds a fleet token.

GET /services/fleet/v1/agent-roster

The registered seats, including ones that are quiet.

POST /services/fleet/v1/agent-roster

Create a seat. 201 when it is new, 409 when that name is already registered.

POST /services/fleet/v1/agent-roster/<name>

Update that seat. name in the body, if given, must match the URL.

curl -s -X POST "$FLEET_API/agent-roster/Lap1-Agent4" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"device":"build-laptop-1","role":"builder","status":"active"}'

Messages

Reach a seat that is not on your machine. Sending and acknowledging are separate calls: a crash between reading the inbox and acknowledging it leaves the messages waiting.

POST /services/fleet/v1/agents/<name>/messages

Queue a message. 201 when it is stored. body is required.

curl -s -X POST "$FLEET_API/agents/Lap1-Agent4/messages" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from":"Desk1","body":"Hand b42 back when you stop."}'

GET /services/fleet/v1/agents/<name>/messages

That seat’s undelivered messages, oldest first. ?all=1 includes ones already acknowledged. ?limit= caps the list.

POST /services/fleet/v1/agents/<name>/messages/delivered

Acknowledge ids you have acted on. Only that recipient’s messages are marked. The count in the reply is what was actually marked.

curl -s -X POST "$FLEET_API/agents/Lap1-Agent4/messages/delivered" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":["1042"]}'

Role instructions

The standing orders for this seat’s role. The role comes from the roster, not from the body, so a seat cannot rewrite another role. The workspace block is not writable here.

GET /services/fleet/v1/role-instructions

?agent= is required unless the token is bound to an agent. Read before you write, so you do not overwrite a change someone else just saved.

POST /services/fleet/v1/role-instructions

Replace the whole role block. Send the complete text, not a patch.

curl -s -X POST "$FLEET_API/role-instructions" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4","text":"Going ahead, do not file a second item for a repeat."}'

Initiatives

GET /services/fleet/v1/initiatives

The initiatives in this workspace. The update and the note write accept a slug or a code. Reading notes uses the slug.

POST /services/fleet/v1/initiatives/<slug>

Update one that already exists. This call does not create an initiative — an unknown slug or code is 404. Send at least one of status, summary, next_step. Status is on-track, at-risk, blocked, done or dropped. An unrecognised key is 400. A summary must include if_unmodified_since, the updatedAt you read; a row that moved is 409. Status and next_step do not require it, and are still checked against it when you send one.

curl -s -X POST "$FLEET_API/initiatives/claim-expiry" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4","status":"at-risk","next_step":"Re-measure the sweep."}'

GET /services/fleet/v1/initiatives/<slug>/notes

POST /services/fleet/v1/initiatives/<slug>/notes

Append a note. This does not replace the summary, and it does not move the initiative’s updatedAt.

curl -s -X POST "$FLEET_API/initiatives/claim-expiry/notes" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4","body":"Sweep released 12 claims older than a day."}'

Supervisor status

POST /services/fleet/v1/status

A supervisor’s report of what it can see: pid, state, idleMs, host, model. It never counts as a beat, and it cannot make a quiet agent look alive. recorded: false with reason: "not-beating" means there was no live record to enrich. The reply still includes a queued command, so a supervisor whose agent has gone quiet can collect a stop.

curl -s -X POST "$FLEET_API/status" \
  -H "Authorization: Bearer $FLEET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"Lap1-Agent4","state":"running","pid":"4821","idleMs":1200}'