Update civic complaints

Mutation contract

• PATCH /api/v1/complaints/{complaintReference} requires complaints:write.
• An assignment field additionally requires complaints:assign; the key must carry both scopes.
• Send a UUID Idempotency-Key header and a positive expectedVersion body field.
• The body can set status, assignment with nullable teamId and userId, or nullable leadStatusId. At least one mutation is required and unknown fields are rejected.

Version and replay

• A stale expectedVersion returns 409 so the caller can reload before changing newer work.
• An exact retry with the same operation ID and canonical request returns the retained result with replayed true.
• Reusing an operation ID for changed input returns 409 and never silently applies the different request.
• After a timeout, reconcile current complaint state before choosing between exact replay and a new operation.

Lifecycle and authority

• Only allowed lifecycle transitions succeed; an invalid current-state transition returns 422.
• Team, assignee, and lead-status references are validated inside the trusted account boundary.
• Key expiry, account state, plan access, and exact scopes are locked and rechecked at operation time.
• Assignment does not broaden the key or reveal member data from another account.

Update example

curl -X PATCH "/api/v1/complaints/CMP-2026-0123456789ABCDEF"   -H "Authorization: Bearer tus_live_your_key_here"   -H "Idempotency-Key: 00000000-0000-4000-8000-000000000001"   -H "Content-Type: application/json"   -d '{"expectedVersion":1,"status":"acknowledged"}'