Tools API
Discover and execute organization tools from one unified registry.
Every organization tool is declared once in convex/tools/definitions/ and exposed through three surfaces: this REST API, the MCP server, and the pnpm tools CLI. Adding a tool to the registry publishes it everywhere at once.
Endpoints
GET /v1/tools
GET /v1/tools/:name
POST /v1/tools/:name| Endpoint | Description |
|---|---|
GET /v1/tools | List every tool with its JSON Schema |
GET /v1/tools/:name | JSON Schema of a single tool |
POST /v1/tools/:name | Execute a tool with a JSON body as its input |
Authentication
Create an organization API key from the organization settings page:
/orgs/{orgSlug}/settings/api-keysSend it with x-api-key or as a bearer token:
Authorization: Bearer pk_live_YOUR_KEY
Authorization: Bearer YOUR_API_KEYThe key resolves the organization, so no organization id is ever passed in a tool input.
An OAuth access token issued to an MCP client is sent the same way, as a bearer
token. API keys are recognized by their pk_live_ prefix, everything else is
verified as an OAuth token, so both credentials reach the same handlers.
Available tools
| Tool | Category | Access | Input | Returns |
|---|---|---|---|---|
create_pin | pins | write | { account_id, board_id, image_url, ... } | The pin, queued or scheduled |
list_pins | pins | read | { status?, cursor?, limit? } | Pins, newest first |
get_pin | pins | read | { pin_id } | One pin |
cancel_pin | pins | write | { pin_id } | The cancelled pin |
generate_video | pins | write | { image_url, prompt, duration?, model? } | { run_id, request_id, status } |
list_video_runs | pins | read | { product_sku? } | Runs with their state and file URL |
create_video_pin | pins | write | { video_url, cover_image_url, ... } | The video pin, queued or scheduled |
attach_video_to_pin | pins | write | { pinterest_pin_id, video_url } | The file's address on the shop's server |
list_accounts | accounts | read | none | Connected Pinterest accounts |
list_boards | accounts | read | { account_id } | The account's boards |
get_analytics | analytics | read | { startDate, endDate } | Impressions, saves and outbound clicks |
get_organization | organization | read | none | Organization id, name, slug |
list_members | members | read | { cursor?, limit? } | { members, count, nextCursor, hasMore } |
get_member | members | read | { memberId } | One member |
get_subscription | billing | read | none | Plan, status, seats and plan limits |
Videos have their own page: Videos API. To reach these tools from Claude Code or another MCP client, see Connect an MCP client.
Discovery response
GET /v1/tools returns a JSON Schema per tool, ready to feed an LLM or a client generator:
{
"total": 15,
"tools": [
{
"name": "get_member",
"description": "Get a single member of the organization by member id.",
"category": "members",
"access": "read",
"inputSchema": {
"type": "object",
"properties": {
"memberId": { "type": "string", "minLength": 1 }
},
"required": ["memberId"]
},
"endpoint": "/v1/tools/get_member",
"method": "POST",
"route": { "method": "GET", "path": "/v1/members/:memberId" }
}
]
}route is the tool's REST alias, or null when it only answers on /v1/tools/<name>. Both paths run the same tool; the alias returns the payload without the data envelope. See Unified Tools for how to declare one.
Execution response
Successful executions return the tool payload under data:
{
"data": {
"members": [{ "id": "mem_123", "role": "owner" }],
"count": 1,
"nextCursor": null,
"hasMore": false
}
}CLI
export PINCAST_API_KEY="YOUR_API_KEY"pnpm tools list