V2 Backend API Guide
This is the frontend-facing source of truth for the v2 backend.
1) Use one base URL
Frontend should call one public gateway:
API_V2_BASE_URL=https://krow-api-v2-933560802882.us-central1.run.app
Frontend should not call the internal core, command, or query Cloud Run services directly.
2) Current status
The unified v2 gateway is ready for frontend integration in dev.
What was validated live against the deployed stack:
- client sign-in
- staff auth bootstrap
- client dashboard, billing, coverage, hubs, vendors, managers, team members, orders, and reports
- client hub and order write flows
- client invoice approve and dispute
- staff dashboard, availability, payments, shifts, profile sections, documents, certificates, attire, bank accounts, benefits, and time card
- staff availability, profile, tax form, bank account, shift apply, shift accept, clock-in, clock-out, and swap request
- direct file upload helpers and verification job creation through the unified host
- client and staff sign-out
The live validation command is:
source ~/.nvm/nvm.sh
nvm use 23.5.0
node backend/unified-api/scripts/live-smoke-v2-unified.mjs
The demo tenant can be reset with:
source ~/.nvm/nvm.sh
nvm use 23.5.0
cd backend/command-api
npm run seed:v2-demo
3) Auth and headers
Protected routes require:
Authorization: Bearer <firebase-id-token>
Write routes also require:
Idempotency-Key: <unique-per-user-action>
For now:
- backend wraps sign-in and sign-out
- frontend can keep using Firebase token refresh on the client
- backend is the only thing frontend should call for session-oriented API flows
All routes return the same error envelope:
{
"code": "STRING_CODE",
"message": "Human readable message",
"details": {},
"requestId": "uuid"
}
4) Route model
Frontend sees one base URL and one route shape:
/auth/*/client/*/staff/*- direct upload aliases like
/upload-fileand/staff/profile/*
Internally, the gateway still forwards to:
| Frontend use case | Internal service |
|---|---|
| auth/session wrapper | krow-api-v2 |
| uploads, signed URLs, model calls, verification workflows | core-api-v2 |
| writes and workflow actions | command-api-v2 |
| reads and mobile read models | query-api-v2 |
5) Frontend integration rule
Use the unified routes first.
Do not build new frontend work on:
/query/tenants/*/commands/*/core/*
Those routes still exist for backend/internal compatibility, but mobile/frontend migration should target the unified surface documented in Unified API.