For developers

Elpia is one core that many apps talk to: a website, a Minecraft mod, a server plugin, a focus app, and whatever comes next. Everything they use is documented here, and everything public is readable without an account.

What you can talk to

  • REST API

    JSON over HTTPS, versioned under /v1. The same paths from the website, from a device and from a script.

    Read the reference

  • OpenAPI document

    The same endpoints as a machine-readable file, for generating a client or importing into an HTTP tool.

    openapi.json

  • llms.txt

    A short overview for AI agents, in the format they look for first.

    llms.txt

How you identify yourself

Every endpoint states which of these it needs. A device never gets a login session: its key may report activities and nothing else.

Open (21)
No login. Rules, budget, catalog, Deeds, receipts and statistics are public, because transparency is the point.
Person (18)
The session cookie of the website, or an Authorization header with the session token for callers without cookies. Signing in returns that token in the set-auth-token header.
App or device (3)
An Authorization header with the API key of a device you approved. With an Ed25519 signature the reported activity counts as verified instead of merely from a device.
Owner (20)
A signed-in person with the admin role. Everything that changes rules, prices or money lives here.

House rules

  • Errors look the same everywhere

    An error carries an error code and a message; a failed validation adds the issues. Unexpected errors only carry a request id, and the details stay in our log rather than in your response.

  • Every request has an id

    Send X-Request-Id and it is used and echoed; otherwise you get one. Quote it when something went wrong and it can be found in the log.

  • Limits are per account, not per address

    One address can be a whole household, one account can be many addresses. Over the limit you get 429 with Retry-After; the answer never says which account it was.

  • Repeating a request is safe

    An activity with the same externalId is stored once. Retry after a timeout instead of guessing whether it arrived.

  • Nothing is rewritten

    Rules, prices, postings, payouts and reviews are append-only. A correction is a new entry that says what changed and why.

  • Locations stay coarse

    Activities carry at most a country or electricity zone. There is no endpoint that returns anything finer, because there is nothing finer to return.

Planned

  • MCP server

    A thin layer over the same REST endpoints, so an AI agent can look up the catalog, read Deeds and check statistics. It comes after the public API is stable and keys can carry scopes: an agent should be able to read without holding a key that may also spend Drops.

  • Webhooks

    A signed call to your side when a redemption becomes a Deed, instead of asking us again and again.

  • Sign in with Elpia

    Elpia as an OIDC provider, so a connected app does not have to keep its own passwords.

Read the reference