API documentation

Authentication

No API key, account, or session. Every route is public and read-only. Send requests over HTTPS. The API describes this website. It cannot list, upload, decrypt, or restore photos from the Mavaul app.

Endpoints

GET /api/ai returns the page catalog and product facts as JSON. The operation id is getAiCatalog.

Optional query parameter category is a string, one of product, guides, blog, or legal. Omit it for the full catalog.

GET /openapi.json is the OpenAPI 3.0.3 specification: operation ids, typed parameters, and response schemas.

GET /api/health returns {"status":"ok"} when this API is serving.

GET /.well-known/api-catalog is the API catalog (RFC 9727). The response is application/linkset+json. It links /api/ai to the OpenAPI spec, these docs, and /api/health.

GET /llms.txt tells an agent when to use Mavaul and which page to open. Pages also answer Accept: text/markdown with Content-Type: text/markdown and Vary: Accept.

Example requests

curl -sS https://mavaul.com/api/ai

curl -sS "https://mavaul.com/api/ai?category=guides"

curl -sS https://mavaul.com/openapi.json

curl -sS -H "Accept: application/linkset+json" https://mavaul.com/.well-known/api-catalog

curl -sS -H "Accept: text/markdown" https://mavaul.com/

curl -sS -D - -o /dev/null -X POST https://mavaul.com/api/ai

Errors

Failed API calls return JSON, not an HTML page. Each body has error.code, error.message, and error.hint with the next step.

400 invalid_category — the category is not in the allowed list. Drop the parameter or use one of the four values.

404 not_found — no route matches that path. Read openapi.json.

405 method_not_allowed — retry with GET. The Allow header lists GET, HEAD, and OPTIONS.

503 ai_data_unavailable — retry shortly, or read llms.txt.

A missing website page is HTTP 404. Agents that send Accept: text/markdown get a Markdown explanation with links to these docs, the sitemap, and llms.txt.