Bot policy, team rules and setup scripts

What it does

How an administrator runs the team's bots, each through the same engine as its screen:

• The bot policy (Organisation → Policies): whether bots are on for the team, what they may do, how the automatic reviewer works, who may use them and where their computers may connect.
• Team rules (Organisation → Rules): standing instructions every member's bot reads on the surfaces each rule names.
• Setup scripts (Organisation → Setup): what every member's computer runs when it starts. A change runs only once a second administrator approves it.

Organisation secrets have no route: they are set on the dashboard only.

Authentication

A read key reads GET /policy/bots, GET /rules and GET /setup-scripts. Every other call needs an admin key from a current owner or admin; a read or write key on one of them is 401.

Request

Bot policy

• GET /api/v1/policy/bots — the whole policy:
  • enabled — off, no member starts a run; their computers, bots and history are kept.
  • capabilities — templateSharing (off, team or public), actionRecording, localExecutionCeiling (the most any member's desktop may allow: always_allow, ask_every_time or never_allow; a member's own choice is kept and applies again when the limit is lifted) and delegation (whether a bot may hand coding work to a connected coding tool).
  • approvalReview — enforced (the automatic reviewer runs for Team Bots wherever they run) and the reviewer's allow and block instructions.
  • access — mode (all members, or chosen groups) and groupIds. A member outside the chosen groups is refused when a run starts.
  • network — mode (unset, allow_all, default_with_network_settings or network_settings_only) and allowlist, the organisation's own destinations. Change the allowlist through /organisation/egress-entries. network.locked is always true: members never change the network setting in this product, only an administrator does.
• PATCH /api/v1/policy/bots — any of the fields above; inside an object, any of its fields. allow and block (up to 20 each, 500 characters each) and groupIds replace the stored list. Turning actionRecording on needs actionRecordingAcknowledgement: true, the workforce notice; network.mode: "allow_all" needs a non-blank network.acknowledgement. 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 policy as GET does.

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

Team rules

• GET /api/v1/rules — limit (1–200, default 50) and cursor, newest first. Each rule: id, content, surfaces (chat, computer, routines, channels), enabled, createdAt, updatedAt.
• POST /api/v1/rules — body { "content": "Answer in British English." } (1–500 characters), optionally surfaces (every surface by default) and enabled (on by default). Needs an Idempotency-Key. An organisation keeps at most 20 rules.
• PATCH /api/v1/rules/{id} — any of content, surfaces and enabled.
• DELETE /api/v1/rules/{id} — answers the rule it removed.

An id that is not a live rule of this organisation is 404. A rule reaches each member's next run.

Setup scripts

• GET /api/v1/setup-scripts — data, the approved scripts (name, setup, check), the approved version, and pending, the change waiting for a second administrator (null when there is none).
• PUT /api/v1/setup-scripts/{name} — create or replace one script. {name} is lowercase letters and digits joined by hyphens, up to 64 characters. 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/setup-scripts/{name} — remove one script; a name the approved scripts do not hold is 404.
• POST /api/v1/setup-script-proposals/{id}/decision — body { "decision": "approved" } or "rejected". The administrator who proposed a change may withdraw it but not approve it. Answers the scripts as GET does.

PUT and DELETE answer 202 with the proposal (id, version, proposedBy, proposedAt, scripts as they would be). Once approved, every member's computer runs the scripts at its next start. One change waits at a time.

Response

GET /api/v1/policy/bots:

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

Mapping from the source product's admin API

Errors

Rate limits

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