Krow-workspace/docs/BACKEND/API_GUIDES/V2/query-api.md

V2 Query API

Use query-api-v2 for implemented read screens in the v2 clients.

Base URL:

https://krow-query-api-v2-e3g6witsvq-uc.a.run.app

1) Required header

Authorization: Bearer <firebase-id-token>

2) Route summary

Method	Route	Purpose
GET	/query/tenants/:tenantId/orders	Order list
GET	/query/tenants/:tenantId/orders/:orderId	Order detail with shifts and roles
GET	/query/tenants/:tenantId/businesses/:businessId/favorite-staff	Favorite staff list
GET	/query/tenants/:tenantId/staff/:staffId/review-summary	Staff rating summary and recent reviews
GET	/query/tenants/:tenantId/assignments/:assignmentId/attendance	Attendance session and event detail
GET	/readyz	Ready check

3) Order list

GET /query/tenants/:tenantId/orders

Optional query params:

• businessId
• status
• limit
• offset

Response shape:

{
  "items": [
    {
      "id": "uuid",
      "orderNumber": "ORD-1001",
      "title": "Cafe Event Staffing",
      "status": "OPEN",
      "serviceType": "EVENT",
      "startsAt": "2026-03-12T08:00:00.000Z",
      "endsAt": "2026-03-12T16:00:00.000Z",
      "businessId": "uuid",
      "businessName": "Google Mountain View Cafes",
      "vendorId": "uuid",
      "vendorName": "Legendary Staffing Pool A",
      "shiftCount": 1,
      "requiredWorkers": 2,
      "assignedWorkers": 1
    }
  ],
  "requestId": "uuid"
}

4) Order detail

GET /query/tenants/:tenantId/orders/:orderId

Response shape:

{
  "id": "uuid",
  "orderNumber": "ORD-1001",
  "title": "Cafe Event Staffing",
  "status": "OPEN",
  "businessId": "uuid",
  "businessName": "Google Mountain View Cafes",
  "vendorId": "uuid",
  "vendorName": "Legendary Staffing Pool A",
  "shifts": [
    {
      "id": "uuid",
      "shiftCode": "SHIFT-1",
      "title": "Morning Shift",
      "status": "OPEN",
      "startsAt": "2026-03-12T08:00:00.000Z",
      "endsAt": "2026-03-12T16:00:00.000Z",
      "requiredWorkers": 2,
      "assignedWorkers": 1,
      "roles": [
        {
          "id": "uuid",
          "roleCode": "BARISTA",
          "roleName": "Barista",
          "workersNeeded": 2,
          "assignedCount": 1
        }
      ]
    }
  ],
  "requestId": "uuid"
}

5) Favorite staff list

GET /query/tenants/:tenantId/businesses/:businessId/favorite-staff

Optional query params:

• limit
• offset

6) Staff review summary

GET /query/tenants/:tenantId/staff/:staffId/review-summary

Optional query params:

• limit

Response includes:

• staff identity
• average rating
• rating count
• recent reviews

7) Assignment attendance detail

GET /query/tenants/:tenantId/assignments/:assignmentId/attendance

Response includes:

• assignment status
• shift info
• attendance session
• ordered attendance events
• NFC and geofence validation fields

8) Current boundary

Frontend should use only these documented reads on query-api-v2.

Do not point dashboard, reports, finance, or other undocumented list/detail views here yet.