{ "openapi": "3.1.0", "info": { "title": "Nexus Public Discovery API", "version": "1.2.0", "description": "Read-only public product, pricing, service and AI discovery. publicKnowledge.facts shares the website assistant's canonical public corpus, including published prices and billing rules. Cite exact fact URLs and retain scope boundaries. Preserve monthly billing versus daily capacity units, per-module/per-location capacity and per-platform setup or add-ons. Do not infer unpublished overage fees, discounts, throughput guarantees, certifications or service levels. Existing product and capability fields remain available." }, "servers": [ { "url": "https://www.nexus-soft.org" } ], "paths": { "/api/health": { "get": { "operationId": "getHealth", "summary": "Service health", "responses": { "200": { "description": "API is available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "example": { "ok": true, "service": "nexus-api" } } } } } } }, "/api/ready": { "get": { "operationId": "getReadiness", "summary": "Service readiness", "responses": { "200": { "description": "API and MongoDB are ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" }, "example": { "ok": true, "service": "nexus-api", "database": "ready" } } } }, "500": { "description": "A required runtime dependency is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "Unexpected server error" } } } } } } }, "/api/catalog": { "get": { "operationId": "getPublicCatalog", "summary": "Products, pricing, services and sourced public knowledge", "responses": { "200": { "description": "Public catalog with legacy capability summaries and the complete sourced fact corpus", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } } } } }, "/api/capabilities": { "get": { "operationId": "getPublicCapabilities", "summary": "Platform capabilities and sourced public knowledge", "responses": { "200": { "description": "Capability summaries plus the same publicKnowledge, pricing and services as the catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capabilities" } } } } } } }, "/.well-known/mcp/server.json": { "get": { "operationId": "getMcpMetadata", "summary": "Public MCP server metadata", "responses": { "200": { "description": "Server identity and public Streamable HTTP endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpMetadata" } } } } } } }, "/llms.txt": { "get": { "operationId": "getAiDocumentationIndex", "summary": "Public documentation and discovery index", "responses": { "200": { "description": "Markdown documentation index", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/llms-full.txt": { "get": { "operationId": "getFullPublicKnowledge", "summary": "Complete public knowledge with sources and boundaries", "responses": { "200": { "description": "Markdown containing catalog JSON and operator knowledge", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/mcp": { "post": { "operationId": "callPublicMcp", "summary": "Streamable HTTP MCP endpoint", "description": "Initialize MCP, list tools/resources/prompts, read nexus://products/catalog or nexus://knowledge/public, or call a read-only discovery tool. get_public_knowledge accepts optional query, kind and topic filters, offset (0–10000) and limit (1–30, default 12). Its text result contains JSON with scope, status, total, offset, hasMore and facts. Existing seven discovery tools preserve their response formats. Send Accept: application/json, text/event-stream.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_public_knowledge", "arguments": { "kind": "pricing", "limit": 12 } } } } } }, "responses": { "200": { "description": "MCP JSON-RPC response or event stream", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "202": { "description": "MCP notification accepted without a response body" }, "400": { "description": "Invalid JSON-RPC or MCP request" }, "406": { "description": "Required JSON and event-stream Accept types were not provided" } } } } }, "components": { "schemas": { "StringList": { "type": "array", "items": { "type": "string" } }, "StringMap": { "type": "object", "additionalProperties": { "type": "string" } }, "DescriptionRows": { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string" } } }, "Health": { "type": "object", "required": [ "ok", "service" ], "properties": { "ok": { "const": true }, "service": { "const": "nexus-api" } } }, "Readiness": { "allOf": [ { "$ref": "#/components/schemas/Health" }, { "type": "object", "required": [ "database" ], "properties": { "database": { "const": "ready" } } } ] }, "ApiError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "PublicFact": { "type": "object", "required": [ "id", "kind", "url", "topics", "boundary", "title", "text" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9.-]+$", "examples": [ "pricing.product.search.rate" ] }, "kind": { "type": "string", "enum": [ "product", "solution", "pricing", "service", "format", "guide", "policy", "resource" ] }, "url": { "type": "string", "format": "uri", "description": "Exact public source URL for this fact.", "examples": [ "https://www.nexus-soft.org/products/search/price-plans" ] }, "topics": { "$ref": "#/components/schemas/StringList" }, "sourceTitle": { "type": "string", "description": "Source label when supplied by the canonical corpus." }, "lastModified": { "type": "string", "format": "date", "description": "Date of a substantive revision to the source guide, when recorded. Not a publication date, live-data timestamp or human certification." }, "sourceReferences": { "type": "array", "description": "Supporting product or official technical references published with the source guide. Retain the fact's own url and scope boundary; references do not certify a Nexus integration.", "items": { "type": "object", "required": [ "url", "title" ], "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" } } } }, "title": { "type": "string", "examples": [ "Search Syndication: published capacity price" ] }, "text": { "type": "string" }, "boundary": { "type": "string", "description": "Scope limitation that must be retained with the fact; not a guarantee or offer." } } }, "PublicFacts": { "type": "array", "items": { "$ref": "#/components/schemas/PublicFact" } }, "PublicKnowledge": { "type": "object", "required": [ "scope", "factCount", "sourceCount", "sourceUrls", "facts" ], "properties": { "scope": { "type": "string" }, "factCount": { "type": "integer", "minimum": 0 }, "sourceCount": { "type": "integer", "minimum": 0 }, "sourceUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "uniqueItems": true }, "facts": { "$ref": "#/components/schemas/PublicFacts" } } }, "PublicKnowledgeResult": { "type": "object", "required": [ "scope", "status", "total", "offset", "hasMore", "facts" ], "properties": { "scope": { "type": "string" }, "status": { "enum": [ "available", "scope_confirmation_required", "public_information_only" ] }, "total": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "facts": { "$ref": "#/components/schemas/PublicFacts" } }, "description": "JSON encoded in the text content returned by MCP get_public_knowledge. total counts the available matches for this query, not the full corpus." }, "PlatformSolution": { "type": "object", "required": [ "slug", "name", "goal", "audience", "summary", "capture", "scope", "boundary", "example", "modules", "workflow", "requirements", "formats", "capabilities" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "goal": { "type": "string" }, "audience": { "type": "string" }, "summary": { "type": "string" }, "capture": { "type": "string" }, "scope": { "type": "string" }, "boundary": { "type": "string" }, "example": { "type": "string" }, "modules": { "$ref": "#/components/schemas/StringList" }, "workflow": { "$ref": "#/components/schemas/StringList" }, "requirements": { "$ref": "#/components/schemas/StringList" }, "formats": { "$ref": "#/components/schemas/StringList" }, "capabilities": { "$ref": "#/components/schemas/DescriptionRows" } } }, "AdFormat": { "type": "object", "required": [ "name", "category", "definition", "availability", "placements", "buyingModels", "targeting", "deliveryFlow", "deployment", "metrics" ], "properties": { "name": { "type": "string" }, "category": { "type": "string" }, "definition": { "type": "string" }, "availability": { "type": "string" }, "placements": { "$ref": "#/components/schemas/StringList" }, "buyingModels": { "$ref": "#/components/schemas/StringList" }, "targeting": { "$ref": "#/components/schemas/StringList" }, "deliveryFlow": { "$ref": "#/components/schemas/StringList" }, "deployment": { "type": "object", "required": [ "kind", "solution", "nexus", "requires" ], "properties": { "kind": { "type": "string" }, "solution": { "type": "string" }, "nexus": { "type": "string" }, "requires": { "type": "string" } } }, "metrics": { "type": "array", "items": { "type": "object", "required": [ "name", "definition" ], "properties": { "name": { "type": "string" }, "definition": { "type": "string" } } } } } }, "OperatingGuide": { "type": "object", "required": [ "seoDescription", "eyebrow", "title", "lead", "accent", "boundary", "closing", "closingText", "visual", "metrics", "dimensions", "capabilities", "workflow", "definitions" ], "properties": { "seoDescription": { "type": "string" }, "eyebrow": { "type": "string" }, "title": { "type": "string" }, "lead": { "type": "string" }, "accent": { "type": "string" }, "boundary": { "type": "string" }, "closing": { "type": "string" }, "closingText": { "type": "string" }, "visual": { "$ref": "#/components/schemas/StringList" }, "metrics": { "$ref": "#/components/schemas/StringList" }, "dimensions": { "$ref": "#/components/schemas/StringList" }, "capabilities": { "$ref": "#/components/schemas/DescriptionRows" }, "workflow": { "$ref": "#/components/schemas/DescriptionRows" }, "definitions": { "$ref": "#/components/schemas/DescriptionRows" } } }, "Standards": { "type": "object", "required": [ "scope", "protocols" ], "properties": { "scope": { "type": "string" }, "protocols": { "type": "array", "items": { "type": "object", "required": [ "key", "organization", "title", "subtitle", "description", "linkLabel", "href" ], "properties": { "key": { "type": "string" }, "organization": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "description": { "type": "string" }, "linkLabel": { "type": "string" }, "href": { "type": "string", "format": "uri" } } } } } }, "SharedDiscovery": { "type": "object", "required": [ "name", "products", "platformSolutions", "adFormats", "operatingCapabilities", "security", "publicKnowledge", "pricing", "services" ], "properties": { "name": { "const": "Nexus" }, "products": { "$ref": "#/components/schemas/StringMap" }, "platformSolutions": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformSolution" } }, "adFormats": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/AdFormat" } }, "operatingCapabilities": { "$ref": "#/components/schemas/StringMap" }, "security": { "type": "string" }, "publicKnowledge": { "$ref": "#/components/schemas/PublicKnowledge" }, "pricing": { "$ref": "#/components/schemas/PublicFacts", "description": "Canonical published prices and billing rules, including capacity units, per-platform charges, inclusions, trials and boundaries for unpublished terms." }, "services": { "$ref": "#/components/schemas/PublicFacts", "description": "Canonical public facts tagged services, including engineering and server management scope." } } }, "Catalog": { "allOf": [ { "$ref": "#/components/schemas/SharedDiscovery" }, { "type": "object", "required": [ "category", "heritage", "website", "mcp", "operations", "standards" ], "properties": { "category": { "type": "string" }, "heritage": { "type": "string" }, "website": { "type": "string", "format": "uri" }, "mcp": { "type": "string", "format": "uri" }, "operations": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/OperatingGuide" } }, "standards": { "$ref": "#/components/schemas/Standards" } } } ] }, "Capabilities": { "allOf": [ { "$ref": "#/components/schemas/SharedDiscovery" }, { "type": "object", "required": [ "version", "targeting", "ai", "documentation", "openapi" ], "properties": { "version": { "type": "string" }, "targeting": { "type": "string" }, "ai": { "type": "string" }, "documentation": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" } } } ] }, "McpMetadata": { "type": "object", "required": [ "name", "title", "description", "version", "websiteUrl", "remotes" ], "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "websiteUrl": { "type": "string", "format": "uri" }, "remotes": { "type": "array", "items": { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "const": "streamable-http" }, "url": { "type": "string", "format": "uri" } } } } } }, "JsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "type": "string" }, "params": { "type": "object", "additionalProperties": true } } }, "JsonRpcResponse": { "oneOf": [ { "type": "object", "required": [ "jsonrpc", "id", "result" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer", "null" ] }, "result": { "type": "object", "additionalProperties": true } } }, { "type": "object", "required": [ "jsonrpc", "id", "error" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer", "null" ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": {} } } } } ] } } } }