aeon


aeon developer resources.

The API, the MCP server, and everything an agent or developer needs to call aeon.

aeon is an open-source framework you own and run on your own GitHub Actions - there is no hosted CRUD API - but it does expose a small set of real, reachable endpoints for agents and developers, all described here at predictable URLs.

API & endpoints

The full, typed description of every reachable endpoint lives in the OpenAPI 3.1 spec (function-calling ready: unique operation IDs, typed schemas, descriptions). The two input-driven endpoints:

  • /ask - the NLWeb natural-language endpoint. POST { query } (or GET /ask?q=...) to get ranked schema.org resources from aeon's pages and live skill catalog. Add prefer: streaming=true for Server-Sent Events.
  • /mcp - the hosted MCP server (see below).

MCP server

aeon runs a hosted Model Context Protocol server over Streamable HTTP at https://www.aeon.fun/mcp. Point Claude, ChatGPT, Cursor, or any MCP client at that URL and it can call aeon's read-only tools natively - an overview, the setup command, the skill catalog, keyword search, and a natural-language ask. The server card is published at /.well-known/mcp.json. To drive a running instance (write access), run the full aeon-mcp server from the repo.

Aeon Connect (hosted dashboard)

Aeon Connect is the hosted, multi-tenant aeon dashboard: sign in with GitHub, create an instance (a public fork or a private copy of aeonfun/aeon), connect a model, pick skills, and drive runs from the browser. It talks to GitHub through the Aeon Connect GitHub App with tokens scoped to the one repo you pick, and stores keys only as encrypted secrets in that repo. It is also the reference implementation of the ADK pattern for building products on aeon.

CLI

Every aeon instance is driven by its own ./aeon CLI in its repo: authenticate, pick skills, and schedule them from the command line. aeon also ships as an installable Claude Code plugin from the plugin/ directory of the source repo.

Machine-readable discovery

Agent-facing files an agent can fetch directly:

Authentication & rate limits

The reachable read-only endpoints (/ask, /mcp, and the discovery documents) need no authentication - everything they return is public. Every response carries standard RateLimit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy); the soft limit is 120 requests per 60 seconds per client, and /ask answers a 429 with a Retry-After header when it is exceeded. Unknown /api/* paths return a structured JSON 404.

API versioning

The reachable API is v1, versioned in the URL path - https://www.aeon.fun/v1/ask is the versioned alias of /ask - and echoed in an API-Version response header on every API response. Breaking changes ship under a new version prefix (/v2/…); the previous version keeps working through its sunset window.

Deprecation & sunset policy

When an endpoint is deprecated, aeon signals it two ways so an agent can plan around it:

  • a Deprecation response header carrying the date the endpoint was deprecated (RFC 9745); and
  • a Sunset response header carrying the date it will be removed (RFC 8594), with a Link header (rel="deprecation") pointing back to this page.

There is a minimum of 90 days between the Deprecation and Sunset dates. Nothing is deprecated today, so neither header is emitted. This policy, along with the versioning and rate-limit conventions, is also declared in the OpenAPI spec (the x-api-versioning, x-deprecation-policy, and x-ratelimit extensions).

Errors

Every agent-facing endpoint returns structured JSON errors, never an HTML page, so a failure is parseable: { "error": { "code", "message", "hint", "docs" } }. The docs field links to the matching entry below.

  • invalid_json (400) - The request body is not valid JSON.
  • missing_query (400) - POST /ask was called without a non-empty query.
  • not_found (404) - No API endpoint exists at the requested /api/* path.
  • method_not_allowed (405) - The MCP server was asked for a server-initiated SSE stream it does not offer.
  • rate_limited (429) - The per-client rate limit was exceeded. Wait for Retry-After seconds.



RUN NOW