Commands

This page describes how to apply a command to one or more issues.

Root resource	`/api/commands`
Returned entity	CommandList. For the description of the entity attributes, see the Supported Fields section.
Supported methods	`POST`: apply a command to one or more issues.
Supported sub-resources	`/api/commands/assist`: command suggestions.

Supported Fields

Field	Type	Description
caret	Int	Current caret position. End of current command by default.
commands	List	Read-only. Stores a collection of commands parsed from the provided `query`.
comment	String	A comment to add to an issue.
issues	List	Mandatory. Stores a collection of issues to which the current command applies.
query	String	Mandatory. Stores a command to apply.
runAs	String	Login for a user on whose behalf the command is executed. To use the `runAs` parameter, you must have the Low-level Administration permission in the project for the target issue. For more information about permissions, see Permissions Reference.
silent	Boolean	If `true`, the command is applied without notification. The default value is `false`.
suggestions	List	Read-only. Stores a collection of possible command suggestions.
usesMarkdown	Boolean	When `true`, a comment added with the command is parsed as Markdown formatted. Otherwise, the comment is parsed as YouTrack Wiki formatted.
visibility	CommandVisibility	Stores visibility settings for a comment added with the command. Supported entity types: CommandLimitedVisibility : a command with restricted visibility applied to a comment. CommandUnlimitedVisibility: a command with no visibility restrictions applied to a comment.
id	String	Stores a unique ID of the command.

Execute a Command

Request syntax:

POST /api/commands[?fields=<fields>]

Request parameters

Parameter	Type	Description
fields	string	A list of attributes of the `CommandList` entity that should be returned in the response.

Sample minimal request

A minimal request for a command requires you to send in the request body a query to apply and a collection of issues that should be represented at least by their IDs.

curl -X POST \
'https://example.myjetbrains.com/youtrack/api/commands' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"query": "Fixed",
"issues": [ { "id": "2-17" } ] }'

Sample response body

For the sample minimal request without the fields parameter, the server sends a response with the 200 OK status and an empty body.

Sample request with a comment

The following request assigns the specific issue to the current user and adds a new comment with restricted visibility.

curl -X POST \
 'https://example.myjetbrains.com/youtrack/api/commands?fields=issues%28id,idReadable%29,query,visibility%28permittedGroups%28id,name%29,permittedUsers%28id,login%29%29' \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
 -H 'Cache-Control: no-cache' \
 -H 'Content-Type: application/json' \
 -d '{
 "query":"for me ",
 "issues":[{"id":"2-15"}],
 "silent":false,
 "comment":"Still cannot reproduce.",
 "visibility":
 {
 "$type":"jetbrains.youtrack.commands.rest.CommandLimitedVisibility",
 "permittedGroups":[{"id":"3-2"}]
 }
 }'

Sample response body

For the sample minimal request above, the server sends a response with the following data in its body:

{
    "visibility": {
        "permittedGroups": [
            {
            "id": "3-2"
            }
        ],
        "$type": "jetbrains.youtrack.commands.rest.CommandLimitedVisibility"
    },
    "issues": [
        {
            "idReadable": "SP-16",
            "id": "2-15"
        }
    ],
    "query": "for me "
}

Command Suggestions

Resource

/api/commands/assist

Returned entity

CommandList. For the description of the entity attributes, see the Supported Fields section.

Supported methods

POST: Get a list of command suggestions for a query.

Get Command Suggestions

Request syntax

POST /api/commands/assist?[fields=<fields>]

Request parameters

Parameter	Type	Description
fields	string	A list of attributes of the `CommandList` entity that should be returned in the response.

Sample request

curl -X POST \
'https://example.myjetbrains.com/youtrack/api/commands/assist?fields=caret,commands%28delete,description,error%29,query,styleRanges%28end,length,start,style%29,suggestions%28caret,className,comment,completionEnd,completionStart,description,group,icon,id,matchingEnd,matchingStart,option,prefix,suffix%29'
\
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{"query": "sta","caret": 3, "issues": [ { "id": "2-30" } ] }'

Sample response body

{
    "commands": [
        {
            "description": "unknown command: sta",
            "delete": false,
            "error": true
        }
    ],
    "styleRanges": [
        {
            "start": 0,
            "style": "error",
            "length": 3
        }
    ],
    "suggestions": [
        {
            "icon": null,
            "description": "change star",
            "completionEnd": 3,
            "caret": 5,
            "completionStart": 0,
            "matchingEnd": 3,
            "matchingStart": 0,
            "group": null,
            "prefix": null,
            "option": "star",
            "suffix": " ",
            "id": "star",
            "className": null
        },
        {
            "icon": null,
            "description": "change State",
            "completionEnd": 3,
            "caret": 6,
            "completionStart": 0,
            "matchingEnd": 3,
            "matchingStart": 0,
            "group": null,
            "prefix": null,
            "option": "State",
            "suffix": " ",
            "id": "State",
            "className": null
        }
    ],
    "caret": 3,
    "query": "sta"
}

Last modified: 7 March 2019