{"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 public read-only aeon docs MCP server (Streamable HTTP at /mcp), and aeon's machine-readable discovery documents. aeon is an open-source framework that runs on your own GitHub Actions. Aeon Connect at /connect hosts the dashboard and a remote MCP server at /connect/mcp (OAuth, see x-mcp-connect) that drives your own agent; there is no hosted CRUD API beyond what is described here.\n\n**Versioning.** 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\n**Deprecation.** 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\n**Rate 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"},"x-mcp-connect":{"endpoint":"https://www.aeon.fun/connect/mcp","transport":"streamable-http","auth":"oauth2.1","authorizationMetadata":"https://www.aeon.fun/.well-known/oauth-protected-resource/connect/mcp","description":"Drive your own aeon agent from any MCP client: list and run skills, follow runs, read output and memory, toggle skills. Sign in with GitHub."},"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"}}}}}}},"/docs.md":{"get":{"operationId":"getDocsMarkdown","summary":"Docs guide as markdown","description":"The full /docs guide as one heading-led markdown document, generated from the live page.","responses":{"200":{"description":"Markdown document.","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/llms-full.txt":{"get":{"operationId":"getLlmsFull","summary":"Full llms.txt","description":"The homepage summary plus the whole docs guide in one plain-text file.","responses":{"200":{"description":"Plain-text document.","content":{"text/plain":{"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":{}}}}}}}}