# Review workflow

> Read the current state, apply one action, and use the returned version for the next update.

Source: https://math-api.qmindlabs.ai/docs/guides/workflow

## Read before you write

[GETRead workflow and history](https://math-api.qmindlabs.ai/docs/api-reference/tag/tasks-review/GET/api/math/tasks/%7Btask_id%7D/workflow.md)

Use the returned task `version` for every mutation. IDs and versions below are placeholders; use values from your own response.

```json
{
  "action": "feedback",
  "version": 3,
  "comment": "Clarify the final proof step."
}
```

[POSTApply a workflow action](https://math-api.qmindlabs.ai/docs/api-reference/tag/tasks-review/POST/api/math/tasks/%7Btask_id%7D.md)

## Available actions

| Action | Required fields | Role |
| --- | --- | --- |
| `assign` | `reviewer_id` (or null) | Owner / Admin |
| `start` | No additional fields | Assigned reviewer / Owner / Admin |
| `feedback` | `comment` | Assigned reviewer / Owner / Admin |
| `verdict` | `decision` and `comment` | Assigned reviewer / Owner / Admin |
| `client` | `client_id` (or null) | Owner / Admin |
| `archive` / `restore` | No additional fields | Owner / Admin |
| `reopen` | `comment` | Owner / Admin |

All actions also require `version` and the `write` scope. Decisions are `READY_AS_IS`, `MINOR_REPAIR`, `MAJOR_REPAIR`, or `REJECTED`.

## State transitions

Restore an archived task before making changes. Reopen a completed review before reassigning it or recording another verdict. Feedback can move an assigned task into `IN_REVIEW`. There is no arbitrary status setter.

## Handle a conflict

A stale version or invalid transition returns `409`. Read the latest workflow, review intervening changes, and decide whether the intended action still applies. Do not repeatedly submit the old version.

Each successful action increments the version and returns the updated task and history. Client updates use the exact current `updated_at` timestamp instead.

## Notes and history

Notes are nonempty comments from workflow events. Adding a note uses the feedback action and follows the same version and state rules.

[POSTAdd a task note](https://math-api.qmindlabs.ai/docs/api-reference/tag/tasks-review/POST/api/math/tasks/%7Btask_id%7D/notes.md)

[GETBrowse workflow activity](https://math-api.qmindlabs.ai/docs/api-reference/tag/monitoring/GET/api/math/activity.md)