Using the API

Rezepte's frontend talks to the same HTTP API documented here — there is nothing it can do that the API cannot.

Base URL and format

Every endpoint lives under /api/v1 of your instance (e.g. http://localhost:8060/api/v1). Requests and responses are JSON, with camelCase field names.

The API is versioned with Rezepte itself: info.version in /api/v1/openapi.json is the Rezepte version the instance runs, the same number /healthz reports, and a release's changelog page says what changed in the API.

Authentication

Two credentials work. An API token is what programs should use — see API tokens:

curl -H "Authorization: Bearer rzp_..." 'http://localhost:8060/api/v1/recipes?limit=5'

The session cookie is what the browser uses, and it works from a script too:

curl -c cookies.txt -H 'Content-Type: application/json' \
  -d '{"username":"demo","password":"demo1234"}' \
  http://localhost:8060/api/v1/auth/login

curl -b cookies.txt 'http://localhost:8060/api/v1/recipes?limit=5'

POST, PUT, PATCH and DELETE requests additionally require an Origin header that matches the instance's host — this is what a browser sends automatically, and what a reverse proxy must forward unchanged (see Reverse proxy). A request with no Origin header at all, such as the curl calls above, is not affected.

Errors

Errors are application/problem+json:

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "errors": [{ "location": "body.title", "message": "expected length >= 1" }]
}

Interactive docs

A running instance serves interactive, try-it-out documentation (Scalar) at /api/v1/docs. The way in from the app is "Settings" → "API", which every signed-in member can open: it names this instance's base URL, what it serves, and links to both the interactive documentation and the raw document. See Settings.

Reference

Coming later

Instance sync is planned but not part of the current API — see Roadmap. An MCP server already exists — see Connect an AI assistant.