OpenProject Sprints API

openapi: 3.2.0
info:
  description: You're looking at the current **stable** documentation of the OpenProject APIv3.
  title: OpenProject API V3 (Stable) Sprints API
  version: '3'
servers:
- url: https://qa.openproject-edge.com
  description: Edge QA instance
- url: https://qa.openproject-stage.com
  description: Staging instance
- url: https://community.openproject.org
  description: Community instance
security:
- BasicAuth: []
tags:
- description: Work packages can be assigned to a sprint.
  name: Sprints
paths:
  /api/v3/projects/{id}/sprints:
    get:
      parameters:
      - description: ID of the project whose sprints will be listed
        example: '1'
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: 'JSON specifying filter conditions.


          Accepts the same format and filters as returned by the [sprints](https://www.openproject.org/docs/api/endpoints/sprints/) endpoint.'
        example: '[{ "definingWorkspace": { "operator": "=", "values": ["1"] }" }]'
        in: query
        name: filters
        required: false
        schema:
          type: string
      - description: Page number inside the requested collection.
        example: '25'
        in: query
        name: offset
        required: false
        schema:
          default: 1
          type: integer
      - description: Number of elements to display per page.
        example: '25'
        in: query
        name: pageSize
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/SprintCollectionModel'
              examples:
                response:
                  $ref: '#/components/examples/SprintCollectionResponse'
          description: OK
          headers: {}
        '403':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/SprintCollectionModel'
              examples:
                response:
                  $ref: '#/components/examples/SprintCollectionResponse'
          description: 'Returned if the user lacks permission to list sprints in the queried for project.


            **Required permission:** view sprints in the project.'
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The specified project does not exist.
          description: 'Returned if the project does not exist.


            **Required permission:** view sprints in the queried for project.'
          headers: {}
      tags:
      - Sprints
      description: List sprints in the project. The sprints might be ones native to the project or shared with it. This endpoint supports pagination and filtering.
      operationId: List_sprints_in_project
      summary: List sprints in project
  /api/v3/sprints:
    get:
      parameters:
      - description: 'JSON specifying filter conditions.

          Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/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"] }" }]'
        in: query
        name: filters
        required: false
        schema:
          type: string
      - description: Page number inside the requested collection.
        example: '25'
        in: query
        name: offset
        required: false
        schema:
          default: 1
          type: integer
      - description: Number of elements to display per page.
        example: '25'
        in: query
        name: pageSize
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/SprintCollectionModel'
              examples:
                response:
                  $ref: '#/components/examples/SprintCollectionResponse'
          description: OK
          headers: {}
      tags:
      - Sprints
      description: List sprints visible to the user. This endpoint supports pagination and filtering.
      operationId: List_sprints
      summary: List sprints
  /api/v3/sprints/{id}:
    get:
      summary: Get sprint
      operationId: get_sprint
      tags:
      - Sprints
      description: Retrieves a sprint defined by its unique identifier.
      parameters:
      - description: Sprint id
        example: '1'
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/SprintModel'
              examples:
                response:
                  $ref: '#/components/examples/SprintResponse'
        '404':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: '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)'
components:
  schemas:
    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


                    **Resource**: Collection'
          _embedded:
            type: object
            required:
            - elements
            properties:
              elements:
                type: array
                items:
                  $ref: '#/components/schemas/SprintModel'
    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


                  **Resource**: Sprint'
            definingWorkspace:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'The workspace to which the sprint belongs.


                  **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"
    CollectionLinks:
      type: object
      required:
      - self
      properties:
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          - description: 'This collection resource.


              **Resource**: Collection'
    Link:
      type: object
      required:
      - href
      properties:
        href:
          type:
          - string
          - 'null'
          description: URL to the referenced resource (might be relative)
        title:
          type: string
          description: Representative label for the resource
        templated:
          type: boolean
          default: false
          description: If true the href contains parts that need to be replaced by the client
        method:
          type: string
          default: GET
          description: The HTTP verb to use when requesting the resource
        payload:
          type: object
          description: The payload to send in the request to achieve the desired result
        identifier:
          type: string
          description: An optional unique identifier to the link object
        type:
          type: string
          description: The MIME-Type of the returned resource.
      example:
        href: /api/v3/work_packages
        method: POST
    Formattable:
      type: object
      required:
      - format
      properties:
        format:
          type: string
          enum:
          - plain
          - markdown
          - custom
          readOnly: true
          description: Indicates the formatting language of the raw text
          example: markdown
        raw:
          type: string
          description: The raw text, as entered by the user
          example: I **am** formatted!
        html:
          type: string
          readOnly: true
          description: The text converted to HTML according to the format
          example: I <strong>am</strong> formatted!
      example:
        format: markdown
        raw: I am formatted!
        html: I am formatted!
    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.
    CollectionModel:
      type: object
      required:
      - _type
      - total
      - count
      - _links
      properties:
        _type:
          type: string
          enum:
          - Collection
        total:
          type: integer
          description: The total amount of elements available in the collection.
          minimum: 0
        count:
          type: integer
          description: Actual amount of elements in this response.
          minimum: 0
        _links:
          $ref: '#/components/schemas/CollectionLinks'
  examples:
    SprintCollectionResponse:
      description: Simple response of a sprint collection.
      value:
        _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
    SprintResponse:
      description: A sprint resource example
      value:
        _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
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic