# 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:

```env
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:

```bash
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:

```bash
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:

```http
Authorization: Bearer <firebase-id-token>
```

Write routes also require:

```http
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:

```json
{
  "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-file` and `/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](./unified-api.md).

## 6) Docs

- [Unified API](./unified-api.md)
- [Core API](./core-api.md)
- [Command API](./command-api.md)
- [Query API](./query-api.md)
- [Mobile API Reconciliation](./mobile-api-gap-analysis.md)