API Overview

Two ways to reach Shanone programmatically

Most agent integrations should use the MCP server — it’s what Cursor, Claude Code, and other MCP clients speak natively. The REST API documented here is the same underlying functionality, useful when you want to call Shanone directly from a script, backend service, or CI job without an MCP client in the loop. In fact, Shanone’s own local stdio MCP proxies (@duzzle/shanone-mcp and the Python equivalent) are implemented as thin wrappers over this exact REST API.

Base URL

https://app.shanone.ai/api

Authentication

External API requests (as opposed to the web dashboard’s session-based JWT auth) use a Shanone API key:

curl "https://app.shanone.ai/api/v1/tools/search?query=post+slack+message" \
  -H "Authorization: Bearer sh_xxxxxxxxxxxxxxxx"

See Authentication for key management, scoping, and rate limits.

Endpoint groups

Tool Vendor

GET /v1/tools/search, GET /v1/tools/list, GET /v1/tools/{tool_name}/schema, POST /v1/tools/{tool_name}/execute

Skill Vendor

GET /v1/skills, GET /v1/skills/{skill_id}, POST /v1/skills, PUT /v1/skills/{skill_id}, DELETE /v1/skills/{skill_id}

Permission Vendor

GET /v1/permissions/services, GET /v1/permissions/users/{user_id}, PATCH /v1/permissions/users/{user_id}/tools/{tool_name}, PATCH /v1/permissions/users/{user_id}/services/{service_name}, GET /v1/permissions/users/{user_id}/summary, PATCH /v1/permissions/users/{user_id}/batch

Health

GET /v1/health — the same check backing shanone_health_check

These map directly to the MCP meta-tools of the same shape — GET /v1/tools/search is what shanone_search_tools calls under the hood, POST /v1/tools/{tool_name}/execute is shanone_execute_tool, and so on. If you already know the MCP tool you want, the REST endpoint is almost always the same verb aimed at a slightly different URL shape.

Shanone’s dashboard (Settings, API Keys, Webhooks, Integrations, etc.) is backed by a much larger set of JWT-authenticated internal routes — those aren’t part of the external API and aren’t meant to be called directly with an API key.

Example: search, then execute

cURL
Python

# 1. Search
curl "https://app.shanone.ai/api/v1/tools/search?query=post+slack+message&limit=5" \
  -H "Authorization: Bearer sh_xxxxxxxxxxxxxxxx"

# 2. Execute
curl -X POST "https://app.shanone.ai/api/v1/tools/slack_post_message/execute" \
  -H "Authorization: Bearer sh_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"channel": "#general", "text": "Hello from the API!"}}'

import requests

headers = {"Authorization": "Bearer sh_xxxxxxxxxxxxxxxx"}
base = "https://app.shanone.ai/api"

search = requests.get(f"{base}/v1/tools/search",
                      params={"query": "post slack message", "limit": 5},
                      headers=headers).json()

result = requests.post(f"{base}/v1/tools/slack_post_message/execute",
                        json={"arguments": {"channel": "#general", "text": "Hello from the API!"}},
                        headers=headers).json()

Response shape

Tool Vendor and Skill Vendor REST endpoints return JSON objects. Updated MCP search also returns JSON text. Example search response structure (values and schema simplified for illustration):

{
  "tools": [
    {
      "name": "linear_list_teams",
      "service": "linear",
      "description": "List all teams in the Linear workspace.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "required": []
      }
    }
  ],
  "total": 1,
  "query": "list teams",
  "service": "linear",
  "offset": 0,
  "limit": 5,
  "has_more": false,
  "next_step": "Use shanone_execute_tool with an arguments object when inputSchema is present; otherwise fetch the schema."
}

GET /v1/tools/search includes schemas for top candidates using schema_limit (default 3, range 0–5). Schemas exceeding the combined 24,000 UTF-8 byte budget, among other fallback cases, use schemaRef instead of inputSchema. See the MCP search reference. Execution envelopes differ between REST and MCP implementations. Inspect the outer status, success, or reason fields as applicable, as well as the provider result.

Rate limits

Setting	Default
Requests per minute	60
Requests per day	10,000

Both are configurable per API key (up to 1,000/min and 1,000,000/day) from Settings → API Keys. Exceeding either returns 429 with a Retry-After header.

API

Two ways to reach Shanone programmatically

Base URL

Authentication

Endpoint groups

Tool Vendor

Skill Vendor

Permission Vendor

Health

Example: search, then execute

Response shape

Rate limits

Next steps

Authentication

MCP Tools Reference

​Two ways to reach Shanone programmatically

​Base URL

​Authentication

​Endpoint groups

Tool Vendor

Skill Vendor

Permission Vendor

Health

​Example: search, then execute

​Response shape

​Rate limits

​Next steps

Authentication

MCP Tools Reference

Two ways to reach Shanone programmatically

Base URL

Authentication

Endpoint groups

Example: search, then execute

Response shape

Rate limits

Next steps