# V2 Backend API Guide

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

If you are building against the new backend, start here.

## 1) Which service to use

| Use case | Service |
| --- | --- |
| File upload, signed URLs, model calls, rapid order helpers, verification flows | `core-api-v2` |
| Business writes and workflow actions | `command-api-v2` |
| Screen reads for the implemented v2 views | `query-api-v2` |

## 2) Live dev base URLs

- Core API: `https://krow-core-api-v2-e3g6witsvq-uc.a.run.app`
- Command API: `https://krow-command-api-v2-e3g6witsvq-uc.a.run.app`
- Query API: `https://krow-query-api-v2-e3g6witsvq-uc.a.run.app`

## 3) Auth and headers

All protected routes require:

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

All 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

### Ready now

- `core-api-v2`
  - upload file
  - create signed URL
  - invoke model
  - rapid order transcribe
  - rapid order parse
  - create verification
  - get verification
  - review verification
  - retry verification
- `command-api-v2`
  - create order
  - update order
  - cancel order
  - assign staff to shift
  - accept shift
  - change shift status
  - clock in
  - clock out
  - favorite and unfavorite staff
  - create staff review
- `query-api-v2`
  - order list
  - order detail
  - favorite staff list
  - staff review summary
  - assignment attendance detail

### Do not move yet

- reports
- payments and finance screens
- undocumented dashboard reads
- undocumented scheduling reads and writes
- any flow that assumes verification history is durable in SQL

## 5) Important caveat

`core-api-v2` is usable now, but verification job state is not yet persisted to `krow-sql-v2`.

What is durable today:
- uploaded files in Google Cloud Storage
- generated signed URLs
- model invocation itself

What is not yet durable:
- verification job history
- verification review history
- verification event history

That means frontend can integrate with verification routes now, but should not treat them as mission-critical durable state yet.

## 6) Recommended frontend environment variables

```env
CORE_API_V2_BASE_URL=https://krow-core-api-v2-e3g6witsvq-uc.a.run.app
COMMAND_API_V2_BASE_URL=https://krow-command-api-v2-e3g6witsvq-uc.a.run.app
QUERY_API_V2_BASE_URL=https://krow-query-api-v2-e3g6witsvq-uc.a.run.app
```

## 7) Service docs

- [Core API](./core-api.md)
- [Command API](./command-api.md)
- [Query API](./query-api.md)

## 8) Frontend integration rule

Do not point screens directly at database access just because a route does not exist yet.

If a screen is missing from the docs, the next step is to define the route contract and add it to `query-api-v2` or `command-api-v2`.