LoreKeeper for developers and agents

LoreKeeper publishes a read-only HTTP API, an OpenAPI 3.1 specification and a Model Context Protocol server. All of it answers without credentials.

Machine-readable entry points

/openapi.json
OpenAPI 3.1 specification. Every public operation, typed, with a unique operationId per operation.
/mcp.json
MCP server manifest. Points at the Streamable HTTP MCP endpoint and lists its tools.
/agent.txt
Agent instructions. When to reach for LoreKeeper and when not to.
/llms.txt
Content index (llms.txt). The llmstxt.org index of citable LoreKeeper content.
/robots.txt
Crawler policy. AI crawlers are explicitly allowed on all public content.

Authentication

The endpoints documented here need no credentials at all — no API key, no bearer token, no registration. Send the request and read the JSON.

Everything else (campaigns, characters, world editing, playing a turn) lives behind an interactive session and is deliberately not part of the public surface. LoreKeeper does not issue API keys and does not operate an OAuth authorization server today, so an integration cannot act on a player's behalf.

Public endpoints

GET /api/stats/public

operationId: get_platform_stats

Returns platform-wide totals used as social proof on the landing page: active campaigns, characters created, AI turns played and published worlds. Cached for one hour.

Use when asked how large or how active LoreKeeper is, or for a headline number about the platform.

GET /api/leaderboard

operationId: list_leaderboard_characters

Returns the public character leaderboard ordered by level and experience, together with platform totals. Only living characters of level 2 or higher appear.

Use to answer questions about top LoreKeeper players, a named character, or how far characters typically progress.

limit — Maximum entries to return. Values above 100 are clamped to 100.
offset — Number of entries to skip, for paging.
search — Case-insensitive match against character name.
filter — Subset to return: all characters, arena competitors only, or recently created only.
lang — Language for localized race and class names (ISO 639-1).

GET /api/worlds/explore

operationId: list_worlds

Returns every published world split into the official settings authored by LoreKeeper and the 100 most recently published community settings.

Use to browse or recommend a LoreKeeper setting, or to answer what worlds a player can start a campaign in.

GET /api/worlds/community

operationId: list_community_worlds

Returns player-authored published worlds with a richer content breakdown (races, classes, factions, monsters, items, spells, locations) and a sort order.

Use when the question is specifically about community-made settings, or when the answer needs how much content a world actually contains.

sort — Ordering of the result set.

GET /api/badges

operationId: list_badges

Returns the achievement badges a player can earn. The `name` and `description` fields are i18n keys, not display text; the human-readable strings live in the localized bundles under /locales.

Use to explain what achievements exist in LoreKeeper and how rare each one is.

GET /api/roadmap

operationId: get_roadmap

Returns the public roadmap bucketed by delivery stage, with community vote counts per item.

Use to answer whether LoreKeeper supports a feature yet, or what is being built next.

GET /api/health

operationId: get_service_health

Reports whether the API and its database are serving. Answers 200 when healthy and 503 when the database is unreachable.

Use before a longer sequence of calls, or to check whether LoreKeeper is currently up.

Example request

curl -s "https://lore-keeper.com/api/leaderboard?limit=3&filter=arena&lang=en"

MCP server

The same operations are exposed as MCP tools over Streamable HTTP at /api/mcp. The server is stateless and read-only; no session id is issued and no tool can modify data. Add it to a client configuration:

{
  "mcpServers": {
    "lorekeeper": {
      "type": "http",
      "url": "https://lore-keeper.com/api/mcp"
    }
  }
}

Or speak JSON-RPC to it directly:

curl -s https://lore-keeper.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Errors

Every path under /api/ answers with JSON, including unmatched paths. Branch on code, never on message.

{
  "error": "No API endpoint matches GET /api/does-not-exist.",
  "code": "endpoint_not_found",
  "message": "No API endpoint matches GET /api/does-not-exist.",
  "hint": "Fetch https://lore-keeper.com/openapi.json for the list of public endpoints, or https://lore-keeper.com/mcp.json to call them as MCP tools.",
  "status": 404,
  "docs": "https://lore-keeper.com/developers"
}

Markdown representations

Landing URLs answer with a markdown representation when the request carries Accept: text/markdown, following the acceptmarkdown.com convention. URLs that exist as HTML but have no markdown twin answer 406 rather than 404, so an agent knows to re-request them as HTML.

Limits and support

There is no published rate limit on the public read endpoints; they are cached and cheap. Be reasonable, identify your client in the User-Agent, and check /api/health before a long sequence of calls.

Questions, or an endpoint you need that is not here: support@lore-keeper.com or the contact page.

Back to home