Editing a workflow

The request lets you edit an existing workflow: its name, initial action, steps, type, and resolution settings for issue types.

PATCH

https://api.tracker.yandex.net/v3/workflows/<id>?version=<version>

Request format

Before making the request, get API access.

To edit a workflow, use an HTTP request with the PATCH method. Specify only the parameters you want to change in the request body. Pass the current workflow version in the version query parameter or the If-Match header.

PATCH /v3/workflows/<id>?version=<version>
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
Content-Type: application/json
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
    "name": "Updated workflow",
    "type": "VISUAL",
    "initialAction": {
        "id": "open",
        "name": { "ru": "Открыть", "en": "Open" },
        "target": "open"
    },
    "steps": [
        {
            "status": "open",
            "actions": [
                {
                    "id": "inProgress",
                    "name": { "ru": "Взять в работу", "en": "Start progress" },
                    "target": "inProgress"
                }
            ]
        },
        {
            "status": "inProgress",
            "actions": [
                {
                    "id": "close",
                    "name": { "ru": "Закрыть", "en": "Close" },
                    "target": "closed"
                }
            ]
        },
        {
            "status": "closed",
            "actions": []
        }
    ]
}

Headers

Host: address of the node that provides the API.
Authorization: Authorization token about these formats:
- OAuth <OAuth_token>: For authorization using the OAuth 2.0 protocol. Learn more
- Bearer <IAM_token>: For authorization using an IAM token, if a Yandex Identity Hub organization is linked to Tracker. Learn more
X-Org-ID or X-Cloud-Org-ID: Organization ID.
- Use the X-Org-ID header if a Tracker organization is linked to Yandex 360 for Business.
- Use the X-Cloud-Org-ID header if a Tracker organization is linked to Yandex Identity Hub.
To get the organization ID, go to Administration → Organizations and copy the value from the ID field.

Resource

Parameter	Description	Data type
<id>	Workflow ID.	String
<version>	Workflow version. Used to prevent conflicts during concurrent changes. You can find out the current version using the request to get a workflow. You can use the `If-Match` header instead of the query parameter.	Number

Request body parameters

Parameter	Description	Data type	Required
name	New workflow name.	String	No
type	Workflow type. The `visual` type is currently available. Use the `VISUAL` value in the request. The API returns `visual` in the response. The field may be missing for workflows created earlier.	String	No
initialAction	New initial action. The object structure is described under Creating a workflow.	Object	No
steps	Updated array of workflow steps. The object structure is described under Creating a workflow.	Array of objects	No
issueTypeResolutions	Array of resolution settings for issue types.	Array of objects	No

Example: Edit workflow W21 by setting a new name and updating the steps with transitions to testing and completion (version 3)

PATCH /v3/workflows/W21?version=3
Host: api.tracker.yandex.net
Authorization: OAuth y0__xAbc******
Content-Type: application/json
X-Org-ID: 1234******

{
    "name": "QA workflow",
    "initialAction": {
        "id": "new",
        "name": { "ru": "Создать", "en": "Create" },
        "target": "new"
    },
    "steps": [
        {
            "status": "new",
            "actions": [
                {
                    "id": "needInfo",
                    "name": { "ru": "Отправить на тестирование", "en": "Send to testing" },
                    "target": "testing"
                }
            ]
        },
        {
            "status": "testing",
            "actions": [
                {
                    "id": "resolved",
                    "name": { "ru": "Завершить", "en": "Resolve" },
                    "target": "resolved"
                }
            ]
        },
        {
            "status": "resolved",
            "actions": []
        }
    ]
}

Response format

Request executed successfully

Request failed

If the request is successful, the API returns a response with code 200 OK.

The response body contains information about the edited workflow in JSON format. The version field value is incremented after every change.

The API does not return optional fields that have no value, such as queue, type, createdBy, and updatedBy.

{
    "self": "https://api.tracker.yandex.net/v3/workflows/W21",
    "id": "W21",
    "name": "Updated workflow",
    "version": 2,
    "steps": [
        {
            "status": {
                "self": "https://api.tracker.yandex.net/v3/statuses/1",
                "id": "1",
                "key": "open",
                "display": "Open"
            },
            "actions": [
                {
                    "id": "inProgress",
                    "name": "Start progress",
                    "target": {
                        "self": "https://api.tracker.yandex.net/v3/statuses/3",
                        "id": "3",
                        "key": "inProgress",
                        "display": "In progress"
                    }
                }
            ]
        },
        {
            "status": {
                "self": "https://api.tracker.yandex.net/v3/statuses/3",
                "id": "3",
                "key": "inProgress",
                "display": "In progress"
            },
            "actions": [
                {
                    "id": "close",
                    "name": "Close",
                    "target": {
                        "self": "https://api.tracker.yandex.net/v3/statuses/8",
                        "id": "8",
                        "key": "closed",
                        "display": "Closed"
                    }
                }
            ]
        },
        {
            "status": {
                "self": "https://api.tracker.yandex.net/v3/statuses/8",
                "id": "8",
                "key": "closed",
                "display": "Closed"
            }
        }
    ],
    "initialAction": {
        "id": "open",
        "name": "Open",
        "target": {
            "self": "https://api.tracker.yandex.net/v3/statuses/1",
            "id": "1",
            "key": "open",
            "display": "Open"
        }
    },
    "queue": {
        "self": "https://api.tracker.yandex.net/v3/queues/DESIGN",
        "id": "4",
        "key": "DESIGN",
        "display": "DESIGN"
    },
    "created": "2026-08-11T14:37:06.356+0000",
    "updated": "2026-08-11T15:10:00.000+0000",
    "createdBy": {
        "self": "https://api.tracker.yandex.net/v3/users/11********",
        "id": "11********",
        "display": "User Name",
        "cloudUid": "ajeppa7dgp53********",
        "passportUid": 1100000000
    },
    "updatedBy": {
        "self": "https://api.tracker.yandex.net/v3/users/11********",
        "id": "11********",
        "display": "User Name",
        "cloudUid": "ajeppa7dgp53********",
        "passportUid": 1100000000
    },
    "deleted": false,
    "type": "visual"
}

Response parameters

Parameter	Description	Data type
self	Workflow link.	String
id	Workflow ID.	String
name	Workflow name.	String
version	Workflow version. Each change increases the version number.	Number
steps	Array of workflow steps.	Array of objects
initialAction	Initial action.	Object
queue	Queue the workflow is linked to.	Object
created	Creation date and time.	String
updated	Date and time of the last update.	String
createdBy	Workflow author.	Object
updatedBy	User who last updated the workflow.	Object
deleted	Indicates whether the workflow has been deleted.	Boolean
type	Workflow type. The only current value is `visual`. The field may be missing for workflows created earlier.	String

Fields of objects in the steps array

Parameter	Description	Data type
status	Workflow step status.	Object
actions	Array of actions (transitions) available from this status.	Array of objects

Fields of the status object

Parameter	Description	Data type
self	Status link.	String
id	Status ID.	String
key	Status key.	String
display	Status display name.	String

Fields of the action and initialAction objects

Parameter	Description	Data type
id	Action ID.	String
name	Action name.	String
target	Target status that the action moves the issue to.	Object

Fields of the target object

Parameter	Description	Data type
self	Status link.	String
id	Status ID.	String
key	Status key.	String
display	Status display name.	String

Fields of the queue object

Parameter	Description	Data type
self	Queue link.	String
id	Queue ID.	String
key	Queue key.	String
display	Queue display name.	String

Fields of the user object (createdBy, updatedBy)

Parameter	Description	Data type
self	User link.	String
id	User ID.	String
display	User display name.	String
cloudUid	Unique user ID in Yandex Cloud.	String
passportUid	Unique user account ID in Yandex Passport.	Number

If the request could not be processed successfully, the response message contains information about the errors:

400: One or more request parameters have an invalid value.

401: The user is not authorized. Make sure that actions described in the API access section are performed.

403: You are not authorized to perform this action. You can check what rights you have in the Tracker interface. The same rights are required to perform an action via the API and interface.

404: The requested object was not found. You may have specified an invalid object ID or key.

412: A conflict occurred while editing the object. The error may be due to an invalid update version.

422: JSON validation error, the request is rejected.

428: Access to the resource is denied. Make sure all required conditions for the request are specified.

Was the article helpful?

Get a workflow

Edit an action in a workflow step