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:

Authorization: Bearer <firebase-id-token>

All 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

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

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

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.

2.9 KiB Raw Blame History