Agiles

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

Resource	/api/agiles
Returned entity	Agile. For the description of the entity attributes, see Supported Fields section.
Supported methods	`GET`: Read a List of Agiles. `POST`: Add a New Agile.
Supported sub-resources	/api/agiles/{agileID}: Operations with Specific Agile /api/agiles/{agileID}/sprints: Sprints

Agile attributes

Represents an agile board configuration.

Related Resources

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

Agile Boards

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 List of Agiles

Get the list of all available agile boards in the system.

Request syntax

GET /api/agiles?{fields}&{$top}&{$skip}

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.

$skip

Int

Optional. Lets you set a number of returned entities to skip before returning the first one.

$top

Int

Optional. Lets you specify the maximum number of entries that are returned in the response. If you don't set the $top value, the server limits the maximum number of returned entries.

The server returns a maximum of 42 entries for most resources that return collections. For more information, see Pagination.

Sample

Sample request

                https://example.youtrack.cloud/api/agiles?fields=id,name,owner(id,name),projects(id,name),sprints(id,name)&$top=3
            

Sample response body

                [
                  {
                    "owner": {
                      "name": "John Smith",
                      "id": "1-1",
                      "$type": "User"
                    },
                    "projects": [
                      {
                        "name": "Sandbox",
                        "id": "0-3",
                        "$type": "Project"
                      }
                    ],
                    "sprints": [
                      {
                        "name": "First sprint",
                        "id": "109-0",
                        "$type": "Sprint"
                      }
                    ],
                    "name": "Sandbox Scrum Board",
                    "id": "108-0",
                    "$type": "Agile"
                  },
                  {
                    "owner": {
                      "name": "John Doe",
                      "id": "1-2",
                      "$type": "User"
                    },
                    "projects": [
                      {
                        "name": "GRA Project",
                        "id": "0-7",
                        "$type": "Project"
                      }
                    ],
                    "sprints": [
                      {
                        "name": "First sprint",
                        "id": "109-1",
                        "$type": "Sprint"
                      }
                    ],
                    "name": "GRA Project",
                    "id": "108-1",
                    "$type": "Agile"
                  },
                  {
                    "owner": {
                      "name": "John Doe",
                      "id": "1-2",
                      "$type": "User"
                    },
                    "projects": [
                      {
                        "name": "Sample Project",
                        "id": "0-0",
                        "$type": "Project"
                      },
                      {
                        "name": "Rest Api Project",
                        "id": "0-2",
                        "$type": "Project"
                      }
                    ],
                    "sprints": [
                      {
                        "name": "First sprint",
                        "id": "109-3",
                        "$type": "Sprint"
                      }
                    ],
                    "name": "Kanban board",
                    "id": "108-3",
                    "$type": "Agile"
                  }
                ]
            

Add a New Agile

Create a new agile board.

Required fields: name, projects (id - database IDs of the project that need to be associated with the board).

Request syntax

POST /api/agiles?{fields}&{template}

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.
template	String	The name of the board template that should be used. Possible values: `kanban`, `scrum`, `version`, `custom`, `personal`.

Sample

Sample request

                https://example.youtrack.cloud/api/agiles?template=kanban&fields=id,name,owner(id,name),projects(id,name),sprints(id,name)
            

Sample request body

                {
                  "name":"Kanban board",
                  "projects":[{"id":"0-0"},{"id":"0-2"}],
                  "updateableByProjectBased":true,
                  "visibleForProjectBased":true
                }
            

Sample response body

                {
                  "owner": {
                    "name": "John Doe",
                    "id": "1-2",
                    "$type": "User"
                  },
                  "projects": [
                    {
                      "name": "Sample Project",
                      "id": "0-0",
                      "$type": "Project"
                    },
                    {
                      "name": "Rest Api Project",
                      "id": "0-2",
                      "$type": "Project"
                    }
                  ],
                  "sprints": [
                    {
                      "name": "First sprint",
                      "id": "109-30",
                      "$type": "Sprint"
                    }
                  ],
                  "name": "Kanban board",
                  "id": "108-23",
                  "$type": "Agile"
                }
            

Last modified: 7 November 2024