Locals BI — Agent API

Quickstart

Zet je token hieronder — alle voorbeelden op deze pagina vullen 'm dan automatisch in. Het token blijft in je browser en wordt nergens heen gestuurd.

# Draait de API en is je token geldig?
curl -s https://locals-dashboard-omega.vercel.app/api/v1/health

# Omzet per dag, afgelopen week
curl -s -H "Authorization: Bearer $LOCALS_TOKEN" \
  "https://locals-dashboard-omega.vercel.app/api/v1/revenue/daily?start=2026-07-01&end=2026-07-07"

# Winst per locatie over juni — dé endpoint voor winstvragen
curl -s -H "Authorization: Bearer $LOCALS_TOKEN" \
  "https://locals-dashboard-omega.vercel.app/api/v1/financials/pnl?start=2026-06-01&end=2026-06-30"

Authenticatie & scopes

Elk endpoint verwacht Authorization: Bearer <token>. Alleen /health en /openapi.json zijn publiek — die geven geen bedrijfsdata prijs.

Tokens beheren

Tokens staan in de Vercel-omgevingsvariabele AGENT_API_TOKENS, als JSON-array. Een token intrekken = die regel weghalen en opnieuw deployen.

[
  {"token": "lba_…", "name": "hermes", "scopes": ["read", "write"]},
  {"token": "lba_…", "name": "viewer", "scopes": ["read"]}
]

Foutformaat

{"error": {"code": "forbidden",
           "message": "Dit token heeft de scope 'write' niet (heeft: read)."}}

Hermes koppelen

De API praat ook MCP, dus Hermes ontdekt alle endpoints als tools — één commando, geen losse skill nodig.

hermes mcp add locals \
  --url https://locals-dashboard-omega.vercel.app/api/v1/mcp \
  --auth header

# Vul bij de prompt in:  Authorization: Bearer <jouw token>

hermes mcp test locals          # moet alle tools ontdekken
hermes tools list | grep locals # locals_kpis, locals_financials_pnl, …

De tools heten locals_<operatie> — dezelfde namen als de operationId's hieronder. Een token zonder write-scope krijgt de schrijftools niet eens te zien.

Conventies

Alle endpoints

Gegenereerd uit de live OpenAPI-spec, dus altijd gelijk aan wat de API werkelijk doet.

Vrije query

Voor alles waar geen eigen endpoint voor is. Alleen lezen, alleen tabellen uit de allowlist, maximaal 5000 rijen.

curl -s -X POST -H "Authorization: Bearer $LOCALS_TOKEN" \
  -H "Content-Type: application/json" \
  https://locals-dashboard-omega.vercel.app/api/v1/query \
  -d '{
    "table": "lightspeed_products_daily",
    "select": "date,product_name,qty,net_revenue",
    "filters": {"date": {"gte": "2026-07-01"},
                "location_id": {"eq": "locals-coffee"}},
    "order": "net_revenue.desc",
    "limit": 25
  }'

Toegestane operatoren: eq, neq, gt, gte, lt, lte, like, ilike, in, is, cs, cd. De volledige tabel-allowlist staat in de OpenAPI-spec bij query.

MCP-protocol

Voor wie zelf een client bouwt: POST /api/v1/mcp spreekt JSON-RPC 2.0 over HTTP, protocolversie 2025-06-18.

curl -s -X POST -H "Authorization: Bearer $LOCALS_TOKEN" \
  -H "Content-Type: application/json" \
  https://locals-dashboard-omega.vercel.app/api/v1/mcp \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Ondersteund: initialize, tools/list, tools/call, ping. Argumenten van tools/call zijn één plat object — query-, pad- en bodyvelden door elkaar; de server sorteert dat zelf uit.

Databronnen & versheid

Handig om te weten hoe actueel een antwoord kan zijn. GET /api/v1/data-quality geeft de werkelijke versheid per bron.

Valkuilen

Vier dingen waar een agent anders de mist in gaat.