Editing an action in a workflow step

The request lets you edit the parameters of a specific action (transition) in a workflow step (status).

PATCH

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

Request format

Before making the request, get API access.

To edit an action, use an HTTP request with the PATCH method. Specify the parameters in JSON format in the request body.

PATCH /v3/workflows/<id>/steps/<status>/actions/<actionId>?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": { "ru": "Взять в работу", "en": "Start progress" },
    "target": "inProgress"
}

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
<status>	Key of the status (step) that contains the action. For example: `open`, `inProgress`, `closed`. You can get the list of workflow step statuses using the request to get a workflow.	String
<actionId>	ID of the action inside the step. For example: `inProgress`, `close`. You can get the list of actions for each step using the request to get a workflow.	String
<version>	Workflow version. Used to control concurrent changes. You can find out the current version using the request to get a workflow.	Number

Request body parameters

Additional parameters

Parameter	Description	Data type
id	Action ID.	String
name	Action name as an object with localizations, for example `{"ru": "...", "en": "..."}`.	Object
description	Action description as an object with localizations.	Object
target	Target status that the action moves the issue to. You can specify a status key (string), ID (number), or an object: `{"key": "..."}` / `{"id": ...}` / `{"name": "..."}`.	String, number, or object
screen	Transition screen with fields that can be filled in when performing the action.	Object
conditions	Array of conditions for performing the action.	Array of objects
functions	Array of functions executed during the transition.	Array of objects

Example: Edit the “Close” action in the “In progress” step of workflow W21 (version 2) by updating the name, adding a description, and changing the target status

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

{
    "name": { "ru": "Завершить", "en": "Complete" },
    "description": { "ru": "Перевести задачу в статус «Закрыт»", "en": "Move issue to Closed status" },
    "target": "closed"
}

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 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": 3,
    "steps": [
        {
            "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"
            }
        },
        {
            "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"
                    }
                }
            ]
        }
    ],
    "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-12T12:42:50.675+0000",
    "updated": "2026-08-12T14:00:19.614+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.

409: There was a conflict when editing the object. The error may be due to an invalid update version.

422: JSON validation error, the request is rejected.

Was the article helpful?

Edit a workflow

Delete a workflow