Operations with Specific Agile - Help

Agile attributes

Represents an agile board configuration.

This table describes attributes of the Agile entity.

To receive an attribute in the response from server, specify it explicitly in the request parameter fields.
To update an attribute, provide it in the body of a POST request.

Field	Type	Description
name	String	The name of the agile board. `Can be null`.
owner	User	Owner of the agile board. `Can be null`.
visibleFor	UserGroup	The user group that can view this board. `Can be null`.
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. `Can be null`.
updateableByProjectBased	Boolean	When true, anyone who can update the associated 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. `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 actual for the current date. `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}

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 URI

https://example.myjetbrains.com/youtrack/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}

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 URI

https://example.myjetbrains.com/youtrack/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}

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 URI

https://example.myjetbrains.com/youtrack/api/agiles/108-23

Resource	/api/agiles/{agileID}
Returned entity	Agile. For the description of the entity attributes, see Supported Fields section.
Supported methods	`GET`: Read a Specific Agile. `POST`: Update a Specific Agile. `DELETE`: Delete a Specific Agile.