API Reference

Base URL: https://project--007723d4-f76c-4fb3-a6ba-8514a43c08c1.lovable.app/api/public

Authentication

Every request sends an API key as x-api-key: ann_live_…. Issue keys in the Admin panel.

Endpoints

• POST /assess — start an assessment run.
• GET /runs/:id — poll run status and result.
• GET /neighbourhoods — list registered neighbourhoods.

Modes

The mode field on POST /assess selects the pipeline:

• neb_context — NEB pillar scores only (Beautiful / Sustainable / Together).
• placemaking_zones — ranked placemaking zones with sub-scores.
• full_assessment — composite + NEB + placemaking + recommendations.

Response Shapes

neb_context

{
  "methodology_version": "JRC139118",
  "neb": {
    "beautiful":   { "score": 72, "level": "established", "evidence": [{ "source": "...", "url": "..." }] },
    "sustainable": { "score": 58, "level": "emerging",    "evidence": [...] },
    "together":    { "score": 81, "level": "exemplary",   "evidence": [...] }
  }
}

placemaking_zones

{
  "methodology_version": "PPS-EU-v1",
  "zones": [
    {
      "name": "Travemünde Strandpromenade",
      "score": 84,
      "sub_scores": { "sociability": 88, "uses": 82, "access": 79, "comfort": 86, "identity": 85 },
      "opportunity_brief": "High footfall, weak winter activation; …"
    }
  ]
}

Rate Limits

Default 100 req/min per key. Burst up to 200. Configurable per key by admins.

Error Codes

• 401 — invalid or missing API key.
• 422 — body fails validation; response lists the failing fields.
• 429 — rate limited; Retry-After header in seconds.
• 404 — unknown neighbourhood. We never return fabricated data.