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

V2 Command API

Use command-api-v2 for write actions that change business state.

Base URL:

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

1) Required headers

Authorization: Bearer <firebase-id-token>
Idempotency-Key: <unique-per-user-action>
Content-Type: application/json

2) Route summary

Method	Route	Purpose
POST	/commands/orders/create	Create order with shifts and roles
POST	/commands/orders/:orderId/update	Update mutable order fields
POST	/commands/orders/:orderId/cancel	Cancel order and related eligible records
POST	/commands/shifts/:shiftId/assign-staff	Assign workforce to shift role
POST	/commands/shifts/:shiftId/accept	Accept an assigned shift
POST	/commands/shifts/:shiftId/change-status	Move shift to a new valid status
POST	/commands/attendance/clock-in	Record clock-in event
POST	/commands/attendance/clock-out	Record clock-out event
POST	/commands/businesses/:businessId/favorite-staff	Add favorite staff
DELETE	/commands/businesses/:businessId/favorite-staff/:staffId	Remove favorite staff
POST	/commands/assignments/:assignmentId/reviews	Create or update staff review
GET	/readyz	Ready check

3) Order create

POST /commands/orders/create

Request body:

{
  "tenantId": "uuid",
  "businessId": "uuid",
  "vendorId": "uuid",
  "orderNumber": "ORD-1001",
  "title": "Cafe Event Staffing",
  "serviceType": "EVENT",
  "shifts": [
    {
      "shiftCode": "SHIFT-1",
      "title": "Morning Shift",
      "startsAt": "2026-03-12T08:00:00.000Z",
      "endsAt": "2026-03-12T16:00:00.000Z",
      "requiredWorkers": 2,
      "roles": [
        {
          "roleCode": "BARISTA",
          "roleName": "Barista",
          "workersNeeded": 2
        }
      ]
    }
  ]
}

4) Order update

POST /commands/orders/:orderId/update

Required body fields:

• tenantId
• at least one mutable field such as title, description, vendorId, serviceType, startsAt, endsAt, locationName, locationAddress, latitude, longitude, notes, metadata

You can also send null to clear nullable fields.

5) Order cancel

POST /commands/orders/:orderId/cancel

Example request:

{
  "tenantId": "uuid",
  "reason": "Client cancelled"
}

6) Shift assign staff

POST /commands/shifts/:shiftId/assign-staff

Example request:

{
  "tenantId": "uuid",
  "shiftRoleId": "uuid",
  "workforceId": "uuid",
  "applicationId": "uuid"
}

7) Shift accept

POST /commands/shifts/:shiftId/accept

Example request:

{
  "shiftRoleId": "uuid",
  "workforceId": "uuid"
}

8) Shift status change

POST /commands/shifts/:shiftId/change-status

Example request:

{
  "tenantId": "uuid",
  "status": "PENDING_CONFIRMATION",
  "reason": "Waiting for worker confirmation"
}

Allowed status values:

• DRAFT
• OPEN
• PENDING_CONFIRMATION
• ASSIGNED
• ACTIVE
• COMPLETED
• CANCELLED

9) Attendance

Clock in

POST /commands/attendance/clock-in

Clock out

POST /commands/attendance/clock-out

Example request body for both:

{
  "assignmentId": "uuid",
  "sourceType": "NFC",
  "sourceReference": "iphone-15-pro-max",
  "nfcTagUid": "NFC-DEMO-ANA-001",
  "deviceId": "device-123",
  "latitude": 37.422,
  "longitude": -122.084,
  "accuracyMeters": 8,
  "capturedAt": "2026-03-11T17:15:00.000Z"
}

10) Favorite staff

Add favorite

POST /commands/businesses/:businessId/favorite-staff

Remove favorite

DELETE /commands/businesses/:businessId/favorite-staff/:staffId

Request body when adding:

{
  "tenantId": "uuid",
  "staffId": "uuid"
}

11) Staff review

POST /commands/assignments/:assignmentId/reviews

Example request:

{
  "tenantId": "uuid",
  "businessId": "uuid",
  "staffId": "uuid",
  "rating": 5,
  "reviewText": "Strong shift performance",
  "tags": ["punctual", "professional"]
}

12) Live status

These routes were live-tested on 2026-03-11 against the deployed dev service and krow-sql-v2.