{"openapi":"3.1.0","info":{"title":"AgentManifest Public API","version":"2.0.0","description":"The AgentManifest API lets autonomous agents **discover, purchase, and invoke** services\nfrom the marketplace — entirely over HTTP, without any human in the loop.\n\n## Quick start for agents\n1. **Discover** — `GET /api/agent/services?q=your+query` to find what you need.\n2. **Inspect** — `GET /api/agent/services/{slug}` for pricing, parameters, and invocation details.\n3. **Purchase** — `POST /api/agent/purchase` with your `amk_...` agent key. Free services and services with preview credits activate instantly.\n4. **Invoke** — `POST /api/agent/invoke` to run the service and get the result. Credits are decremented automatically.\n\n## Authentication\nAuthenticated endpoints use **Bearer token** auth with an AgentManifest agent key (`amk_...`).\nCreate a key in the [AgentManifest dashboard](/account).\n\n## MCP\nAll marketplace tools are also available over the [Model Context Protocol](https://modelcontextprotocol.io)\nat `POST /api/mcp` (JSON-RPC 2.0). Discovery descriptor: `GET /.well-known/mcp.json`.\n\n## OpenAI / LangChain\n`GET /api/agent/tools` returns every listed service as an OpenAI function-tool schema.\nPoint your agent's `execute` endpoint at `POST /api/agent/invoke`.","contact":{"name":"AgentManifest","url":"https://agent123.xyz/docs","email":"api@agent123.xyz"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"},"x-logo":{"url":"https://agent123.xyz/favicon.ico","altText":"AgentManifest"}},"externalDocs":{"description":"Agent API guide","url":"https://agent123.xyz/docs"},"servers":[{"url":"https://agent123.xyz","description":"Production"}],"tags":[{"name":"Catalog","description":"Browse and search the marketplace. No authentication required."},{"name":"Purchase","description":"Autonomously purchase services using an agent key."},{"name":"Invoke","description":"Execute purchased services through the AgentManifest gateway."},{"name":"Entitlements","description":"Check and record usage against active entitlements."},{"name":"MCP","description":"Model Context Protocol (JSON-RPC 2.0) endpoint."},{"name":"Discovery","description":"Machine-readable discovery and spec files."}],"components":{"securitySchemes":{"AgentKey":{"type":"http","scheme":"bearer","bearerFormat":"amk_...","description":"AgentManifest agent key. Create one in the dashboard. Pass as `Authorization: Bearer amk_...` or the `X-Agent-Key` header."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."}}},"CatalogEntry":{"type":"object","description":"A compact listing of a marketplace service.","properties":{"slug":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string","nullable":true},"category":{"type":"string"},"pricing_model":{"type":"string","enum":["free","per_use","subscription","one_time"]},"price":{"type":"string","description":"Human-readable price, e.g. \"$0.02 USD / call\"."},"price_cents":{"type":"integer"},"unit":{"type":"string","nullable":true},"currency":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"rating":{"type":"number","nullable":true},"rating_count":{"type":"integer"},"purchase_count":{"type":"integer"},"call_count":{"type":"integer"},"detail_url":{"type":"string","format":"uri"},"purchase_endpoint":{"type":"string","format":"uri"}}},"ServiceManifest":{"type":"object","description":"Full manifest for a marketplace service including invocation details.","properties":{"slug":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"category":{"type":"string"},"provider":{"type":"string","nullable":true},"pricing":{"type":"object","properties":{"model":{"type":"string"},"price_cents":{"type":"integer"},"currency":{"type":"string"},"unit":{"type":"string","nullable":true},"human":{"type":"string"},"preview_credits":{"type":"integer"}}},"invocation":{"type":"object","properties":{"endpoint":{"type":"string","format":"uri","nullable":true},"method":{"type":"string"},"spec_url":{"type":"string","format":"uri","nullable":true},"parameters":{"type":"array","items":{"type":"object"}},"example":{"type":"object","nullable":true}}},"stats":{"type":"object","properties":{"purchases":{"type":"integer"},"calls":{"type":"integer"}}},"purchase":{"type":"object","description":"How to purchase this service.","properties":{"endpoint":{"type":"string","format":"uri"},"method":{"type":"string"},"auth":{"type":"string"},"body":{"type":"object"},"note":{"type":"string"}}}}},"PurchaseResult":{"type":"object","properties":{"status":{"type":"string","enum":["active","checkout_required"],"description":"\"active\" = instant access granted; \"checkout_required\" = Stripe checkout needed."},"purchase_id":{"type":"integer"},"type":{"type":"string"},"credits_remaining":{"type":"integer","nullable":true},"checkout_url":{"type":"string","format":"uri","nullable":true,"description":"Stripe Checkout URL. Present only when status = checkout_required."},"message":{"type":"string","nullable":true}}},"InvokeResult":{"type":"object","properties":{"ok":{"type":"boolean"},"slug":{"type":"string"},"result":{"type":"object","description":"Service-specific output."},"billing":{"type":"object","properties":{"plan":{"type":"string","enum":["free_credit","metered","included"]},"units":{"type":"integer"},"cost_cents":{"type":"integer"},"credits_remaining":{"type":"integer","nullable":true}}}}},"EntitlementEntry":{"type":"object","properties":{"purchase_id":{"type":"integer"},"service_slug":{"type":"string"},"service_name":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"credits_remaining":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"McpRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"method":{"type":"string","enum":["initialize","ping","tools/list","tools/call","notifications/initialized","resources/list","prompts/list"]},"params":{"type":"object","nullable":true}}},"McpResponse":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"result":{"type":"object","nullable":true},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{}}}}}}},"paths":{"/api/agent/services":{"get":{"operationId":"listServices","summary":"Search the service catalog","description":"Returns a paginated list of published marketplace services. No authentication required. Supports free-text search and filters.","tags":["Catalog"],"parameters":[{"name":"q","in":"query","description":"Free-text search across name, description, tags.","schema":{"type":"string"}},{"name":"category","in":"query","description":"Filter by category slug (e.g. `tool_api`, `data_feed`, `compute`).","schema":{"type":"string"}},{"name":"pricing","in":"query","description":"Filter by pricing model.","schema":{"type":"string","enum":["free","per_use","subscription","one_time"]}},{"name":"max_price_cents","in":"query","description":"Maximum price in cents (inclusive).","schema":{"type":"integer"}},{"name":"sort_by","in":"query","description":"Sort order: `popularity` (default), `newest`, `price_asc`, `price_desc`.","schema":{"type":"string","enum":["popularity","newest","price_asc","price_desc"]}},{"name":"has_preview","in":"query","description":"When `true`, only return services with free preview credits.","schema":{"type":"boolean"}},{"name":"limit","in":"query","description":"Max results (1–200, default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Catalog search results.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["catalog"]},"query":{"type":"string","nullable":true},"total_published":{"type":"integer"},"categories":{"type":"array","items":{"type":"string"}},"count":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/CatalogEntry"}},"docs":{"type":"string","format":"uri"}}},"example":{"object":"catalog","query":"summarize","total_published":3,"categories":["tool_api"],"count":1,"results":[{"slug":"summarize","name":"Summarize","tagline":"Condense text into bullets or a TL;DR","category":"tool_api","pricing_model":"per_use","price":"$0.02 USD / call","price_cents":2,"unit":"call","currency":"USD","tags":["nlp","summarization"],"rating":null,"rating_count":0,"purchase_count":0,"call_count":0,"detail_url":"https://agent123.xyz/s/summarize","purchase_endpoint":"https://agent123.xyz/api/agent/purchase"}],"docs":"https://agent123.xyz/docs"}}}}}}},"/api/agent/services/{slug}":{"get":{"operationId":"getService","summary":"Get a service manifest","description":"Returns the full manifest for a published service: pricing, invocation contract, parameters, and how to purchase.","tags":["Catalog"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The service slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"Service manifest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceManifest"}}}},"404":{"description":"Service not found or not published.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/tools":{"get":{"operationId":"getOpenAiTools","summary":"Get OpenAI-compatible tool schemas","description":"Returns every listed service as an [OpenAI function-tool](https://platform.openai.com/docs/guides/function-calling) definition. Drop the `tools` array directly into your `openai.chat.completions.create()` call. When the model invokes a tool, POST `{ slug, params }` to the `execute_endpoint` with your agent key.","tags":["Catalog"],"parameters":[{"name":"q","in":"query","description":"Filter tools by keyword.","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"OpenAI tool list.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["tool_list"]},"format":{"type":"string","enum":["openai-function-tools"]},"note":{"type":"string"},"execute_endpoint":{"type":"string","format":"uri"},"authentication":{"type":"string"},"count":{"type":"integer"},"tools":{"type":"array","items":{"type":"object"}}}}}}}}}},"/api/agent/purchase":{"post":{"operationId":"purchaseService","summary":"Autonomously purchase a service","description":"Purchase a service using an agent key. Free services and services with preview credits activate instantly (status = `active`). Paid services return a Stripe Checkout URL (status = `checkout_required`) that the agent's principal can complete.","tags":["Purchase"],"security":[{"AgentKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string","description":"The service slug to purchase."}}},"example":{"slug":"agent-answer"}}}},"responses":{"200":{"description":"Purchase result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResult"}}}},"401":{"description":"Missing or invalid agent key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Service not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/invoke":{"post":{"operationId":"invokeService","summary":"Execute a purchased service","description":"Run a service through the AgentManifest gateway. The gateway verifies your entitlement, bills the call (consuming a credit or metering per-use), executes the service (first-party or proxied), logs usage, and returns the result.\n\nFor first-party services the result is returned directly. For third-party services the gateway proxies the request to the provider's endpoint.","tags":["Invoke"],"security":[{"AgentKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string","description":"The service slug to invoke."},"params":{"type":"object","description":"Service-specific input parameters (see the service manifest)."},"units":{"type":"integer","description":"Units to consume (default 1). Only relevant for metered services.","default":1}}},"example":{"slug":"agent-answer","params":{"question":"What is the capital of France?","max_words":50}}}}},"responses":{"200":{"description":"Service result with billing summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvokeResult"}}}},"400":{"description":"Bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid agent key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"No active entitlement. Purchase the service first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Service not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream service failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/entitlements":{"get":{"operationId":"listEntitlements","summary":"List active entitlements","description":"Returns all active purchases (entitlements) for the authenticated agent key.","tags":["Entitlements"],"security":[{"AgentKey":[]}],"responses":{"200":{"description":"List of active entitlements.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["entitlement_list"]},"count":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/EntitlementEntry"}}}}}}},"401":{"description":"Missing or invalid agent key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/usage":{"get":{"operationId":"getUsageHistory","summary":"Usage history (paginated)","description":"Paginated audit log of all invocations made with the authenticated agent key, including service name, units consumed, cost, and timestamp.","tags":["Usage"],"security":[{"AgentKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"description":"Max records to return."},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Pagination offset."}],"responses":{"200":{"description":"Paginated usage history.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"usage_history"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"},"daily_usage":{"type":"object","properties":{"units":{"type":"integer"},"cost_cents":{"type":"integer"}}},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"service_slug":{"type":"string"},"service_name":{"type":"string"},"units":{"type":"integer"},"cost_cents":{"type":"integer"},"timestamp":{"type":"integer","description":"Unix ms timestamp"}}}}}}}}},"401":{"description":"Missing or invalid agent key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RichError"}}}}}},"post":{"operationId":"recordUsage","summary":"Record metered usage","description":"Decrement credits from an active entitlement. Use this when you want to record usage outside the invoke gateway (e.g. you called the provider directly and want to keep billing in sync).","tags":["Usage"],"security":[{"AgentKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string"},"units":{"type":"integer","default":1}}}}}},"responses":{"200":{"description":"Usage recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"credits_remaining":{"type":"integer","nullable":true}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp":{"post":{"operationId":"mcpCall","summary":"MCP over HTTP (JSON-RPC 2.0)","description":"Model Context Protocol endpoint. Send a JSON-RPC 2.0 request to call any marketplace tool.\n\n**Available methods:** `initialize`, `ping`, `tools/list`, `tools/call`, `notifications/initialized`, `resources/list`, `prompts/list`.\n\n**Available tools (via `tools/call`):** `search_services`, `get_service`, `purchase_service`, `check_entitlement`, `invoke_service`.\n\nProtocol version: `2025-06-18` (Streamable-HTTP transport).","tags":["MCP"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpRequest"},"examples":{"initialize":{"summary":"Initialize handshake","value":{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","clientInfo":{"name":"my-agent","version":"1.0"}}}},"toolsList":{"summary":"List available tools","value":{"jsonrpc":"2.0","id":2,"method":"tools/list"}},"searchServices":{"summary":"Search the catalog","value":{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_services","arguments":{"query":"summarize text","limit":5}}}},"purchaseService":{"summary":"Purchase a service","value":{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"purchase_service","arguments":{"slug":"agent-answer","agent_key":"amk_live_..."}}}},"invokeService":{"summary":"Invoke a purchased service","value":{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"invoke_service","arguments":{"slug":"agent-answer","agent_key":"amk_live_...","params":{"question":"What is 2+2?"}}}}}}}}},"responses":{"200":{"description":"JSON-RPC response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpResponse"}}}}}}},"/.well-known/mcp.json":{"get":{"operationId":"getMcpDiscovery","summary":"MCP discovery descriptor","description":"Machine-readable MCP discovery file. Agents and MCP clients can fetch this to learn the endpoint, protocol version, and available tools.","tags":["Discovery"],"responses":{"200":{"description":"MCP descriptor.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/openapi.json":{"get":{"operationId":"getOpenApiJson","summary":"OpenAPI spec (JSON)","description":"This specification document in OpenAPI 3.1 JSON format.","tags":["Discovery"],"responses":{"200":{"description":"OpenAPI 3.1 spec.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/agent/keys":{"post":{"operationId":"createAgentKey","summary":"Create an agent key (no auth required)","description":"Create a new agent key instantly with just an email address. No OAuth or account required.\nA guest user is created (or reused) and **50 welcome credits** are automatically activated\nacross all first-party services so the agent can start invoking immediately.\n\nThe key is shown **only once** — save it securely.","tags":["Agent Keys"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Your email address. Used to identify your account."},"label":{"type":"string","maxLength":120,"default":"My agent key","description":"Human-readable label for this key."}}},"example":{"email":"agent@example.com","label":"My autonomous agent"}}}},"responses":{"201":{"description":"Key created. Save the `key` field — it is shown only once.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"agent_key"},"key":{"type":"string","example":"amk_live_abc123...","description":"The full secret key. Save this — it is shown only once."},"key_prefix":{"type":"string","example":"amk_live_abc1"},"label":{"type":"string"},"welcome_credits":{"type":"integer","example":50},"activated_services":{"type":"array","items":{"type":"string"}},"note":{"type":"string"},"next_steps":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Invalid email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RichError"}}}}}}},"/api/openapi.yaml":{"get":{"operationId":"getOpenApiYaml","summary":"OpenAPI spec (YAML)","description":"This specification document in OpenAPI 3.1 YAML format.","tags":["Discovery"],"responses":{"200":{"description":"OpenAPI 3.1 spec.","content":{"text/yaml":{"schema":{"type":"string"}}}}}}}}}