API Reference

Connect this to your agent

Four ways to plug this in, in order of how little code you have to write. Client SDKs (TypeScript, Python) are in progress.

1. Zero code — import the OpenAPI spec

Point your framework's tool-calling / plugin importer at the spec below. Most modern agent frameworks (and a growing number of LLM providers' own tool-use setup flows) can ingest an OpenAPI document directly and generate a working tool with no hand-written integration code.

GET /openapi.json

2. Copy-paste a ready-made tool definition

Same source of truth as the OpenAPI spec — generated from the actual request/response schemas, not hand-maintained, so it can't drift from what the API really does.

GET /tools/openai.json      // OpenAI Chat Completions / Responses API `tools` array
GET /tools/anthropic.json   // Claude Messages API `tools` array

// Example: OpenAI
const tools = await fetch("https://agent-capability-search-api.shamarwebsterrb.workers.dev/tools/openai.json")
  .then((r) => r.json());
// pass `tools` directly as the `tools` param on your Chat Completions call

3. Connect as an MCP server

If your agent already speaks MCP, add this as a server directly — no HTTP code to write, just config. It's a thin local passthrough to the same /search and /resolve endpoints below, using your own API key, so tiering/rate limits/billing all work exactly like calling the REST API yourself. (Runs locally via npx, not a remote hosted server — see packages/mcp-server/README.md in the repo for why, if you're curious.)

{
  "mcpServers": {
    "agent-capability-search": {
      "command": "npx",
      "args": ["-y", "@acs/mcp-server"],
      "env": { "ACS_API_KEY": "<your key>" }
    }
  }
}

Exposes two tools: search_capabilities and resolve_capability.

4. Call the REST API directly

POST /search and POST /resolve, documented below — works from any language, any framework, zero dependencies.

Authentication

Pass your key as x-api-key. /search allows a small unauthenticated demo quota; /resolve always requires a key.

Tier	/search	/resolve
Free (no key)	Limited demo quota	Not allowed
Free (with key)	Allowed	20 / day
Starter+	Allowed	Higher limits, plus payment-hint detail and verified-only filtering

POST /search

Find capabilities matching a natural-language query.

Request

{
  "query": "get the current weather for a city",
  "protocol": ["mcp_tool", "rest_api"],   // optional
  "constraints": {                          // optional
    "verifiedOnly": true,
    "authType": "api_key",
    "paymentMethod": "free"
  },
  "limit": 10,                              // 1-50, default 10
  "cursor": null                            // optional pagination cursor
}

Response

{
  "results": [
    {
      "capabilityId": "b6f1a2b0-1c2d-4e3f-8a9b-000000000002",
      "name": "get_weather",
      "description": "Returns current weather for a city.",
      "protocol": "mcp_tool",
      "provider": { "id": "...", "name": "Acme Weather" },
      "score": 0.94,
      "verificationStatus": "scanned_clean",
      "paymentHintSummary": ["free"]
    }
  ],
  "nextCursor": null
}

Example

curl -X POST https://api.example.com/search \
  -H "content-type: application/json" \
  -d '{"query":"weather"}'

POST /resolve

Get everything needed to invoke a capability returned by /search.

Request

{
  "capabilityId": "b6f1a2b0-1c2d-4e3f-8a9b-000000000002",
  "intentContext": "user is asking about weather in Berlin"  // optional
}

Response

{
  "capabilityId": "b6f1a2b0-1c2d-4e3f-8a9b-000000000002",
  "protocol": "mcp_tool",
  "endpoint": { "url": "https://...", "method": "streamable-http" },
  "auth": { "type": "none" },
  "schema": { "input": { ... }, "output": { ... } },
  "payment": { "accepted": ["free"], "providerDeclared": true, "verified": false },
  "safety": { "verificationStatus": "scanned_clean", "lastScannedAt": "2026-08-01T00:00:00Z" },
  "expiresAt": "2026-08-29T00:10:00Z"
}

Example

curl -X POST https://api.example.com/resolve \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"capabilityId":"b6f1a2b0-1c2d-4e3f-8a9b-000000000002"}'

Safety

Every capability is scanned before listing. verificationStatus tells you what stage it's at — only scanned_clean and manual_reviewed capabilities are ever returned by /search or /resolve. Flagged or delisted capabilities are excluded automatically.