{"openapi":"3.1.0","info":{"title":"SemiAnalysis Agent API","version":"0.1.0","description":"Agent-facing API for SemiAnalysis research. Free articles are public; paid articles return 402 without a key and 200 with a demo subscriber key. Mock/demo — no real payments.","contact":{"email":"licensing@semianalysis.com","url":"https://seminalysisgoesagentic.swarmlabs.eu/developers"}},"servers":[{"url":"https://seminalysisgoesagentic.swarmlabs.eu","description":"Production"},{"url":"https://seminalysisgoesagentic.swarmlabs.eu/api/sandbox/v1","description":"Sandbox — mirrors /api/v1 with X-Sandbox: true. Nothing is billed."}],"paths":{"/api/v1/articles":{"get":{"operationId":"listArticles","summary":"List articles","description":"Paginated list of all articles with id, title, tier, date, url.","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"Article list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedArticles"}}}}},"security":[{"bearerAuth":["articles:read"]},{"oauth2":["articles:read"]},{}]}},"/api/v1/articles/{slug}":{"get":{"operationId":"getArticle","summary":"Read an article","description":"Free articles return the full body. Paid articles return 402 without a key, 401 with an invalid key, and 200 with a valid demo key.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Article","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":["articles:read"]},{"oauth2":["articles:read"]},{}]}},"/api/v1/pricing":{"get":{"operationId":"getPricing","summary":"Pricing tiers","responses":{"200":{"description":"Pricing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pricing"}}}}},"security":[{}]}},"/api/v1/agent/subscribe":{"post":{"operationId":"agentSubscribe","summary":"Mock subscribe and receive a demo key","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string"}}}}}},"responses":{"200":{"description":"Demo subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeResponse"}}}}},"security":[{}]}},"/ask":{"get":{"operationId":"askGet","summary":"NLWeb search (GET)","servers":[{"url":"https://seminalysisgoesagentic.swarmlabs.eu"}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"NLWeb response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskResponse"}},"text/event-stream":{"schema":{"type":"string"}}}}},"security":[{}]},"post":{"operationId":"askPost","summary":"NLWeb search (POST)","servers":[{"url":"https://seminalysisgoesagentic.swarmlabs.eu"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"}},"required":["query"]}}}},"responses":{"200":{"description":"NLWeb response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskResponse"}}}}},"security":[{}]}},"/mcp":{"post":{"operationId":"mcpProduct","summary":"Product MCP server (JSON-RPC 2.0)","servers":[{"url":"https://seminalysisgoesagentic.swarmlabs.eu"}],"responses":{"200":{"description":"JSON-RPC response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPResponse"}}}}},"security":[{"bearerAuth":["mcp:connect"]},{"oauth2":["mcp:connect"]},{}]}},"/mcp/docs":{"post":{"operationId":"mcpDocs","summary":"Docs MCP server (JSON-RPC 2.0)","servers":[{"url":"https://seminalysisgoesagentic.swarmlabs.eu"}],"responses":{"200":{"description":"JSON-RPC response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPResponse"}}}}},"security":[{}]}},"/checkout_sessions":{"options":{"operationId":"checkoutOptions","summary":"ACP commerce signal (CORS preflight)","servers":[{"url":"https://seminalysisgoesagentic.swarmlabs.eu"}],"responses":{"204":{"description":"Allowed"}}},"post":{"operationId":"checkoutCreate","summary":"Create a checkout session (demo)","servers":[{"url":"https://seminalysisgoesagentic.swarmlabs.eu"}],"responses":{"200":{"description":"Demo session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}}},"security":[{}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"sa_demo","description":"Demo subscriber key: sa_demo_<hex>. Obtain via POST /api/v1/agent/subscribe."},"oauth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://seminalysisgoesagentic.swarmlabs.eu/agent/auth/token","scopes":{"articles:read":"Read paid article bodies","mcp:connect":"Connect the MCP server and call tools"}}},"x-authorization-server":"https://seminalysisgoesagentic.swarmlabs.eu/.well-known/oauth-authorization-server"}},"schemas":{"Article":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"tier":{"type":"string","enum":["free","paid"]},"date":{"type":"string"},"url":{"type":"string","format":"uri"},"markdown":{"type":"string"},"access_level":{"type":"string"}},"required":["id","slug","title","tier","url"]},"ArticleSummary":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"tier":{"type":"string"},"date":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["id","slug","title","tier","url"]},"PaginatedArticles":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ArticleSummary"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"next":{"type":"string","nullable":true},"prev":{"type":"string","nullable":true}}}},"required":["data","pagination"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"docs_url":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"PaymentError":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Error/properties/error"},"payment":{"type":"object","properties":{"required":{"type":"boolean"},"price":{"type":"number"},"currency":{"type":"string"},"pay_endpoint":{"type":"string"},"pricing":{"type":"string"}}}}},"Pricing":{"type":"object","properties":{"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string"},"includes":{"type":"array","items":{"type":"string"}}}}}}},"SubscribeResponse":{"type":"object","properties":{"status":{"type":"string"},"api_key":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"mcp_endpoint":{"type":"string"},"docs":{"type":"string"},"message":{"type":"string"},"idempotency_key":{"type":"string"}},"required":["status","api_key","scopes","mcp_endpoint"]},"AskResponse":{"type":"object","properties":{"query_id":{"type":"string"},"query":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"name":{"type":"string"},"site":{"type":"string"},"score":{"type":"number"},"schema_object":{"type":"object"}}}}},"required":["query_id","query","results"]},"MCPResponse":{"type":"object","description":"JSON-RPC 2.0 response envelope","properties":{"jsonrpc":{"type":"string"},"id":{},"result":{"type":"object"},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}},"CheckoutSession":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}}}}},"x-payment-info":{"protocol":"x402","resource":"https://seminalysisgoesagentic.swarmlabs.eu/api/v1","paid_endpoints":["/api/v1/articles/{slug} (paid tier)"],"subscribe":"https://seminalysisgoesagentic.swarmlabs.eu/api/v1/agent/subscribe","pricing":"https://seminalysisgoesagentic.swarmlabs.eu/pricing","docs":"https://seminalysisgoesagentic.swarmlabs.eu/why"},"x-sandbox":{"url":"https://seminalysisgoesagentic.swarmlabs.eu/api/sandbox/v1","header":"X-Sandbox: true","note":"Full mirror of /api/v1. Nothing is billed."}}