---
schema: rendered-html/v1
title: "Operations with Specific Agile | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/operations-api-agiles.html
generated_at: 2026-06-11T15:05:53.138164+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- MCP Tools
- YouTrack Workflows
- YouTrack Import Scripts
- YouTrack Form API
- YouTrack REST API
- Get Started with REST API
- REST API Reference
- Entities
- Resources
- Activity Items
- Issue Activities Page
- Build Bundles
- Enum Bundles
- Owned Bundles
- State Bundles
- User Bundles
- Version Bundles
- Custom Fields
- Field Types
- Backup Files
- Database Backup Settings
- Global Settings
- Organizations
- Projects
- Telemetry data
- Global Time Tracking Settings
- Agiles
- [Operations with Specific Agile](operations-api-agiles.html)
- Sub-resources
- Articles
- Assigned Roles
- Commands
- Command Suggestions
- User Groups
- Issue Link Types
- Issue Tag
- Issues
- Issue Count
- Permissions
- Roles
- Saved Queries
- Search Suggestions
- Tags
- Users
- My User Profile
- Issue Work Items
- REST API Use Cases
- REST API Troubleshooting
- Color Indices List
- Hub REST API

1. YouTrack REST API
2. REST API Reference
3. Resources
4. Agiles
5. [Operations with Specific Agile](#0)

# Operations with Specific Agile﻿

Last modified: 24 March 2025

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](/help/youtrack/devportal/operations-api-agiles.html#Agile-supported-fields) section. |
| Supported methods | - `GET`: [Read a Specific Agile](/help/youtrack/devportal/operations-api-agiles.html#get-Agile-method). - `POST`: [Update a Specific Agile](/help/youtrack/devportal/operations-api-agiles.html#update-Agile-method). - `DELETE`: [Delete a Specific Agile](/help/youtrack/devportal/operations-api-agiles.html#delete-Agile-method). |

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

- [Operations with Specific Agile](/help/youtrack/devportal/operations-api-agiles.html)
- [Agile attributes](/help/youtrack/devportal/operations-api-agiles.html#Agile-supported-fields)
- [Read a Specific Agile](/help/youtrack/devportal/operations-api-agiles.html#get-Agile-method)
- [Update a Specific Agile](/help/youtrack/devportal/operations-api-agiles.html#update-Agile-method)
- [Delete a Specific Agile](/help/youtrack/devportal/operations-api-agiles.html#delete-Agile-method)

AgilesSprints

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.
