Skip to main content
The Toolshed REST API lets you register tool sources, manage OAuth provider connections, define access-control roles, and handle human-in-the-loop elicitation requests — all over HTTP. Every endpoint returns JSON and follows standard HTTP status-code conventions.

​
Base URL

All endpoints are relative to your Toolshed server’s base URL: 
https://your-toolshed-server.com/api
Replace your-toolshed-server.com with your actual server host. When running locally the base URL is typically http://localhost:3000/api.

​
Authentication

Most API endpoints require a bearer token. Obtain a token by running toolshed login with the Toolshed CLI, then pass it in the Authorization header on every request: 
Authorization: Bearer <your-token>
Requests that are missing or have an invalid token return 401 Unauthorized.

​
Quick example

curl https://your-toolshed-server.com/api/registry \
  --header "Authorization: Bearer <your-token>"

​
Endpoint groups

Registry

Register tool sources and discover the full catalog. Supports OpenAPI, MCP, GraphQL, and plugin sources.

Auth

Connect and manage OAuth provider integrations (GitHub, Slack, Linear, Google) on behalf of your users.

Policy

Create roles with tool-path patterns and resolve a user’s effective tool access.

Elicitation

Handle human-in-the-loop approval requests raised by tools mid-execution.

​
HTTP status codes

CodeMeaning
200Success
201Resource created
400Bad request — check the error and details fields in the response
404Resource not found
401Unauthorized — missing or invalid bearer token
502Upstream provider error

​
Error format

All error responses share a consistent shape: 
{
  "error": "Human-readable error message",
  "details": [...]
}
The details array is present on validation errors and contains Zod issue objects describing exactly which fields failed and why.