Skip to content
Docs

Choose a connection's tools

PUT
/api/workspaces/{ws}/connections/{id}/tools

Which found tools hires can use at all (enabled; empty for all of them), and which ones people say change nothing (readOnly), so read-only hires get them. Each hire can be narrowed further on its Tools tab.

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.

Request Body

application/json
  1. body
enabled?array<>
Itemsitems <= 500
readOnly?array<>
Itemsitems <= 500

Response Body

The connection.

application/json
Example Request
curl -X PUT 'https://app.useroster.work/api/workspaces/string/connections/string/tools' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "8d1e5b2c-0f3a-4e7b-9c6d-1a2b3c4d5e6f",  "kind": "tool",  "type": "github",  "name": "GitHub",  "settings": {},  "secretsSet": [    "token"  ],  "status": "connected",  "statusDetail": null,  "account": "acme-studio",  "checkedAt": "2026-11-03T09:00:00.000Z",  "createdAt": "2026-11-03T09:00:00.000Z"}

Test a connection and find its tools POST

For MCP servers and custom APIs (catalog entries with `discovers: true`): asks the MCP server for its tools, or reads the API's OpenAPI document (its `openapiUrl`, or the text given as `document`). What's found is kept on the connection as `settings.discovered`, each tool with `readOnly` (from the server's `readOnlyHint`, or GET); tools the server doesn't mark count as changing things. A custom API with no document is checked with one GET of its base address.

Connect a tool with OAuth GET

For a connection with an OAuth app's client ID and secret (Linear): redirects the person to the tool to authorise Roster, then back to Integrations → Tools.