0pt/docs/04-api.md

04 · API contract (FastAPI)

Canonical REST contract. Reconcile the existing 25+ endpoints in src/orchestrator/main.py toward this. JSON in/out, snake_case. All amounts in öre. Auth: Next.js → FastAPI over a shared internal token (X-Internal-Token); customer identity passed as org_id/user_id resolved from the Auth.js session server-side.

Conventions

• Errors: { "error": { "code", "message" } }, proper HTTP status. Interface-voice messages (Swedish) are produced in the frontend, not here.
• Idempotency: accept Idempotency-Key on POSTs that create orders/payments.
• Pagination: ?limit=&cursor=.

Catalog

GET  /catalog                      -> [{id,title,markets,entity_type,count,updated,price_ore,confidence}]
GET  /catalog/{id}                 -> full dataset (overview, coverage, schema, quality summary)
GET  /catalog/{id}/sample?n=10     -> sample rows WITH per-field provenance

Estimate (configurator → price/time/confidence)

POST /estimates
  body: { flow, markets[], entity_type, fields[], enrichment[], volume, frequency, confidence_target, formats[] }
  -> { total_ore, deposit_ore, balance_ore, est_days, est_confidence, breakdown[] }

AI-assist (NL → config)

POST /ai/parse
  body: { text }                   -- "5000 svenska SaaS-bolag med e-post och omsättning"
  -> { config: <estimate body>, rationale }   -- prefilled configurator; uses pgvector match to catalog/fields

Orders (lifecycle)

POST /orders                       body: { flow, config }            -> { order_id, status:'draft'|'quoted' }
GET  /orders                       -> [orders for org]
GET  /orders/{id}                  -> order + current job + delivery (if any)
POST /orders/{id}/scope            (custom flow) body:{ notes }      -> status:'quoted' (manual quote step)
POST /orders/{id}/accept           customer approves delivery        -> triggers balance release; status:'accepted'
POST /orders/{id}/revise           body:{ notes }                    -> status:'revision'; escrow untouched

Payments (50/50 escrow)

POST /payments/{order_id}/deposit  -> { checkout_url }   (Stripe Checkout for 50%; on success → IN_PRODUCTION)
POST /payments/{order_id}/release  -> captures/charges the held balance (called on accept)
POST /webhooks/stripe              (Stripe → here) verify signature; update payments + order status

Implement balance as either a manual capture on a held PaymentIntent, or a second Checkout/invoice keyed to order_id. Never charge balance before accept.

Jobs / live status

GET  /orders/{id}/status           -> { stage, pct, per_market[], confidence, eta, rows }
GET  /orders/{id}/events           -> Server-Sent Events stream (preferred for the production tracker)

Uploads (R2 presigned)

POST /uploads                      body:{ order_id, name, mime, bytes } -> { file_id, put_url }  (client PUTs to R2)
GET  /orders/{id}/files            -> [files]

Customer DB access (read-only grant)

POST /connections/db-grant
  body: { order_id, conn_string, scope, expires_at }   -- stored ENCRYPTED; validated read-only
  -> { grant_id, status:'pending'|'verified' }
DELETE /connections/db-grant/{id}  -> revoke

Deliveries

GET  /orders/{id}/delivery         -> { formats, destinations, record_count, avg_confidence, quality_report, files[], provenance_export_url }
POST /orders/{id}/delivery/destinations  body:{ destinations[] }    -> updates targets (CSV/Parquet/JSON/API/NocoDB/Metabase/FiveCRM/Sheets/webhook)

Sources (the transparency moat)

GET  /sources                      -> [{source_id,name,market,access,licence,cadence,confidence}]
GET  /sources/{market}             -> sources + freshness for a market

Subscriptions / feeds

POST /subscriptions                body:{ order_id, cadence, webhook_url } -> { sub_id }
GET  /subscriptions                -> [subs]
POST /subscriptions/{id}/pause | /resume

Webhooks out (to customers)

• On delivery / feed update: POST to subscriptions.webhook_url with { order_id, delta_url, summary }.

Health

GET  /health                       -> { ok, db, workers, queue }

Existing-code reconciliation

Map current endpoints (orders, estimates, ai-assistent, catalog, webhooks, health) onto the names above; rename for consistency, keep behavior. Add: /orders/{id}/events (SSE), /payments/* escrow split, /connections/db-grant, /sources, /subscriptions. Remove any endpoint that drives a bypass/stealth fetch path.