Krow-workspace/docs/BACKEND/API_GUIDES/V2

V2 Backend API Guide

This is the frontend-facing source of truth for the v2 backend.

1) Frontend entrypoint

Frontend should target one public base URL:

API_V2_BASE_URL=<krow-api-v2-url>

The unified v2 gateway exposes:

• /auth/*
• /core/*
• /commands/*
• /query/*
• /query/client/*
• /query/staff/*

Internal services still stay separate behind that gateway.

2) Internal service split

Use case	Internal service
File upload, signed URLs, model calls, verification helpers	core-api-v2
Business writes and workflow actions	command-api-v2
Screen reads and mobile read models	query-api-v2
Frontend-facing single host and auth wrappers	krow-api-v2

3) Auth and headers

Protected routes require:

Authorization: Bearer <firebase-id-token>

Command routes also require:

Idempotency-Key: <unique-per-user-action>

All services return the same error envelope:

{
  "code": "STRING_CODE",
  "message": "Human readable message",
  "details": {},
  "requestId": "uuid"
}

4) What frontend can use now on this branch

Unified gateway

• POST /auth/client/sign-in
• POST /auth/client/sign-up
• POST /auth/sign-out
• POST /auth/client/sign-out
• POST /auth/staff/sign-out
• GET /auth/session
• Proxy access to /core/*, /commands/*, /query/*

Client read routes

• GET /query/client/session
• GET /query/client/dashboard
• GET /query/client/reorders
• GET /query/client/billing/accounts
• GET /query/client/billing/invoices/pending
• GET /query/client/billing/invoices/history
• GET /query/client/billing/current-bill
• GET /query/client/billing/savings
• GET /query/client/billing/spend-breakdown
• GET /query/client/coverage
• GET /query/client/coverage/stats
• GET /query/client/hubs
• GET /query/client/cost-centers
• GET /query/client/vendors
• GET /query/client/vendors/:vendorId/roles
• GET /query/client/hubs/:hubId/managers
• GET /query/client/orders/view

Staff read routes

• GET /query/staff/session
• GET /query/staff/dashboard
• GET /query/staff/profile-completion
• GET /query/staff/availability
• GET /query/staff/clock-in/shifts/today
• GET /query/staff/clock-in/status
• GET /query/staff/payments/summary
• GET /query/staff/payments/history
• GET /query/staff/payments/chart
• GET /query/staff/shifts/assigned
• GET /query/staff/shifts/open
• GET /query/staff/shifts/pending
• GET /query/staff/shifts/cancelled
• GET /query/staff/shifts/completed
• GET /query/staff/shifts/:shiftId
• GET /query/staff/profile/sections
• GET /query/staff/profile/personal-info
• GET /query/staff/profile/industries
• GET /query/staff/profile/skills
• GET /query/staff/profile/documents
• GET /query/staff/profile/certificates
• GET /query/staff/profile/bank-accounts
• GET /query/staff/profile/benefits

Existing v2 routes still valid

• /core/* routes documented in core-api.md
• /commands/* routes documented in command-api.md
• /query/tenants/* routes documented in query-api.md

5) Remaining gaps after this slice

Still not implemented yet:

• staff phone OTP wrapper endpoints
• hub write flows
• hub NFC assignment write route
• invoice approve and dispute commands
• staff apply / decline / request swap commands
• staff profile update commands
• availability write commands
• reports suite
• durable verification persistence in core-api-v2

6) Docs

• Unified API
• Core API
• Command API
• Query API
• Mobile gap analysis