HXP Actions and Status Changes

For third-party server access, use the separate organization API-key contract. Its read projections and allowed commands are narrower than the operator API documented below. Do not substitute its bearer key into these operator URLs.

Read the work before changing itCopy Anchor Link

The operator endpoint GET /api/v1/orgs/{orgId}/messaging?scope={scopeId}&view=actions returns { "data": { "items": [...], "nextCursor": null } }. A guest's view=thread&guest={guestId} response also includes Actions.

Use returned IDs and versions. Guest names and owner labels are display context, not stable identity or authority. Where a task concerns a benefit, booking, payment, or delivery, consult the authoritative domain record as well; the Action is the coordination record.

Commands, not arbitrary status patchesCopy Anchor Link

Current Action states are suggestion, waiting_for_teammate, working, complete, and canceled. The public-facing work labels used for AI tasks and deliveries include additional states; do not use that larger vocabulary as valid Action transitions.

Every suffix is under /api/v1/orgs/{orgId}. These commands require POST, JSON, the HXP session, and Idempotency-Key. There is no generic PATCH { "status": "done" } operation, and no reopen command for a completed or canceled Action.

CreateCopy Anchor Link

{
  "type": "action",
  "guestId": "guest-example",
  "stayId": null,
  "audience": { "type": "team", "teamId": "team-example" },
  "sourceMessageId": null,
  "title": "Prepare the quiet room before arrival",
  "teamId": "team-example",
  "dueAt": "2026-09-20T18:00:00.000Z"
}

ClaimCopy Anchor Link

{
  "type": "claim",
  "id": "hxp-action:example",
  "expectedVersion": 1
}

Complete with evidenceCopy Anchor Link

Fetch the latest Action after claiming. The following version is illustrative:

{
  "type": "finish",
  "id": "hxp-action:example",
  "expectedVersion": 2,
  "evidence": "Room preparation checked and completed by the assigned operator."
}

evidence must contain 8–2,000 characters after trimming. The server records the authenticated owner; there is no client-supplied completedBy override.

Hand offCopy Anchor Link

Send to /collaboration, not /messaging. dueAt is required but may be null; use the existing due time to retain it.

{
  "type": "handoff",
  "actionId": "hxp-action:example",
  "expectedVersion": 2,
  "ownerId": "user-next-owner",
  "dueAt": "2026-09-20T18:00:00.000Z"
}

CancelCopy Anchor Link

{
  "type": "cancel_action",
  "id": "hxp-action:example",
  "expectedVersion": 2
}

These are alternative examples, not a sequence to run against the same version.

Receipts, retries, and errorsCopy Anchor Link

Messaging commands return HTTP 200 with:

{
  "result": {
    "id": "hxp-action:example",
    "kind": "action",
    "receiptId": "receipt-example"
  }
}

The collaboration runtime's handoff response uses the same shape with kind: "runtime" and the Action ID. Neither response contains the updated Action; reread its authorized snapshot for the new state and version.

• Use one stable operation key per intended command: 8–180 letters, digits, underscores, colons, or hyphens (a UUID is suitable).
• After an ambiguous network result, repeat the same key and identical input as the same actor in the same organization/scope. Do not generate a new key merely because a response was lost.
• Reusing a key for changed content produces 409. A stale expectedVersion or invalid current state also produces 409; reread and review before issuing a new command with a new key.
• Reads need hxp:guests:read; these writes also need hxp:organizations:manage. Current access is checked even for retries.
• Invalid requests normally return 400; unauthenticated requests 401; cross-origin checks may return 403; unavailable or unauthorized collaboration records may return 404. Do not interpret a 404 as proof a record never existed.

Operator errors have an error object with code, message, requestId, and retryable; responses also include X-Request-ID. Use the request ID for support and avoid logging guest message bodies or credentials.

Completion is not provider fulfillmentCopy Anchor Link

An HXP completion receipt proves the HXP command was recorded. It does not redeem a benefit, move funds, change a reservation, or establish guest delivery. Those operations use their own authorized services and evidence. submitted_to_provider, delivery_confirmed, and reconciling belong to delivery/execution workflows, not this Action state machine.

For a third-party system that must perform these transitions, see the explicit external integration gap. Enabling MCP alone will not add Action status-write tools.