# PATCH /api/v2/workflow-transitions/{workflow_transition}

Update a workflow transition

- MCP id: workflow-transitions.update
- Scope: api:write:workflows
- Permission: workflows::update
- Needs the sprints feature on your organisation
- Rate cost: 1 unit, write bucket. A write costs the same whatever `view` you ask for.
- Cache-Control: private, no-store

Partially updates a workflow transition: absent keys are untouched, an empty body is rejected.

`workflow_id` is not accepted: an edge cannot be moved to another workflow, because its two statuses belong to the one it was created in. The two status fields must be sent together or not at all, and they must differ; both are checked against the transition's own workflow. Send `If-Match` with the `ETag` from your last read to detect a concurrent edit, which answers `412`. Treat it as best-effort only: this resource carries no concurrency token, and `updated_at` is second-precision, so two writes inside the same second are indistinguishable.

## Parameters
- workflow_transition (integer, path): The WorkflowTransition's numeric id.
- view (string, optional): Which field set to render.
- X-Request-Id (header, optional): A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.
- If-Match (header, optional): The ETag a write is conditional on. A stale validator is 412 precondition-failed.

## Request body
- name (string ≤ 255, optional): Transition label as shown on the status button, e.g. `Start progress`.
- from_status_id (integer → WorkflowStatus.id, optional): Status a work item must currently be in for this edge to apply. Required when to_status_id is present.
- to_status_id (integer → WorkflowStatus.id, optional): Status the work item moves to. Always different from `from_status_id`. Required when from_status_id is present. Must differ from from_status_id.

Unknown keys are refused with `422` validation-failed, naming the key.

## Response 200
- id (integer, required): Unique identifier.
- workflow_id (integer, required): Workflow this edge belongs to. Both statuses belong to the same workflow, and the edge cannot be moved to another one.
- from_status_id (integer, required): Status a work item must currently be in for this edge to apply.
- to_status_id (integer, required): Status the work item moves to. Always different from `from_status_id`.
- name (string ≤ 255, required): Transition label as shown on the status button, e.g. `Start progress`.
- created_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Creation timestamp.
- updated_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Last-write timestamp; use for incremental sync.
- workflow (Ref or WorkflowSummary, required): Workflow this edge belongs to.
- from_status (Ref or WorkflowStatusSummary, required): Status the edge leads out of.
- to_status (Ref or WorkflowStatusSummary, required): Status the edge leads into.
- links (WorkflowTransitionLinks, required)
  - self (url, required): The canonical URI of this record.

## Errors
- 403 forbidden-by-policy | insufficient-permission | insufficient-token-scope: Forbidden.
- 412 precondition-failed: Precondition failed.
- 415 unsupported-media-type: Unsupported media type.
- 422 unprocessable-relationship | validation-failed: Unprocessable content.
- 400 idempotency-key-required | invalid-cursor | invalid-query-parameter | malformed-request | unsupported-parameter: Bad request.
- 401 token-expired | unauthenticated: Unauthenticated.
- 404 endpoint-not-found | resource-not-found: Not found.
- 406 not-acceptable: Not acceptable.
- 429 rate-limit-exceeded: Too many requests.
- 500 internal-error: Server error.
- 503 tenant-unavailable: Service unavailable.

## Example
```bash
curl -X PATCH \
  'https://<your-url>/api/v2/workflow-transitions/1' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: *' \
  -d '{
    "name": "Begin work"
  }'
```