Developer Portal for YouTrack and Hub Help

Operations with Specific Agile

This resource lets you work with agile boards in YouTrack using the REST API.

Resource

/api/agiles/{agileID}

Returned entity

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

Supported methods

Agile attributes

Represents an agile board configuration.

Related Resources

Below you can find the list of resources that let you work with this entity.

Attributes

This table describes attributes of the Agile entity.

  • To receive an attribute in the response from the server, specify it explicitly in the fields request parameter.

  • To update an attribute, provide it in the body of a POST request.

Field

Type

Description

id

String

The ID of the agile board. Read-only.

name

String

The name of the agile board. Can be null.

owner

User

The owner of the agile board. Can be null.

visibleFor

UserGroup

Deprecated. Use the readSharingSettings attribute instead.

The group of users that can view this board.

Can be null.

visibleForProjectBased

Boolean

Deprecated.

When true, the board is visible to anyone who can view all projects that are associated with the board.

updateableBy

UserGroup

Deprecated. Use the updateSharingSettings attribute instead.

The group of users who can update the settings of this board.

Can be null.

updateableByProjectBased

Boolean

Deprecated.

When true, anyone who can update the associated projects can update the board.

readSharingSettings

AgileSharingSettings

Users and groups that can view this board. If the board is visible only to its owner, this property contains an empty array. Read-only.

updateSharingSettings

AgileSharingSettings

Users and groups that can update this watch folder. If only the folder's owner can update it, this property contains an empty array. Read-only.

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. Can be null.

originalEstimationField

CustomField

A custom field that is used as the original estimation field for the board. Can be null.

projects

Array of Projects

A collection of projects associated with the board.

sprints

Array of Sprints

The set of sprints that are associated with the board.

currentSprint

Sprint

A sprint that is designated as the current one for this agile board. Read-only. Can be null.

columnSettings

ColumnSettings

Column settings of the board. Read-only.

swimlaneSettings

SwimlaneSettings

Settings of the board swimlanes. Can be null.

sprintsSettings

SprintsSettings

Settings of the board sprints. Read-only.

colorCoding

ColorCoding

Color coding settings for the board. Can be null.

status

AgileStatus

Status of the board. Read-only.

Read a Specific Agile

Get settings of the specific agile board.

Required permissions

The user must have permissions to read the board.

Request syntax

GET /api/agiles/{agileID}?{fields}

{agileID}

The database ID of the agile board.

Request parameters

Parameter

Type

Description

fields

String

A list of Agile attributes that should be returned in the response. If no field is specified, only the entityID is returned.

Sample

Sample request

https://example.youtrack.cloud/api/agiles/108-4?fields=id,name,owner(id,name,login),projects(id,name),sprints(id,name),visibleFor(name,id),visibleForProjectBased,updateableBy(id,name),updateableByProjectBased,hideOrphansSwimlane,orphansAtTheTop,currentSprint(id,name),columnSettings(field(id,name),columns(presentation,isResolved,fieldValues(id,name)))

Sample response body

{ "owner": { "login": "john.doe", "name": "John Doe", "id": "1-2", "$type": "User" }, "projects": [ { "name": "Sample Project", "id": "0-0", "$type": "Project" } ], "columnSettings": { "columns": [ { "fieldValues": [ { "name": "Open", "id": "111-16", "$type": "AgileColumnFieldValue" } ], "presentation": "Open", "isResolved": false, "$type": "AgileColumn" }, { "fieldValues": [ { "name": "In Progress", "id": "111-17", "$type": "AgileColumnFieldValue" } ], "presentation": "In Progress", "isResolved": false, "$type": "AgileColumn" }, { "fieldValues": [ { "name": "Fixed", "id": "111-18", "$type": "AgileColumnFieldValue" } ], "presentation": "Fixed", "isResolved": true, "$type": "AgileColumn" }, { "fieldValues": [ { "name": "Verified", "id": "111-19", "$type": "AgileColumnFieldValue" } ], "presentation": "Verified", "isResolved": true, "$type": "AgileColumn" } ], "field": { "name": "State", "id": "58-3", "$type": "CustomField" }, "$type": "ColumnSettings" }, "orphansAtTheTop": false, "sprints": [ { "name": "First sprint", "id": "109-5", "$type": "Sprint" }, { "name": "Sprint 2: Add more resources", "id": "109-7", "$type": "Sprint" }, { "name": "Sprint 3: Bug-fix release", "id": "109-8", "$type": "Sprint" }, { "name": "Sprint 5: Public resources revision", "id": "109-10", "$type": "Sprint" }, { "name": "Sprint 6: Only the name matters", "id": "109-11", "$type": "Sprint" } ], "hideOrphansSwimlane": false, "updateableByProjectBased": true, "visibleForProjectBased": true, "updateableBy": null, "visibleFor": null, "currentSprint": { "name": "Sprint 3: Bug-fix release", "id": "109-8", "$type": "Sprint" }, "name": "Scrum board", "id": "108-4", "$type": "Agile" }

Update a Specific Agile

Update settings of the specific agile board.

Required permissions

The user must have permissions to update the board.

Request syntax

POST /api/agiles/{agileID}?{fields}

{agileID}

The database ID of the agile board.

Request parameters

Parameter

Type

Description

fields

String

A list of Agile attributes that should be returned in the response. If no field is specified, only the entityID is returned.

Sample

Let's set WIP limit for "In Progress" and "Fixed" columns of a board.

Sample request

https://example.youtrack.cloud/api/agiles/108-0?fields=id,name,columnSettings(columns(id,isResolved,presentation,wipLimit(min,max)),field(id,name))

Sample request body

{"columnSettings": { "columns": [ { "id": "110-0" }, { "wipLimit": {"max":5}, "id": "110-1" }, { "wipLimit": {"max":5}, "id": "110-2" }, { "id": "110-3" } ] }}

Sample response body

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

Delete a Specific Agile

Delete an agile board with the specific ID.

Request syntax

DELETE /api/agiles/{agileID}

{agileID}

The database ID of the agile board.

Request parameters

Parameter

Type

Description

fields

String

A list of Agile attributes that should be returned in the response. If no field is specified, only the entityID is returned.

Sample

Sample request

https://example.youtrack.cloud/api/agiles/108-23
Last modified: 7 November 2024