{ "openapi": "3.1.0", "info": { "title": "Refined-X Public APIs", "version": "1.2.0", "description": "Build-time read-only JSON APIs plus NLWeb v0.55-compatible restricted /ask subset. Static JSON is for indexing and mirrors; Ask/MCP are optional remote endpoints when configured. Supports POST /ask with conversational_search, list, summarize, buffered SSE, and MCP ask over Streamable HTTP. Does not support /await, promise responses, elicitation, chatgpt_app, arbitrary extension fields, result actions, or long-term memory." }, "servers": [ { "url": "https://demo.refined-x.com/" } ], "paths": { "/ask": { "post": { "operationId": "askPublicContent", "description": "Query public content via NLWeb v0.55-compatible restricted /ask subset. Anonymous clients are limited to list; browser summarize modes may require Turnstile. Does not support /await, promise responses, elicitation, chatgpt_app, arbitrary extension fields, result actions, or long-term memory.", "servers": [ { "url": "https://demo.refined-x.com/" } ], "security": [ {}, { "PublicAskApiKey": [] } ], "parameters": [ { "name": "cf-turnstile-response", "in": "header", "required": false, "description": "One-time Turnstile token required for browser summarize mode when enabled.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NlWebAskRequest" } } } }, "responses": { "200": { "description": "NLWeb answer or failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NlWebResponse" } } } }, "400": { "description": "Invalid NLWeb request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NlWebResponse" } } } }, "401": { "description": "Missing, invalid, or revoked machine API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NlWebResponse" } } } }, "403": { "description": "需要或未通过浏览器挑战", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NlWebResponse" } } } }, "429": { "description": "请求或预算限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NlWebResponse" } } } } } } }, "/mcp": { "post": { "operationId": "mcpStreamableHttp", "summary": "MCP Streamable HTTP", "description": "Model Context Protocol 无状态端点（Streamable HTTP）。JSON-RPC 2.0 方法：initialize、tools/list、tools/call。当前暴露 ask 工具，语义与 NLWeb v0.55-compatible restricted /ask subset 一致。匿名客户端默认 list 模式；summarize 需 Bearer API Key。端点 URL：。Does not support /await, promise responses, elicitation, chatgpt_app, arbitrary extension fields, result actions, or long-term memory.", "servers": [ { "url": "https://demo.refined-x.com/" } ], "security": [ {}, { "PublicAskApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": {}, "method": { "enum": [ "initialize", "tools/list", "tools/call" ] }, "params": { "type": "object" } } } } } }, "responses": { "200": { "description": "JSON-RPC result 或 error", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "未授权的模式或凭据", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "请求或预算限流", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/profile.json": { "get": { "operationId": "getProfile", "responses": { "200": { "description": "公开个人资料", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } } } } }, "/api/articles.json": { "get": { "operationId": "getArticles", "responses": { "200": { "description": "公开文章索引", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/topics.json": { "get": { "operationId": "getTopics", "responses": { "200": { "description": "公开主题索引", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/search-index.json": { "get": { "operationId": "getSearchIndex", "responses": { "200": { "description": "公开静态搜索索引", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Profile": { "type": "object", "required": [ "id", "name", "url", "sameAs" ], "properties": { "id": { "type": "string", "format": "uri" }, "name": { "type": "string" }, "jobTitle": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "sameAs": { "type": "array", "items": { "type": "string", "format": "uri" } }, "email": { "type": "string", "format": "email" }, "wechat": { "type": "string", "description": "微信号" } } }, "NlWebAskRequest": { "type": "object", "description": "NLWeb v0.55-compatible restricted /ask subset. Supports POST /ask with conversational_search, list, summarize, buffered SSE, and MCP ask over Streamable HTTP. Does not support /await, promise responses, elicitation, chatgpt_app, arbitrary extension fields, result actions, or long-term memory.", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false }, "context": { "type": "object", "maxProperties": 0, "additionalProperties": false }, "prefer": { "type": "object", "additionalProperties": false, "properties": { "streaming": { "type": "boolean" }, "response_format": { "const": "conversational_search" }, "mode": { "enum": [ "list", "summarize", "list, summarize" ] }, "accept-language": { "type": "string" }, "user-agent": { "type": "string" } } }, "meta": { "type": "object", "properties": { "version": { "const": "0.55" } }, "additionalProperties": false } } }, "NlWebResponse": { "type": "object", "required": [ "_meta" ], "properties": { "_meta": { "type": "object", "required": [ "response_type", "version" ], "properties": { "response_type": { "enum": [ "answer", "failure" ] }, "version": { "const": "0.55" } } }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "error": { "type": "object", "additionalProperties": true } } } }, "securitySchemes": { "PublicAskApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "pask__", "description": "运营者签发的 Trusted Machine Client API Key。" } } } }