Update Case State Safely

Overview

Use the external case PATCH endpoint to update case state after a review, correction, or operator action. The endpoint uses optimistic locking so concurrent edits do not silently overwrite each other.

Use this endpoint when an API client needs to correct extracted data, mark a review decision, store an operator note, or request reprocessing after a manual change.

Questions This Article Answers

• How do API clients update case state?
• What is an update mask?
• How does optimistic locking work?
• When should reprocess be set to true?
• How should clients handle version conflicts?

Endpoint

PATCH /api/v1/cases/{case_id}?usecase_id={usecase_id}

Request Body

{
  "update_mask": ["state.review.required", "state.review.reason"],
  "case": {
    "version": 7,
    "state": {
      "review": {
        "required": true,
        "reason": "Missing invoice total"
      }
    }
  }
}

The update_mask must contain one or more dot-separated field paths. Each path must start with state..

The case.version value must match the current case version. If another update has already changed the case, the request returns a version conflict.

Request Fields

Reprocess After an Edit

Set reprocess to true when the manual edit should cause the agent to run again.

{
  "update_mask": ["state.invoice.total_amount"],
  "case": {
    "version": 7,
    "state": {
      "invoice": {
        "total_amount": 1250.75
      }
    }
  },
  "reprocess": true,
  "user_comment": "Corrected the total amount from the PDF."
}

Use user_comment to provide context for the reprocessing run.

Use reprocessing when:

• A corrected field should change a classification, validation result, routing decision, or generated output.
• A reviewer adds information the agent should use.
• The update fixes missing or incorrect data that downstream steps depend on.

Do not reprocess when:

• The change is only an audit note.
• The change only affects a display-only field.
• The update records a final manual decision that should not be overwritten.

Response

A successful update returns the full updated case and the incremented version. If reprocessing was requested, the response may include a workflow execution ID.

Handling Conflicts

If the API returns a conflict:

1. Fetch the latest case.
2. Reapply the intended changes to the latest state.
3. Submit the PATCH request again with the new version.

Do not retry blindly with the old version. That can discard another user's changes.

Operational Behavior

Best Practices

• Patch only the fields that changed.
• Keep update_mask specific.
• Read the current case immediately before applying an operator edit.
• Use reprocessing only when downstream decisions should change.
• Store correction reasons in explicit review or audit fields when useful.
• Avoid patching fields outside the configured case state schema.

Common Errors

• Missing update_mask: include at least one state. path.
• Missing case.state: include the partial state object to update.
• Version conflict: fetch the latest case and retry with the current version.
• Invalid use case: confirm the usecase_id query parameter is correct.