Bot settings, team rules, setup manifests and computer operations

What it does

How an administrator runs the organisation's bots from a script, each through the same engine as its screen, so a change made here is what the screen shows on its next load:

• Bot settings (Organisation → Policies, and a group's settings page): whether bots are on, what they may do, the automatic reviewer, who may use bots, and where their computers may connect.
• Team rules (Organisation → Rules): standing instructions every member's bot reads on the surfaces each rule names. A rule reaches each member's next run.
• Setup manifests (Organisation → Setup): what every member's computer runs when it starts. A change runs only once a second administrator approves it.
• Computer operations (Organisation → Computers): stop, recreate, terminate or delete many members' computers in one operation, and read its progress.

Organisation secrets have no route: they are set on the dashboard only. The same policy is also served as one resource on /api/v1/policy/bots (Bot policy, team rules and setup scripts); both are doors onto the same settings.

Authentication

A read key reads GET /api/v1/bot-settings. Every other call on this page needs an admin key from a current owner or admin; a read or write key on one of them is 401.

Request

Bot settings

• GET /api/v1/bot-settings — the whole resource:
  • enabled — off, no member starts a run; their computers, bots and history are kept, and turning bots back on finds each computer as it was.
  • capabilities — templateSharing (off, team or public), actionRecording, localExecutionCeiling (the most any member's desktop may allow: always_allow, ask_every_time or never_allow), codingAgentDelegation (whether a bot may hand coding work to a connected coding tool) and mcpServersOnComputer.
  • approvalReview — enforced (the automatic reviewer runs on every member's run, whatever the member's own Auto-review setting; a run an inbound channel message started keeps its own) and the reviewer's allow and block instructions. autoReview.enforcedForTeamBots is the same switch under its earlier name.
  • access — mode (all members, or chosen groups) and groupIds. A member outside the chosen groups is refused when a run starts.
  • network — egressMode (unset, allow_all, default_with_network_settings or network_settings_only) and allowlist, the organisation's own destinations (host or host:port). A computer applies the policy when it next starts or polls. locked is always true: members never change the network setting in this product, only an administrator does.
  • directoryGroups — the groups that mirror a directory group (Enterprise).
• PATCH /api/v1/bot-settings — any of the sections above; inside a section, any of its fields. allow and block (up to 20 each, 500 characters each), groupIds and network.allowlist (up to 500) replace the stored list. Turning actionRecording on needs actionRecordingAcknowledgement: true, the workforce notice; network.egressMode: "allow_all" needs a non-blank network.egressAcknowledgement. network.locked: true is accepted and changes nothing; network.locked: false is refused with 400 invalid_request naming network.locked, and nothing in that request is written. An unknown group refuses the whole request before anything is written. Answers the resource as GET does.

curl -sS "$BOTSEON_API_URL/api/v1/bot-settings" \
  -H "authorization: Bearer $BOTSEON_API_KEY" \
  -H "accept: application/json"

Team rules

• GET /api/v1/bot-settings/rules — limit (1–200, default 50) and cursor, newest first; nextCursor is null on the last page. Each rule: id, body, surfaces (chat, computer, routines, channels), enabled, createdAt, updatedAt.
• POST /api/v1/bot-settings/rules — body { "body": "Answer in British English.", "surfaces": ["chat"] } (1–500 characters), optionally enabled (on by default). Needs an Idempotency-Key. An organisation keeps at most 20 rules.
• PATCH /api/v1/bot-settings/rules/{id} — any of body, surfaces and enabled.
• DELETE /api/v1/bot-settings/rules/{id} — 204; the rule no longer reaches any run.

An id that is not a live rule of this organisation is 404.

Setup manifests

• GET /api/v1/bot-settings/setup-manifests — approved, the manifest every member's computer runs, and proposed, the change waiting for a second administrator (null when there is none).
• POST /api/v1/bot-settings/setup-manifests — propose a whole manifest, { "manifest": { "manifestId": "…", "entries": [ … ] } }. Needs an Idempotency-Key.
• PUT /api/v1/bot-settings/setup-manifests/{id} — create or replace one entry by its id, the script's name (lowercase letters and digits joined by hyphens, up to 64 characters); the rest of the approved manifest is kept. Body { "setup": "…", "check": "…" }: setup up to 32 KB; check, optional, up to 4 KB — when it exits 0, setup is skipped. A script that carries a secret is refused.
• DELETE /api/v1/bot-settings/setup-manifests/{id} — remove one entry by its id; an id the approved manifest does not hold is 404.
• POST /api/v1/bot-settings/setup-manifests/{id}/decision — {id} is the proposal's id; body { "decision": "approved" } or "rejected". The administrator who proposed a change may withdraw it but not approve it.

PUT and DELETE answer 202 with the proposal. Once a second administrator approves it, every member's computer runs it at its next start. One change waits at a time.

Computer operations

• POST /api/v1/organisation/computer-operations — { "action": "stop", "memberUserIds": [ … ] }; action is stop (power down, keep everything), recreate, terminate (end the machine, keep its disk) or delete. Needs an Idempotency-Key; answers 202 with the operation. One operation runs per organisation at a time. memberUserIds takes 1 to 5 000 member ids. recreate and terminate need the Enterprise plan or its trial (403 otherwise).
• GET /api/v1/organisation/computer-operations/{id} — the operation's state, its five counts and each member's result.
• GET /api/v1/organisation/computer-operations/latest — the newest operation, live or finished, the one Organisation → Computers shows when it is reopened; 404 when the organisation has never run one.

Response

GET /api/v1/bot-settings:

{
  "enabled": true,
  "capabilities": {
    "mcpServersOnComputer": false,
    "codingAgentDelegation": true,
    "templateSharing": "team",
    "actionRecording": false,
    "localExecutionCeiling": "ask_every_time"
  },
  "autoReview": { "enforcedForTeamBots": true },
  "access": { "mode": "groups", "groupIds": ["6f1e2d3c-4b5a-4968-8776-655443322110"] },
  "network": { "egressMode": "network_settings_only", "allowlist": ["registry.npmjs.org"], "locked": true },
  "directoryGroups": [],
  "approvalReview": {
    "enforced": true,
    "allow": ["Reading files in the repository"],
    "block": ["Sending email outside the company"]
  }
}

Mapping from the source product's admin API

Errors

Rate limits

The same buckets as every other route. See Envelopes, errors, idempotency and paging.