Skip to content
Docs

Test a connection and find its tools

POST
/api/workspaces/{ws}/connections/{id}/test

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.

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
document?string
Lengthlength <= 5000000

Response Body

{ tools, note?, connection }.

application/json
Example Request
curl -X POST 'https://app.useroster.work/api/workspaces/string/connections/string/test' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "tools": [    {      "name": "search_issues",      "description": "Search issues.",      "readOnly": true,      "inputSchema": {        "type": "object"      }    }  ],  "connection": {    "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"  }}

Connect a tool that hands over its own key POST

For catalog entries with `install` (WooCommerce): `values` holds the fields it names (the store's address). Makes the connection (`status: "pending"`) and answers the tool's own approve page. Once approved, the tool sends Roster a fresh key, which is checked and kept sealed, and people come back to `returnTo` (a path in the app) with `oauth=connected`; a denial, or a key that never arrives, removes the pending connection. With `connectionId`, reconnects that connection instead. Owners and admins only.

Choose a connection's tools PUT

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.