openapi.json

{ "openapi": "3.1.0", "info": { "title": "aeon agent-facing API", "version": "1.0.0", "summary": "Reachable endpoints an agent can call directly.", "description": "Reachable endpoints an agent can call directly: the NLWeb /ask natural-language query endpoint, the hosted MCP server (Streamable HTTP at /mcp), and aeon's machine-readable discovery documents. aeon is an open-source framework you fork and run; there is no hosted CRUD API beyond what is described here.\n\nVersioning. The API is v1 (URL-path versioned: https://www.aeon.fun/v1/ask aliases /ask). Every response carries an API-Version header. Breaking changes ship under a new version prefix.\n\nDeprecation. When an endpoint is deprecated it returns a Deprecation header (the deprecation date) and a Sunset header (the removal date, RFC 8594), with at least 90 days between them. Nothing is deprecated today.\n\nRate limits. Responses carry standard RateLimit headers (RateLimit-Limit/Remaining/Reset/Policy). The soft limit is 120 requests per 60s per client; /ask returns 429 with a Retry-After header when exceeded.", "license": { "name": "MIT", "url": "https://github.com/aeonfun/aeon/blob/main/LICENSE" }, "contact": { "name": "aeon", "url": "https://www.aeon.fun", "email": "aaron@aeon.fun" } }, "externalDocs": { "description": "aeon developer resources: API, MCP server, OpenAPI, CLI, and the versioning & deprecation policy.", "url": "https://www.aeon.fun/developers" }, "servers": [ { "url": "https://www.aeon.fun/v1", "description": "aeon.fun (versioned, current: v1)" }, { "url": "https://www.aeon.fun", "description": "aeon.fun (unversioned aliases)" } ], "x-api-versioning": { "strategy": "url-path", "current": "v1", "versionHeader": "API-Version", "example": "https://www.aeon.fun/v1/ask" }, "x-deprecation-policy": { "signal": [ "Deprecation", "Sunset" ], "sunsetRfc": "https://www.rfc-editor.org/rfc/rfc8594", "minNoticeDays": 90, "docs": "https://www.aeon.fun/developers#deprecation" }, "x-ratelimit": { "limit": 120, "windowSeconds": 60, "headers": [ "RateLimit-Limit", "RateLimit-Remaining", "RateLimit-Reset", "RateLimit-Policy" ], "retryAfterOn": 429 }, "x-mcp": { "endpoint": "https://www.aeon.fun/mcp", "transport": "streamable-http", "protocolVersion": "2025-06-18", "manifest": "https://www.aeon.fun/.well-known/mcp.json" }, "paths": { "/ask": { "get": { "operationId": "describeAsk", "summary": "Search aeon, or describe the /ask endpoint", "description": "With a q (or query) parameter, runs the same ranked search as POST /ask and returns the results. Without one, returns a self-describing NLWeb descriptor so an agent can discover the request shape before posting.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Natural-language query. When present, returns ranked results.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 8 } } ], "responses": { "200": { "description": "Ranked results when q is set, otherwise the NLWeb endpoint descriptor.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AskResults" }, { "$ref": "#/components/schemas/AskDescriptor" } ] } } } } } }, "post": { "operationId": "askAeon", "summary": "Ask a natural-language question about aeon", "description": "NLWeb query endpoint. Send a natural-language question and get back ranked schema.org items drawn from aeon's pages and live skill catalog. Set streaming (or the header 'prefer: streaming=true') to receive Server-Sent Events instead of a single JSON body.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskRequest" }, "examples": { "setup": { "value": { "query": "how do I set up aeon?" } }, "capability": { "value": { "query": "can aeon scan for vulnerabilities?", "limit": 5 } } } } } }, "responses": { "200": { "description": "Ranked results. application/json for a single body, or text/event-stream when streaming is requested.", "headers": { "API-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "example": "v1" } }, "RateLimit-Limit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer", "example": 120 } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The rate-limit policy in force.", "schema": { "type": "string", "example": "120;w=60" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResults" } }, "text/event-stream": { "schema": { "type": "string", "description": "SSE stream of start / result / complete events, each a JSON payload with an NLWeb _meta object." } } } }, "400": { "description": "Invalid or missing query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "API-Version": { "description": "The API version that served this response.", "schema": { "type": "string", "example": "v1" } }, "RateLimit-Limit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer", "example": 120 } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The rate-limit policy in force.", "schema": { "type": "string", "example": "120;w=60" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp": { "get": { "operationId": "getMcpServerCard", "summary": "MCP server card", "description": "The Model Context Protocol server card for aeon-mcp: its Streamable-HTTP endpoint, protocol version, and tool list. Point an MCP client at https://www.aeon.fun/mcp to call the tools natively.", "responses": { "200": { "description": "MCP server card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerCard" } } } } } }, "post": { "operationId": "callMcp", "summary": "MCP JSON-RPC endpoint (Streamable HTTP)", "description": "The Model Context Protocol endpoint. POST a JSON-RPC 2.0 message (initialize, tools/list, tools/call, ping). Read-only tools expose aeon's public facts and skill catalog. Protocol version 2025-06-18.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "examples": { "listTools": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } }, "callTool": { "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "search_skills", "arguments": { "query": "how do I start?" } } } } } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "202": { "description": "Accepted (a JSON-RPC notification, no response body)." }, "400": { "description": "Malformed JSON-RPC request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } } } } }, "/.well-known/mcp.json": { "get": { "operationId": "getMcpManifest", "summary": "MCP discovery manifest", "description": "The aeon-mcp server card at the well-known discovery path, so a client can find the server without running initialize.", "responses": { "200": { "description": "MCP server card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerCard" } } } } } } }, "/.well-known/agent-skills/index.json": { "get": { "operationId": "getAgentSkillsIndex", "summary": "Agent Skills discovery index", "description": "The Agent Skills discovery index (agentskills.io): the skills this site hosts, each with a name, description, URL, and sha256 digest.", "responses": { "200": { "description": "Agent Skills index.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSkillsIndex" } } } } } } }, "/.well-known/api-catalog": { "get": { "operationId": "getApiCatalog", "summary": "API catalog (RFC 9727)", "description": "An RFC 9727 linkset pointing to aeon's machine-readable surfaces.", "responses": { "200": { "description": "RFC 9727 linkset.", "content": { "application/linkset+json": { "schema": { "$ref": "#/components/schemas/ApiCatalog" } } } } } } }, "/.well-known/ai-catalog.json": { "get": { "operationId": "getAiCatalog", "summary": "ai-catalog manifest (ARD)", "description": "The Agentic Resource Discovery manifest naming every agentic resource aeon publishes and where to reach it.", "responses": { "200": { "description": "ARD ai-catalog manifest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCatalog" } } } } } } }, "/llms.txt": { "get": { "operationId": "getLlmsTxt", "summary": "llms.txt summary", "description": "The llmstxt.org summary of what aeon is and when to use it.", "responses": { "200": { "description": "Plain-text (or markdown, when negotiated) summary.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/index.md": { "get": { "operationId": "getIndexMarkdown", "summary": "Homepage as markdown", "description": "A heading-led markdown representation of the homepage for agents.", "responses": { "200": { "description": "Markdown document.", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "AskRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "The natural-language question." }, "limit": { "type": "integer", "minimum": 1, "maximum": 20, "default": 8, "description": "Maximum number of results to return." }, "streaming": { "type": "boolean", "default": false, "description": "Return Server-Sent Events instead of a single JSON body." } } }, "AskResults": { "type": "object", "required": [ "_meta", "query", "results" ], "properties": { "_meta": { "$ref": "#/components/schemas/NlwebMeta" }, "query": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ResultItem" } } } }, "AskDescriptor": { "type": "object", "properties": { "_meta": { "$ref": "#/components/schemas/NlwebMeta" }, "name": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string" }, "request": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The request field shape." } } }, "ResultItem": { "type": "object", "required": [ "@type", "name", "url", "description" ], "properties": { "@type": { "type": "string", "description": "schema.org type." }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" } } }, "NlwebMeta": { "type": "object", "properties": { "response_type": { "type": "string" }, "version": { "type": "string" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable message." }, "hint": { "type": "string", "description": "How to fix the request." }, "docs": { "type": "string", "format": "uri", "description": "Where to read more." } } } } }, "AgentSkillsIndex": { "type": "object", "required": [ "skills" ], "properties": { "$schema": { "type": "string", "format": "uri" }, "skills": { "type": "array", "items": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "description": "Media type of the skill file." }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "sha256": { "type": "string", "description": "Hex sha256 of the skill file." } } } } } }, "Link": { "type": "object", "required": [ "href" ], "properties": { "href": { "type": "string", "format": "uri" }, "type": { "type": "string", "description": "Media type of the target." }, "title": { "type": "string" } } }, "ApiCatalog": { "type": "object", "required": [ "linkset" ], "properties": { "linkset": { "type": "array", "items": { "type": "object", "required": [ "anchor" ], "properties": { "anchor": { "type": "string", "format": "uri" }, "item": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } }, "service-desc": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } }, "service-doc": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } }, "service-meta": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } } } } } } }, "AiCatalog": { "type": "object", "required": [ "specVersion", "host", "entries" ], "properties": { "specVersion": { "type": "string" }, "host": { "type": "object", "properties": { "displayName": { "type": "string" }, "identifier": { "type": "string" }, "documentationUrl": { "type": "string", "format": "uri" }, "logoUrl": { "type": "string", "format": "uri" } } }, "entries": { "type": "array", "items": { "type": "object", "required": [ "identifier", "url" ], "properties": { "identifier": { "type": "string" }, "displayName": { "type": "string" }, "type": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "McpServerCard": { "type": "object", "required": [ "name", "version", "endpoint", "transport", "protocolVersion", "tools" ], "properties": { "$schema": { "type": "string", "format": "uri" }, "name": { "type": "string" }, "title": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "protocolVersion": { "type": "string" }, "endpoint": { "type": "string", "format": "uri", "description": "Streamable-HTTP endpoint." }, "transport": { "type": "string", "enum": [ "streamable-http" ] }, "capabilities": { "type": "object", "additionalProperties": true }, "tools": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } }, "documentationUrl": { "type": "string", "format": "uri" }, "source": { "type": "string", "format": "uri" }, "contact": { "type": "string" } } }, "JsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "description": "Request id. Omit for a notification.", "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "method": { "type": "string", "description": "initialize | tools/list | tools/call | ping" }, "params": { "type": "object", "additionalProperties": true } } }, "JsonRpcResponse": { "type": "object", "required": [ "jsonrpc" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "result": { "type": "object", "additionalProperties": true }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": {} } } } } } } }