Skip to content
Docs

Give a hire a tool

PUT
/api/workspaces/{ws}/hires/{id}/tools/{connection}

values are the connection type's hireFields, e.g. GitHub { "repos": ["acme/web"] } or Linear { "teams": ["ENG"] }: an allowlist checked on every tool call (empty: whatever the connection's credential reaches). access is "read" (only tools that change nothing) or "write" (all; the default). approvals is optional, as for the change below.

Authorization

session
cookiebetter-auth.session_token<token>

Set by POST /api/auth/sign-in/email.

Path Parameters

ws*string

The workspace id (from GET /api/me).

id*string

The id of what the path names: a hire, a connection, a skill, a shared file, a department, a position, a goal or an approval.

connection*string

The connection's id (from GET /api/workspaces/:ws/connections).

Request Body

application/json
  1. body
values?
Default{}
access?string
Value in"read""write"
approvals?

Response Body

The hire, with the tool added.

application/json
Example Request
curl -X PUT 'https://app.useroster.work/api/workspaces/string/hires/string/tools/string' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "3f0c2a7e-6b1d-4c55-9a51-2f4d8e9b7a10",  "displayName": "Builder",  "slug": "builder",  "role": "Software engineer",  "instructions": "You own the web app's build and its CI.",  "status": "active",  "autonomy": "ask",  "timezone": "Europe/Berlin",  "workingHours": {    "days": [      1,      2,      3,      4,      5    ],    "start": "09:00",    "end": "18:00"  },  "home": null,  "voice": "",  "reactions": {    "onPickup": false,    "wakeOn": [      "❓",      "❌"    ]  },  "browser": false,  "desktop": false,  "listen": {    "mentions": true,    "threads": true,    "directMessages": true,    "channels": false,    "chattiness": "normal"  },  "allow": {    "humans": "anyone",    "agents": [],    "maxAgentTurns": 4  },  "chat": [],  "tools": [],  "onShift": false,  "onboardedAt": null,  "createdAt": "2026-11-03T09:00:00.000Z"}

Take a tool away DELETE

Previous Page

When a hire asks before using a tool GET

The tools the hire has on the connection (at its access level), each with its own rule (`default`: `"always"`, `"sometimes"` with the `rule` saying when, or `"never"`), whether asking is `locked` (money moving), and the hire's `setting` (`"ask"`, `"auto"` or null). A call that needs approval doesn't run: the approver is asked in the thread, and Roster makes exactly that call once it's approved. 404 when the hire isn't on the connection.