API reference

Overview#

Every endpoint takes a POST with a JSON body and answers JSON, at https://orvain.dev. There is no API key. Purchases are tied to an email address and proven with the Stripe Checkout Session id that Stripe hands back after payment.

$ curl -X POST https://orvain.dev/api/subscribe \
$   -H 'Content-Type: application/json' \
$   -d '{"email":"you@example.com"}'

Machine-readable files#

The API is described in OpenAPI 3.1 at /openapi.json, with an operationId, a description and typed schemas on every operation, so it can be loaded straight into a function-calling agent. /.well-known/api-catalog points at it in the RFC 9727 format. For reading the site rather than calling it, /llms.txt summarises every page, and the home page answers in Markdown to a request sent with Accept: text/markdown.

Endpoints#

Errors#

Every error, at every status, is JSON in one shape. error is a sentence a person can read, code is stable and safe to branch on, and hint, when present, says how to fix the request. An unknown path under /api answers 404 not_found, and a verb an endpoint does not take answers 405 method_not_allowed with an Allow header.

{
  "error": "That email address doesn't look right.",
  "code": "invalid_email",
  "status": 400,
  "hint": "Send a JSON body like {\"email\":\"you@example.com\"}.",
  "docs": "https://orvain.dev/docs/api#errors"
}