{ "openapi": "3.1.0", "info": { "title": "HYD Public APIs", "version": "1.4.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. Supported locales: zh-CN, en (default: zh-CN). Every static read path is documented once per locale tree." }, "servers": [ { "url": "https://hydblog.xyz" } ], "paths": { "/api/profile.json": { "get": { "operationId": "getProfile", "description": "Served from the default locale tree (zh-CN) at the site root.", "responses": { "200": { "description": "公开个人资料", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } } } } }, "/api/articles.json": { "get": { "operationId": "getArticles", "description": "Served from the default locale tree (zh-CN) at the site root.", "responses": { "200": { "description": "公开文章索引", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/topics.json": { "get": { "operationId": "getTopics", "description": "Served from the default locale tree (zh-CN) at the site root.", "responses": { "200": { "description": "公开主题索引", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/search-index.json": { "get": { "operationId": "getSearchIndex", "description": "Served from the default locale tree (zh-CN) at the site root.", "responses": { "200": { "description": "公开静态搜索索引", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/en/api/profile.json": { "get": { "operationId": "getProfileEn", "description": "Served from the en locale tree under /en/.", "responses": { "200": { "description": "Public profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } } } } }, "/en/api/articles.json": { "get": { "operationId": "getArticlesEn", "description": "Served from the en locale tree under /en/.", "responses": { "200": { "description": "Public article index", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/en/api/topics.json": { "get": { "operationId": "getTopicsEn", "description": "Served from the en locale tree under /en/.", "responses": { "200": { "description": "Public topic index", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/en/api/search-index.json": { "get": { "operationId": "getSearchIndexEn", "description": "Served from the en locale tree under /en/.", "responses": { "200": { "description": "Public static search index", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/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. Streaming: set prefer.streaming=true and/or Accept: text/event-stream for buffered SSE. Does not support /await, promise responses, elicitation, chatgpt_app, arbitrary extension fields, result actions, or long-term memory.", "servers": [ { "url": "https://ask.hydblog.xyz" } ], "security": [ {}, { "PublicAskApiKey": [] } ], "parameters": [ { "name": "Accept", "in": "header", "required": false, "description": "Include text/event-stream to request buffered SSE when prefer.streaming is also honored by the Worker.", "schema": { "type": "string", "examples": [ "application/json", "text/event-stream" ] } }, { "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. Buffered JSON by default; when prefer.streaming is true or Accept includes text/event-stream, the Worker may return buffered SSE (events: start, result, complete).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NlWebResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream. event:start (meta), event:result (index + item), event:complete (meta). Each event data payload is JSON." } } } }, "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 endpoint (protocol profile undeclared until deployment acceptance; do not assume modern dual-era). Exposes ask tool aligned with NLWeb v0.55-compatible restricted /ask subset. Anonymous clients default to list; summarize may require Bearer API Key. Endpoint: https://ask.hydblog.xyz/mcp. This OpenAPI path is an endpoint map for humans and generators — prefer an MCP SDK for wire protocol details. Legacy example: JSON-RPC initialize then tools/list / tools/call without modern MCP-* headers. Modern example: MCP-Protocol-Version: 2026-07-28 with MCP-Method / MCP-Name as required by the 2026-07-28 Streamable HTTP transport, plus matching request _meta when applicable. Modern protocol headers are conditional — they must not be treated as required for every POST. Does not support /await, promise responses, elicitation, chatgpt_app, arbitrary extension fields, result actions, or long-term memory.", "servers": [ { "url": "https://ask.hydblog.xyz" } ], "security": [ {}, { "PublicAskApiKey": [] } ], "parameters": [ { "name": "MCP-Protocol-Version", "in": "header", "required": false, "description": "Optional. Modern (2026-07-28) clients send this with the negotiated protocol version. Legacy initialize clients may omit it or send a 2025-* version after handshake. Do not require this header for all requests.", "schema": { "type": "string", "examples": [ "2026-07-28", "2025-06-18" ] } }, { "name": "MCP-Method", "in": "header", "required": false, "description": "Optional modern routing header (e.g. tools/call, tools/list, server/discover). Required only for modern Streamable HTTP self-describing calls, not for legacy initialize sessions.", "schema": { "type": "string" } }, { "name": "MCP-Name", "in": "header", "required": false, "description": "Optional modern tool name header for tools/call (e.g. ask). Aligns with request _meta when present. Not required for legacy clients.", "schema": { "type": "string", "examples": [ "ask" ] } }, { "name": "Accept", "in": "header", "required": false, "description": "Streamable HTTP clients typically send application/json, text/event-stream. Not all responses are SSE.", "schema": { "type": "string", "examples": [ "application/json, text/event-stream" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": {}, "method": { "type": "string" }, "params": { "type": "object" } } } } } }, "responses": { "200": { "description": "JSON-RPC result 或 error（含工具 result.isError）", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted notification (e.g. notifications/initialized); empty body per Streamable HTTP." }, "401": { "description": "Missing, invalid, or revoked machine API key", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "未授权的模式或凭据", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "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" }, "qq": { "type": "string", "description": "QQ 号" }, "location": { "type": "string", "description": "城市级位置" }, "education": { "type": "string", "description": "在读院校" }, "educationHistory": { "type": "array", "description": "教育经历", "items": { "type": "object", "required": [ "school", "degree", "major", "period" ], "properties": { "school": { "type": "string" }, "degree": { "type": "string" }, "major": { "type": "string" }, "period": { "type": "string" } } } } } }, "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.", "properties": { "query": { "type": "object", "properties": { "text": { "type": "string", "description": "Question text. After trim, must contain 1–500 Unicode code points (not UTF-16 length)." } }, "required": [ "text" ], "additionalProperties": false }, "prefer": { "type": "object", "properties": { "streaming": { "type": "boolean" }, "mode": { "type": "string", "description": "Comma-separated modes: list, summarize. Entry defaults: HTTP Ask uses list, summarize; MCP Ask uses list (including empty string).", "examples": [ "list", "summarize", "list, summarize" ] }, "response_format": { "const": "conversational_search" }, "accept-language": { "type": "string" }, "user-agent": { "type": "string" } }, "additionalProperties": false }, "context": { "type": "object", "maxProperties": 0, "additionalProperties": false }, "meta": { "type": "object", "properties": { "version": { "const": "0.55" } }, "additionalProperties": false } }, "required": [ "query" ], "additionalProperties": false }, "NlWebAnswer": { "type": "object", "required": [ "_meta", "results" ], "properties": { "_meta": { "type": "object", "required": [ "response_type", "response_format", "version", "request_id" ], "properties": { "response_type": { "const": "answer" }, "response_format": { "const": "conversational_search" }, "version": { "const": "0.55" }, "request_id": { "type": "string" }, "streaming": { "type": "boolean" } }, "additionalProperties": false }, "results": { "type": "array", "items": { "type": "object", "required": [ "@type" ], "properties": { "@type": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": false }, "NlWebFailure": { "type": "object", "required": [ "_meta", "error" ], "properties": { "_meta": { "type": "object", "required": [ "response_type", "response_format", "version", "request_id" ], "properties": { "response_type": { "const": "failure" }, "response_format": { "const": "conversational_search" }, "version": { "const": "0.55" }, "request_id": { "type": "string" } }, "additionalProperties": false }, "error": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "NlWebResponse": { "oneOf": [ { "$ref": "#/components/schemas/NlWebAnswer" }, { "$ref": "#/components/schemas/NlWebFailure" } ] } }, "securitySchemes": { "PublicAskApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "pask__", "description": "运营者签发的 Trusted Machine Client API Key。" } } } }