Agile Board Configuration

Resource	`/api/agiles/<boardID>`
Returned entity	Agile. For details, see the Supported Fields.
Supported methods	`GET`: read an agile board configuration. `POST`: update an agile board configuration. `DELETE`: delete an agile board configuration.
Sub-resources	`/api/agiles/<boardID>/sprints`: read a list of sprints of an agile board, or create a new sprint. `/api/agiles/<boardID>/sprints/<sprintID>`: operate a specific sprint of an agile board.

Supported fields

Field	Type	Description
name	String	Name of an agile board.
owner	User	Owner of the agile board.
visibleFor	UserGroup?	A user group that can view this board is visible for.
visibleForProjectBased	Boolean	When `true`, the board is visible to everyone who can view all projects that are associated with the board.
updateableBy	UserGroup?	Group of users who can update board settings.
updateableByProjectBased	Boolean	When `true`, anyone who can update the accosiated projects can update the board.
orphansAtTheTop	Boolean	When `true`, the orphan swimlane is placed at the top of the board. Otherwise, the orphans swimlane is located below all other swimlanes.
hideOrphansSwimlane	Boolean	When `true`, the orphans swimlane is not displayed on the board.
estimationField	CustomField	A custom field that is used as the estimation field for the board.
projects	Project	A collection of projects associated with the board.
sprints	Iterable<Sprint>	Collection of existing sprints of the board.
currentSprint	Sprint	A read-only attribute that contains dtata of a sprint that is actual for the current date.
columnSettings	ColumnSettings	Column settings of the board.
swimlaneSettings	SwimlaneSettings?	Settings of the board swimlanes.
sprintsSettings	SprintsSettings	Setting of the board sprints.
colorCoding	ColorCoding?	Color coding settings for the board. The `ColorCoding` entity is a commot ancestor for two actual entities:
status	AgileStatus	Status of the board.

Read an Agile Board

Get the configuration of a specific agile board.

Request syntax:

GET <YouTrack baseURL>/api/agiles/<boardID>?fields=<string>

Request parameters:

Parameter	Description
<YouTrack baseURL>	The baseURL of your YouTrack service.
<boardID>	Unique ID of the agile board in the YouTrack service.
fields	Optional list of fields to return in the response.

Sample request:

curl -X GET \
'https://example.myjetbrains.com/youtrack/api/agiles/108-0?fields=id,name,owner%28id,name,login%29,projects%28id,name%29,sprints%28id,name%29,hideOrphansSwimlane,columnSettings%28columns%28isResolved,presentation,wipLimit%28min,max%29%29,field%28id,name%29%29' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'

Sample response body:

{
    "projects": [
        {
            "name": "Sandbox",
            "id": "0-3"
        }
    ],
    "sprints": [
        {
            "name": "First sprint",
            "id": "109-0"
        }
    ],
    "hideOrphansSwimlane": false,
    "columnSettings": {
        "columns": [
            {
                "presentation": "Open",
                "wipLimit": null,
                "isResolved": false
            },
            {
                "presentation": "In Progress",
                "wipLimit": null,
                "isResolved": false
            },
            {
                "presentation": "Fixed",
                "wipLimit": null,
                "isResolved": true
            },
            {
                "presentation": "Verified",
                "wipLimit": null,
                "isResolved": true
            }
        ],
        "field": {
            "name": "State",
            "id": "58-3"
        }
    },
    "owner": {
        "login": "root",
        "name": "John Smith",
        "id": "1-1"
    },
    "name": "Sandbox Scrum Board",
    "id": "108-0"
}

Update an Agile Board

Update configuration of a specific agile board.

Request syntax:

POST <YouTrack baseURL>/api/agiles/<boardID>[?{fields}]

Request parameters:

Parameter	Description
<YouTrack baseURL>	The baseURL of your YouTrack service.
<boardID>	Unique ID of the agile board in the YouTrack service.
fields	Optional list of fields to return in the response.

Sample request:

In this sample, we request to set a maximum WIP limit for the "In Progress" column of the board. Please note, that when you update columnSettings you must mention IDs of all columns, even if you do not want to update them. Otherwise, server attempts to delete not-mentioned columns.

curl -X POST \
'https://example.myjetbrains.com/youtrack/api/agiles/108-0?fields=id,name,columnSettings%28columns%28id,isResolved,presentation,wipLimit%28min,max%29%29,field%28id,name%29%29' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
-d '{"columnSettings": { "columns": [ { "id": "110-0" }, { "wipLimit": {"max":5}, "id": "110-1" }, { "id": "110-2" }, { "id": "110-3" } ] }}'

Sample response body:

{
    "columnSettings": {
        "field": {
            "name": "State",
            "id": "58-3"
        },
        "columns": [
            {
                "presentation": "Open",
                "wipLimit": null,
                "isResolved": false,
                "id": "110-0"
            },
            {
                "presentation": "In Progress",
                "wipLimit": {
                    "max": 5,
                    "min": null
                },
                "isResolved": false,
                "id": "110-1"
            },
            {
                "presentation": "Fixed",
                "wipLimit": null,
                "isResolved": true,
                "id": "110-2"
            },
            {
                "presentation": "Verified",
                "wipLimit": null,
                "isResolved": true,
                "id": "110-3"
            }
        ]
    },
    "name": "Sandbox Scrum Board",
    "id": "108-0"
}

Delete a Board

Delete an agile board with a specific ID.

Request syntax:

DELETE <YouTrack baseURL>/api/agiles/<boardID>

Request parameters:

Parameter	Description
<YouTrack baseURL>	The baseURL of your YouTrack service.
<boardID>	Unique ID of the agile board to delete.

Sample request:

curl -X DELETE \
https://example.myjetbrains.com/youtrack/api/agiles/108-2 \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'

Last modified: 7 March 2019