Skip to main content

Transition a single flag to a new status

PUT 
/flags/:id/update-status/:status

Transitions the specified flag to the given target status. Use this endpoint to move one flag through its lifecycle (e.g. acknowledging it, starting outreach, closing it); to move multiple flags in one call, use PUT /flags/update-status-bulk/{status} instead. The caller must hold the per-transition permission for the specific source-to-target status pair (see the flag status-transition rules); closed flags are terminal and cannot be transitioned further. The status path parameter accepts any of the canonical wire values (open, seen, outreachInProgress, sentToCommittee, closed, needsVerification) or the aliases markAsSeen/mark_as_seen, needs_verification, outreach_in_progress, and sent_to_committee — matching is case-insensitive, so any casing of any of these values is accepted. The request body is optional: supply a free-text comment and/or one or more files to attach context to the transition, or omit the body entirely. Returns the full updated flag record on success. A FlagHistory record is always created, and if files were supplied they are stored to GCS and linked as FlagHistoryAttachment records — both are best-effort and do not fail the call if they error. Not idempotent: since no status has a transition to itself, repeating the same call a second time (the flag now already at the target status) returns 409.

Request​

Responses​

The updated flag record, reflecting the new status. The internal tenantProviderId and hash columns are omitted. When the target status is seen, markedSeenAt/markedSeenBy are populated from the transition's FlagHistory record (null if its best-effort creation failed); everything else in the referenced schema is returned verbatim.