Creating a workflow

Use this request to create a new workflow.

POST

https://api.tracker.yandex.net/v3/workflows

Request format

Before making the request, get API access.

To create a workflow, use an HTTP request with the POST method. Specify the parameters in JSON format in the request body.

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

{
    "name": "Design",
    "queue": "DESIGN",
    "type": "VISUAL",
    "initialAction": {
        "id": "open",
        "name": { "ru": "Открыть", "en": "Open" },
        "target": "open"
    },
    "steps": [
        {
            "status": "open",
            "description": { "ru": "Задача открыта", "en": "Issue is open" },
            "actions": [
                {
                    "id": "inProgress",
                    "name": { "ru": "Взять в работу", "en": "Start progress" },
                    "description": { "ru": "Перевести задачу в работу", "en": "Move issue to in progress" },
                    "target": "inProgress"
                }
            ]
        },
        {
            "status": "inProgress",
            "description": { "ru": "Задача в работе", "en": "Issue is in progress" },
            "actions": [
                {
                    "id": "close",
                    "name": { "ru": "Закрыть", "en": "Close" },
                    "description": { "ru": "Закрыть задачу", "en": "Close the issue" },
                    "target": "closed"
                }
            ]
        },
        {
            "status": "closed",
            "description": { "ru": "Задача закрыта", "en": "Issue is closed" },
            "actions": []
        }
    ],
    "issueTypeResolutions": [
        {
            "issueType": "task",
            "resolutions": ["wontFix", "fixed"]
        }
    ]
}

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.

Request body parameters

Required parameters

Parameter	Description	Data type
name	Workflow name.	String
initialAction	Initial action that sets the status assigned to an issue when it is created.	Object
steps	Array of workflow steps. Each step corresponds to a status and contains transitions available from it.	Array of objects

Optional parameters

Parameter	Description	Data type
id	Workflow ID. If the parameter is not specified, the API generates an ID in the `W...` format.	String
queue	Queue that the workflow is linked to. You can specify the queue key (string), ID (number), or an object: `{"key": "..."}` / `{"id": ...}` / `{"name": "..."}`. If the parameter is not specified, a shared workflow is created. You can assign it to issue types in the queue settings. Only users with the relevant permissions can create a shared workflow.	String, number, or object
type	Workflow type. The available type is `visual`. Use `VISUAL` in the request. The API returns `visual` in the response. The field may be missing for workflows created earlier.	String
issueTypeResolutions	Array of resolution settings for issue types.	Array of objects

Fields of the step object

Parameter	Description	Data type	Required
status	Step status. You can specify the status key (string), ID (number), or an object: `{"key": "..."}` / `{"id": ...}` / `{"name": "..."}`.	String, number, or object	Yes
description	Step description as an object with localizations, for example, `{"ru": "...", "en": "..."}`.	Object	No
actions	Array of actions (transitions) available from this status.	Array of objects	No
metaAction	Step meta-action (runs automatically).	Object	No
statusType	Status type. Allowed values: `NEW`, `IN_PROGRESS`, `PAUSED`, `DONE`, `CANCELLED`.	String	No

Fields of the action object

Parameter	Description	Data type	Required
id	Action ID.	String	No
name	Action name as an object with localizations, for example, `{"ru": "...", "en": "..."}`.	Object	Yes
description	Action description as an object with localizations.	Object	No
target	Target status that the action transitions to. You can specify the status key (string), ID (number), or an object: `{"key": "..."}` / `{"id": ...}` / `{"name": "..."}`.	String, number, or object	Yes
screen	Transition screen with fields that can be filled out when the action is performed.	Object	No
conditions	Array of action execution conditions.	Array of objects	No
functions	Array of functions that run during the transition.	Array of objects	No

Fields of the issueTypeResolutions array objects

Parameter	Description	Data type	Required
issueType	Key or ID of the issue type to configure resolutions for. You can get a list of available issue types with this request.	String or number	Yes
resolutions	Array of keys or IDs of resolutions available for issues of this type. You can get a list of available resolutions with this request.	Array of strings or numbers	Yes

Response format

Request executed successfully

Request failed

If the request is successful, the API returns a response with code 201 Created.

The response body contains information about the created 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": "Design",
    "version": 1,
    "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"
                    }
                }
            ]
        }
    ],
    "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-11T14:37:06.356+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 the steps array objects

Parameter	Description	Data type
status	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 transitions 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 is not processed successfully, the response 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.

422: JSON validation error, the request is rejected.

Was the article helpful?

Get group permissions for a queue

Get a list of workflows