{ "openapi": "3.1.1", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Fous API", "version": "1.1.0", "description": "One query endpoint for direct API calls and automatic routing. Responses may include additional fields; clients should ignore fields they do not use." }, "servers": [{ "url": "https://api.fous.com" }], "security": [{ "apiKey": [] }], "paths": { "/": { "get": { "operationId": "getService", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "service": { "type": "string" }, "version": { "type": "string" }, "product": { "type": "string" }, "status": { "type": "string" }, "build_available": { "type": "boolean" }, "registered_providers": { "type": "integer" }, "endpoint": { "const": "/v1/query" } }, "additionalProperties": true } }, "required": ["success", "data"], "additionalProperties": false } } } }, "400": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge; invalid or expired keys use invalid_token.", "schema": { "type": "string" } } } }, "402": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/health": { "get": { "operationId": "getHealth", "security": [], "description": "Operational readiness. A degraded response uses the health envelope, not an execution error.", "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": ["ok", "degraded"] }, "service": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "uptime_seconds": { "type": "integer" }, "checks": { "type": "object", "additionalProperties": true } }, "required": ["status", "service", "timestamp", "uptime_seconds", "checks"], "additionalProperties": false } } } }, "503": { "description": "Degraded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": ["ok", "degraded"] }, "service": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "uptime_seconds": { "type": "integer" }, "checks": { "type": "object", "additionalProperties": true } }, "required": ["status", "service", "timestamp", "uptime_seconds", "checks"], "additionalProperties": false } } } } } } }, "/v1/query": { "post": { "operationId": "query", "summary": "Query an API directly or route a prompt", "description": "Successful prompt searches cost 5 credits, including prompts with a named API. Direct calls with api, operation, and input cost 1 credit. The full price is reserved before execution; failures without a completed receipt release it. 170-second overall request deadline; individual workflows also enforce their execution limits. With Idempotency-Key, work continues after client disconnection; completed terminal results are retained for 24 hours. Identical retries return the same status/body. Concurrent retries return 409 with Retry-After and Location. A changed request under the same key returns 409. Stale unfinished claims never dispatch again. Without a key, a repeated POST is a new billable request. Switching JSON/SSE transport does not change identity.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "maxLength": 255, "pattern": "^[!-~]+$" }, "description": "Unique opaque key per logical query, scoped to the authenticated organization. Retain it for retries." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "examples": { "direct": { "value": { "api": "@x_com", "operation": "tweet_lookup", "version": 1, "input": { "tweet_id": "123" }, "response": { "include": ["text"] } } }, "automatic": { "value": { "prompt": "How many followers does elonmusk have?", "api": "@x_com" } } } } } }, "responses": { "200": { "description": "Completed JSON result, or an SSE stream ending with result/error. SSE HTTP status stays 200; terminal errors carry error.status.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } }, "Location": { "schema": { "type": "string" } }, "X-Fous-Billing-Status": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResult" } }, "text/event-stream": { "schema": { "type": "string" }, "example": "event: progress\ndata: {\"request_id\":\"req_1234567890\",\"stage\":\"accepted\",\"message\":\"Request received.\"}\n\nevent: result\ndata: {\"success\":true,\"data\":{\"output\":{},\"receipt\":{\"request_id\":\"req_1234567890\",\"api\":\"@x_com\",\"operation\":\"tweet_lookup\",\"billing\":{\"status\":\"settled\",\"reserved_credits\":1,\"charged_credits\":1}}}}\n\n" } } }, "400": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge; invalid or expired keys use invalid_token.", "schema": { "type": "string" } } } }, "402": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/query/requests/{request_id}": { "get": { "operationId": "getRequest", "summary": "Retrieve request status, billing and retained result", "parameters": [ { "in": "path", "name": "request_id", "required": true, "schema": { "type": "string", "pattern": "^req_[A-Za-z0-9_-]{10,64}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestStatus" } } } }, "400": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge; invalid or expired keys use invalid_token.", "schema": { "type": "string" } } } }, "402": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/query/requests/{request_id}/feedback": { "post": { "operationId": "feedback", "summary": "Rate a completed public API call", "parameters": [ { "in": "path", "name": "request_id", "required": true, "schema": { "type": "string", "pattern": "^req_[A-Za-z0-9_-]{10,64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "enum": [1, -1, null] } }, "required": ["value"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": ["success"], "additionalProperties": false } } } }, "400": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge; invalid or expired keys use invalid_token.", "schema": { "type": "string" } } } }, "402": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/auth": { "get": { "operationId": "authenticate", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": ["success"], "additionalProperties": false } } } }, "400": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge; invalid or expired keys use invalid_token.", "schema": { "type": "string" } } } }, "402": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/catalog/categories": { "get": { "security": [], "operationId": "listApiCategories", "description": "The supported Discover category IDs and labels. Each API shares one category across its methods.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "ai", "blockchain", "commerce", "communication", "data", "developer-tools", "documents", "education", "energy", "entertainment", "finance", "food", "government", "health", "identity", "jobs", "legal", "logistics", "maps", "marketing", "media", "news", "payments", "productivity", "real-estate", "science", "search", "security", "social", "sports", "storage", "travel", "weather", "other" ] }, "label": { "type": "string" } }, "required": ["id", "label"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } }, "required": ["success", "data"], "additionalProperties": false } } } }, "400": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge; invalid or expired keys use invalid_token.", "schema": { "type": "string" } } } }, "402": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/catalog": { "get": { "security": [], "operationId": "listApis", "description": "Lists active public APIs only. API handles include the @ prefix; each method supplies its callable operation and human-readable label.", "parameters": [ { "in": "query", "name": "query", "schema": { "type": "string" } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "category", "schema": { "type": "string", "enum": [ "ai", "blockchain", "commerce", "communication", "data", "developer-tools", "documents", "education", "energy", "entertainment", "finance", "food", "government", "health", "identity", "jobs", "legal", "logistics", "maps", "marketing", "media", "news", "payments", "productivity", "real-estate", "science", "search", "security", "social", "sports", "storage", "travel", "weather", "other" ] } }, { "in": "query", "name": "api", "schema": { "type": "string", "pattern": "^@[a-z0-9][a-z0-9_-]{0,99}$", "example": "@x_com" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 60 } }, { "in": "query", "name": "sort", "schema": { "enum": ["relevant", "popular", "newest", "updated"] } }, { "in": "query", "name": "max_cost_credits", "description": "Maximum estimated cost per call in credits.", "schema": { "type": "number", "minimum": 0, "maximum": 10000 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogApi" } }, "next_cursor": { "type": ["string", "null"] } }, "required": ["items", "next_cursor"], "additionalProperties": false } }, "required": ["success", "data"], "additionalProperties": false } } } }, "400": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge; invalid or expired keys use invalid_token.", "schema": { "type": "string" } } } }, "402": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/catalog/tools": { "get": { "operationId": "listTools", "parameters": [ { "in": "query", "name": "cursor", "schema": { "type": "integer", "minimum": 1 } }, { "in": "query", "name": "operation_id", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } }, "next_cursor": { "type": ["string", "null"] } }, "required": ["items", "next_cursor"], "additionalProperties": false } }, "required": ["success", "data"], "additionalProperties": false } } } }, "400": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge; invalid or expired keys use invalid_token.", "schema": { "type": "string" } } } }, "402": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/files": { "post": { "operationId": "uploadFile", "description": "Upload up to 10 MB; files are organization-private and expire after 30 days.", "parameters": [ { "in": "header", "name": "X-File-Name", "required": true, "description": "URI-encoded filename, up to 160 decoded characters.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/File" } }, "required": ["success", "data"], "additionalProperties": false } } } }, "400": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge; invalid or expired keys use invalid_token.", "schema": { "type": "string" } } } }, "402": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/files/{file_id}": { "get": { "operationId": "getFile", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "type": "string", "pattern": "^file_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/File" } }, "required": ["success", "data"], "additionalProperties": false } } } }, "400": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge; invalid or expired keys use invalid_token.", "schema": { "type": "string" } } } }, "402": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteFile", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "type": "string", "pattern": "^file_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": ["success"], "additionalProperties": false } } } }, "204": { "description": "Deleted" }, "400": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge; invalid or expired keys use invalid_token.", "schema": { "type": "string" } } } }, "402": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/files/{file_id}/content": { "get": { "operationId": "downloadFile", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "type": "string", "pattern": "^file_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "File bytes, Content-Type reflects the original file.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer authentication challenge; invalid or expired keys use invalid_token.", "schema": { "type": "string" } } } }, "402": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Standard error. Inspect error.code, details and request_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/jwks.json": { "get": { "operationId": "getSigningKeys", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": ["keys"], "additionalProperties": false } } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenApi", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "fous_sk_..." } }, "schemas": { "QueryRequest": { "type": "object", "properties": { "api": { "type": "string", "pattern": "^@[a-z0-9][a-z0-9_-]{0,99}$" }, "operation": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,99}$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647, "description": "Pin an immutable method contract version. Omit to keep the method’s established default version; publishing a new version never moves that default. Only valid with api, operation and input." }, "input": { "$ref": "#/components/schemas/QueryRequest/$defs/__schema0" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "allowed_apis": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^@[a-z0-9][a-z0-9_-]{0,99}$" }, "uniqueItems": true }, "blocked_apis": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^@[a-z0-9][a-z0-9_-]{0,99}$" }, "uniqueItems": true }, "attachments": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^file_[0-9a-f]{32}$" }, "purpose": { "default": "input", "type": "string", "enum": ["input", "context"] } }, "required": ["id"], "additionalProperties": false } }, "stream": { "type": "boolean" }, "response": { "type": "object", "properties": { "format": { "default": "json", "type": "string", "enum": ["json", "text", "markdown"] }, "include": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "uniqueItems": true }, "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "mapping": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "maxLength": 1000 }, "source": { "type": "string", "maxLength": 1000 } }, "required": ["target", "source"], "additionalProperties": false } } }, "additionalProperties": false, "allOf": [ { "not": { "anyOf": [ { "required": ["include", "schema"] }, { "required": ["include", "mapping"] } ] } }, { "if": { "required": ["mapping"] }, "then": { "required": ["schema"] } } ] }, "visibility": { "type": "string", "enum": ["public", "private"], "description": "A handle reaches your organization’s private API and the public API alike; a private method wins a name collision. Set public or private to use one side only." } }, "additionalProperties": false, "$defs": { "__schema0": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, { "type": "array", "items": { "$ref": "#/components/schemas/QueryRequest/$defs/__schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/QueryRequest/$defs/__schema0" } } ] } }, "description": "Provide prompt OR api + operation + input. Allowed and blocked API lists must not overlap. Use include alone, or schema with optional mapping.", "oneOf": [ { "required": ["prompt"], "not": { "anyOf": [ { "required": ["operation"] }, { "required": ["input"] }, { "required": ["version"] } ] } }, { "required": ["api", "operation", "input"], "not": { "required": ["prompt"] } } ] }, "Receipt": { "type": "object", "properties": { "request_id": { "type": "string" }, "api": { "type": ["string", "null"] }, "operation": { "type": ["string", "null"] }, "billing": { "type": "object", "properties": { "status": { "enum": ["not_started", "pending", "settled", "released"] }, "reserved_credits": { "type": "number" }, "charged_credits": { "type": ["number", "null"] } }, "required": ["status", "reserved_credits", "charged_credits"], "additionalProperties": false } }, "required": ["request_id", "api", "operation", "billing"], "additionalProperties": false }, "QueryResult": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "required": ["output", "receipt"], "properties": { "output": {}, "receipt": { "$ref": "#/components/schemas/Receipt" } }, "additionalProperties": true } }, "required": ["success", "data"], "additionalProperties": false }, "Error": { "type": "object", "properties": { "success": { "const": false }, "error": { "type": "object", "required": ["type", "code", "message", "status"], "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" }, "param": { "type": "string" }, "doc_url": { "type": "string" }, "details": {}, "receipt": { "$ref": "#/components/schemas/Receipt" } }, "additionalProperties": true } }, "required": ["success", "error"], "additionalProperties": false }, "RequestStatus": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "required": ["request_id", "status"], "properties": { "request_id": { "type": "string" }, "status": { "type": "string" }, "result": { "oneOf": [ { "$ref": "#/components/schemas/QueryResult" }, { "$ref": "#/components/schemas/Error" }, { "type": "null" } ] }, "response_status": { "type": ["number", "null"] }, "result_expires_at": { "type": ["string", "null"] }, "error_code": { "type": ["string", "null"] }, "receipt": { "$ref": "#/components/schemas/Receipt" }, "feedback": { "enum": [1, -1, null] }, "can_rate": { "type": "boolean" }, "feedback_unavailable_reason": { "type": ["string", "null"] } }, "additionalProperties": true } }, "required": ["success", "data"], "additionalProperties": false }, "File": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": ["id", "name", "content_type", "size", "expires_at"], "additionalProperties": false }, "CatalogApi": { "type": "object", "required": ["api", "name", "operations"], "properties": { "api": { "type": "string", "pattern": "^@[a-z0-9][a-z0-9_-]{0,99}$", "example": "@x_com" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string", "enum": [ "ai", "blockchain", "commerce", "communication", "data", "developer-tools", "documents", "education", "energy", "entertainment", "finance", "food", "government", "health", "identity", "jobs", "legal", "logistics", "maps", "marketing", "media", "news", "payments", "productivity", "real-estate", "science", "search", "security", "social", "sports", "storage", "travel", "weather", "other" ] }, "website_url": { "type": ["string", "null"] }, "logo_url": { "type": ["string", "null"] }, "availability": { "type": "string" }, "visibility": { "const": "public" }, "is_enabled": { "const": true }, "operations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "operation": { "type": "string" }, "label": { "type": "string" }, "contract_version": { "type": "integer" }, "cost_credits": { "type": "number" } }, "additionalProperties": true } } }, "additionalProperties": true }, "Tool": { "type": "object", "required": [ "name", "title", "description", "inputSchema", "outputSchema", "operation_id", "api", "operation", "contract_version" ], "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object" }, "outputSchema": { "type": ["object", "null"] }, "operation_id": { "type": "integer" }, "api": { "type": "string", "pattern": "^@[a-z0-9][a-z0-9_-]{0,99}$", "example": "@x_com" }, "operation": { "type": "string" }, "contract_version": { "type": "integer" } }, "additionalProperties": true } } } }