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

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

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

Command routes also require:

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

All services return the same error envelope:

```json
{
  "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](./unified-api.md)
- [Core API](./core-api.md)
- [Command API](./command-api.md)
- [Query API](./query-api.md)
- [Mobile gap analysis](./mobile-api-gap-analysis.md)