Public API

Versioned under /api/v1. Authenticate with Authorization: Bearer <key>. Rate limit: 60 requests per minute per key. OpenAPI: /openapi.json.

POST/api/v1/analyze

Categorize transactions, estimate CO₂, and compare to peer cohorts. Stateless — nothing is stored.

Required scope: analyze (or *)

curl -X POST https://your-host/api/v1/analyze \
  -H "Authorization: Bearer ocs_…" \
  -H "Content-Type: application/json" \
  -d '{  "transactions": [    { "date": "2026-07-15", "amountEur": 42.5, "description": "Albert Heijn Delft" },    { "date": "2026-07-16", "amountEur": 28.0, "description": "Shell tankstation" }  ],  "profile": {    "ageBand": "25-34",    "profession": "IT_TECH",    "region": "Zuid-Holland"  }}'

GET/api/v1/categories

List spending categories with EEIO CO₂ factors (grams per euro).

Required scope: categories (or *)

curl https://your-host/api/v1/categories \
  -H "Authorization: Bearer ocs_…"

GET/api/v1/partners?region=Zuid-Holland&category=energy

List active partners (public fields). Optional region and category slug filters.

Required scope: partners (or *)

curl https://your-host/api/v1/partners?region=Zuid-Holland&category=energy \
  -H "Authorization: Bearer ocs_…"

Keys are issued by Opticosts admins at /admin/api-keys. Partner keys may be scoped to a marketplace partner; blank partner = internal.