Getting started

Prerequisites

./localenv up broker-api

API: localhost:8125
Swagger UI: localhost:8125/api-docs
Database: postgres://postgres:postgres@localhost:5433/broker

Locally DEV_AUTH=1 trusts X-Dev-Principal as the caller. The service refuses to start with that flag when APP_ENV is not local. The first request creates the person, a staff principal, and — if the email is in BROKER_PLATFORM_ADMINS — a platform-admin role. The default in services/broker/process-compose.yaml is [email protected].

Relay needs a provider key. Name the keys from services/broker/.env.example only; put real values in services/broker/.env, which ./localenv exports. A missing key leaves that provider listed with available=false.

Read the catalog

curl -s localhost:8125/v1/catalog \
  -H "X-Dev-Principal: [email protected]" | jq

Every seeded Anthropic, OpenAI, xAI, and OpenRouter model is listed, with the current price row when one exists.

Report a call

curl -s -X POST localhost:8125/v1/usage \
  -H "X-Dev-Principal: [email protected]" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
        "data": {
          "provider_kind": "anthropic",
          "model": "claude-sonnet-4-8",
          "request_kind": "messages",
          "input_tokens": 1200,
          "output_tokens": 400,
          "cache_read_tokens": 800
        }
      }' | jq

The response is the stored row: tokens, cost_micros, and cache_savings_micros. A model with no price still records tokens; cost is null.

Repeat the POST with the same Idempotency-Key and no second row is created.

Read usage

curl -s 'localhost:8125/v1/usage/summary' \
  -H "X-Dev-Principal: [email protected]" | jq

curl -s 'localhost:8125/v1/usage?pagination[page]=1&pagination[pageSize]=25' \
  -H "X-Dev-Principal: [email protected]" | jq

GET /v1/usage is page mode (ADR 0014). Filters: from, to, actor, provider, model. group defaults to day (one row per day, person, provider, and model). person_model, person, model, and provider sum those daily rows across the date range.

Screens

The intelligence app Broker workspace is the UI:

./localenv up intelligence-app

Then localhost:3503 → Broker. Usage, Cost optimization, and Budgets call this service. BROKER_SERVICE_URL defaults to http://localhost:8125. The app does not wait on broker-api health, so the pages load even when this service is down.

Generate OpenAPI

go run ./services/broker/cmd/api -openapi > /tmp/broker-openapi.yaml

The checked-in spec is services/broker/openapi.yaml.