# Agiles

This resource lets you work with agile boards in YouTrack using the REST API.
|  Resource  |     ```GENERIC /api/agiles ```    |
| --- | --- |
|  Returned entity  |  [Agile](api-entity-Agile.html). For the description of the entity attributes, see [Supported Fields](#Agile-supported-fields) section.  |
|  Supported methods  |      * `GET`: [Read a List of Agiles](#get_all-Agile-method).    * `POST`: [Add a New Agile](#create-Agile-method).    |
|  Supported sub-resources  |      * [/api/agiles/{agileID}](operations-api-agiles.html)    * [/api/agiles/{agileID}/sprints](resource-api-agiles-agileID-sprints.html)    |

## 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.  |
|  owner  |  [User](api-entity-User.html)  |  The owner of the agile board. `Can be null`.  |
|  visibleFor  |  [UserGroup](api-entity-UserGroup.html)  |    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](api-entity-UserGroup.html)  |    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](api-entity-AgileSharingSettings.html)  |  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](api-entity-AgileSharingSettings.html)  |  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](api-entity-CustomField.html)  |  A custom field that is used as the estimation field for the board. `Can be null`.  |
|  originalEstimationField  |  [CustomField](api-entity-CustomField.html)  |  A custom field that is used as the original estimation field for the board. `Can be null`.  |
|  projects  |  [Array of Projects](api-entity-Project.html)  |  A collection of projects associated with the board.  |
|  sprints  |  [Array of Sprints](api-entity-Sprint.html)  |  The set of sprints that are associated with the board.  |
|  currentSprint  |  [Sprint](api-entity-Sprint.html)  |  A sprint that is designated as the current one for this agile board. `Read-only`. `Can be null`.  |
|  columnSettings  |  [ColumnSettings](api-entity-ColumnSettings.html)  |  Column settings of the board. `Read-only`.  |
|  swimlaneSettings  |  [SwimlaneSettings](api-entity-SwimlaneSettings.html)  |  Settings of the board swimlanes. `Can be null`.  |
|  sprintsSettings  |  [SprintsSettings](api-entity-SprintsSettings.html)  |  Settings of the board sprints. `Read-only`.  |
|  colorCoding  |  [ColorCoding](api-entity-ColorCoding.html)  |  Color coding settings for the board. `Can be null`.  |
|  status  |  [AgileStatus](api-entity-AgileStatus.html)  |  Status of the board. `Read-only`.  |

## Read a List of Agiles

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

### Request syntax

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

|  null  |  The database ID of Agile  |
| --- | --- |

### 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](api-concept-pagination.html).     |

### Sample

#### Sample request

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

#### Sample response body

```JSON
[
  {
    "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

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

|  null  |  The database ID of Agile  |
| --- | --- |

### 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

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

#### Sample request body

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

#### Sample response body

```JSON
{
  "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"
}
```