API: Sprints

Work packages can be assigned to a sprint. This is employed in agile contexts such as Scrum or Kanban to group the work packages to be worked on within a defined time frame towards a defined goal.

Linked Properties

Link Description Type Constraints Supported operations
self This sprint Sprint not null READ
definingWorkspace The workspace in which the sprint is defined Workspace READ
status The status the sprint is in URN READ

The status is represented as a URN and can have the following values:

  • urn:openproject-org:api:v3:sprints:status:in_planning: The sprint hasn’t started yet, it is planned.
  • urn:openproject-org:api:v3:sprints:status:active: The sprint is currently active.
  • urn:openproject-org:api:v3:sprints:status:completed: The sprint has finished.

Local Properties

Property Description Type Constraints Supported operations
id Sprint id Integer x > 0 READ
name Sprint name String not null READ
description Formattable READ
startDate Date READ
finishDate Date READ
createdAt Time of creation DateTime not null READ
updatedAt Time of the most recent change to the sprint DateTime not null READ

Methods

List sprints in project

List sprints in the project. The sprints might be ones native to the project or shared with it. This endpoint supports pagination and filtering.

id
integer

required path

ID of the project whose sprints will be listed

Example:
1

filters
string

optional query

JSON specifying filter conditions.

Accepts the same format and filters as returned by the sprints endpoint.

Example:
[{ "definingWorkspace": { "operator": "=", "values": ["1"] }" }]

offset
integer

optional query

Page number inside the requested collection.

Default:
1

Example:
25

pageSize
integer

optional query

Number of elements to display per page.

Example:
25

200

OK

{
  "_type": "Collection",
  "total": 40,
  "count": 20,
  "pageSize": 20,
  "offset": 1,
  "_embedded": {
    "elements": [
      {
        "_type": "Sprint",
        "id": 3,
        "name": "Sprint 11",
        "startDate": "2026-02-02",
        "finishDate": "2026-02-09",
        "createdAt": "2026-02-06T09:30:49.157Z",
        "updatedAt": "2026-02-10T09:53:21.620Z",
        "_links": {
          "self": {
            "href": "/api/v3/sprints/3",
            "title": "Sprint 11"
          },
          "definingWorkspace": {
            "href": "/api/v3/projects/10",
            "title": "Scrum project"
          },
          "status": {
            "href": "urn:openproject-org:api:v3:sprints:status:in_planning",
            "title": "In planning"
          }
        }
      },
      {
        "_abbreviated": "Further sprint resources shortened for brevity."
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/sprints?filters=%5B%5D&offset=1&pageSize=20"
    },
    "jumpTo": {
      "href": "/api/v3/sprints?filters=%5B%5D&offset=%7Boffset%7D&pageSize=20",
      "templated": true
    },
    "changeSize": {
      "href": "/api/v3/sprints?filters=%5B%5D&offset=1&pageSize=%7Bsize%7D",
      "templated": true
    },
    "nextByOffset": {
      "href": "/api/v3/sprints?filters=%5B%5D&offset=2&pageSize=20"
    }
  }
}
SprintCollectionModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "This sprint collection\n\n**Resource**: Collection"
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/SprintModel"
              }
            }
          }
        }
      }
    }
  ]
}

403

Returned if the user lacks permission to list sprints in the queried for project.

Required permission: view sprints in the project.

{
  "_type": "Collection",
  "total": 40,
  "count": 20,
  "pageSize": 20,
  "offset": 1,
  "_embedded": {
    "elements": [
      {
        "_type": "Sprint",
        "id": 3,
        "name": "Sprint 11",
        "startDate": "2026-02-02",
        "finishDate": "2026-02-09",
        "createdAt": "2026-02-06T09:30:49.157Z",
        "updatedAt": "2026-02-10T09:53:21.620Z",
        "_links": {
          "self": {
            "href": "/api/v3/sprints/3",
            "title": "Sprint 11"
          },
          "definingWorkspace": {
            "href": "/api/v3/projects/10",
            "title": "Scrum project"
          },
          "status": {
            "href": "urn:openproject-org:api:v3:sprints:status:in_planning",
            "title": "In planning"
          }
        }
      },
      {
        "_abbreviated": "Further sprint resources shortened for brevity."
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/sprints?filters=%5B%5D&offset=1&pageSize=20"
    },
    "jumpTo": {
      "href": "/api/v3/sprints?filters=%5B%5D&offset=%7Boffset%7D&pageSize=20",
      "templated": true
    },
    "changeSize": {
      "href": "/api/v3/sprints?filters=%5B%5D&offset=1&pageSize=%7Bsize%7D",
      "templated": true
    },
    "nextByOffset": {
      "href": "/api/v3/sprints?filters=%5B%5D&offset=2&pageSize=20"
    }
  }
}
SprintCollectionModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "This sprint collection\n\n**Resource**: Collection"
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/SprintModel"
              }
            }
          }
        }
      }
    }
  ]
}

404

Returned if the project does not exist.

Required permission: view sprints in the queried for project.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified project does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

List sprints

List sprints visible to the user. This endpoint supports pagination and filtering.

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:

  • definingWorkspace: filters sprints based on the project they are defined in. This is opposed to the projects they are shared with.

Example:
[{ "definingWorkspace": { "operator": "=", "values": ["1"] }" }]

offset
integer

optional query

Page number inside the requested collection.

Default:
1

Example:
25

pageSize
integer

optional query

Number of elements to display per page.

Example:
25

200

OK

{
  "_type": "Collection",
  "total": 40,
  "count": 20,
  "pageSize": 20,
  "offset": 1,
  "_embedded": {
    "elements": [
      {
        "_type": "Sprint",
        "id": 3,
        "name": "Sprint 11",
        "startDate": "2026-02-02",
        "finishDate": "2026-02-09",
        "createdAt": "2026-02-06T09:30:49.157Z",
        "updatedAt": "2026-02-10T09:53:21.620Z",
        "_links": {
          "self": {
            "href": "/api/v3/sprints/3",
            "title": "Sprint 11"
          },
          "definingWorkspace": {
            "href": "/api/v3/projects/10",
            "title": "Scrum project"
          },
          "status": {
            "href": "urn:openproject-org:api:v3:sprints:status:in_planning",
            "title": "In planning"
          }
        }
      },
      {
        "_abbreviated": "Further sprint resources shortened for brevity."
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/sprints?filters=%5B%5D&offset=1&pageSize=20"
    },
    "jumpTo": {
      "href": "/api/v3/sprints?filters=%5B%5D&offset=%7Boffset%7D&pageSize=20",
      "templated": true
    },
    "changeSize": {
      "href": "/api/v3/sprints?filters=%5B%5D&offset=1&pageSize=%7Bsize%7D",
      "templated": true
    },
    "nextByOffset": {
      "href": "/api/v3/sprints?filters=%5B%5D&offset=2&pageSize=20"
    }
  }
}
SprintCollectionModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "This sprint collection\n\n**Resource**: Collection"
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/SprintModel"
              }
            }
          }
        }
      }
    }
  ]
}

Get sprint

Retrieves a sprint defined by its unique identifier.

id
integer

required path

Sprint id

Example:
1

200

OK

{
  "_type": "Sprint",
  "id": 3,
  "name": "Sprint 11",
  "startDate": "2026-02-02",
  "finishDate": "2026-02-09",
  "createdAt": "2026-02-06T09:30:49.157Z",
  "updatedAt": "2026-02-10T09:53:21.620Z",
  "_links": {
    "self": {
      "href": "/api/v3/sprints/3",
      "title": "Sprint 11"
    },
    "definingWorkspace": {
      "href": "/api/v3/projects/10",
      "title": "Scrum project"
    },
    "status": {
      "href": "urn:openproject-org:api:v3:sprints:status:in_planning",
      "title": "In planning"
    }
  }
}
SprintModel
{
  "type": "object",
  "required": [
    "id",
    "_type",
    "name",
    "startDate",
    "finishDate",
    "createdAt",
    "updatedAt"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Sprint id",
      "minimum": 1
    },
    "_type": {
      "type": "string",
      "enum": [
        "Sprint"
      ]
    },
    "name": {
      "type": "string",
      "description": "Sprint name"
    },
    "description": {
      "$ref": "#/components/schemas/Formattable"
    },
    "startDate": {
      "type": [
        "string",
        "null"
      ],
      "format": "date"
    },
    "finishDate": {
      "type": [
        "string",
        "null"
      ],
      "format": "date"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the sprint"
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "definingWorkspace"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This sprint\n\n**Resource**: Sprint"
            }
          ]
        },
        "definingWorkspace": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The workspace to which the sprint belongs.\n\n**Resource**: Workspace"
            }
          ]
        },
        "status": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The current status of the sprint which can be any of:\n\n  - *\"urn:openproject-org:api:v3:sprints:status:in_planning\"*: The sprint hasn't started yet, it is planned.\n  - *\"urn:openproject-org:api:v3:sprints:status:active\"*: The sprint is currently active.\n  - *\"urn:openproject-org:api:v3:sprints:status:completed\"*: The sprint has finished.\n\n**Resource**: N/A"
            }
          ]
        }
      }
    }
  }
}

404

Returned if the sprint does not exist or the client does not have sufficient permissions to see it.

Required permission: view master backlogs (this will change to view sprints)

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}