diff options
Diffstat (limited to 'doc/api/iterations.md')
-rw-r--r-- | doc/api/iterations.md | 57 |
1 files changed, 57 insertions, 0 deletions
diff --git a/doc/api/iterations.md b/doc/api/iterations.md new file mode 100644 index 00000000000..53a6bb00f23 --- /dev/null +++ b/doc/api/iterations.md @@ -0,0 +1,57 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Project iterations API **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. + +This page describes the project iterations API. +There's a separate [group iterations API](./group_iterations.md) page. + +As of GitLab 13.5, we don't have project-level iterations, but you can use this endpoint to fetch the iterations of the project's ancestor groups. + +## List project iterations + +Returns a list of project iterations. + +```plaintext +GET /projects/:id/iterations +GET /projects/:id/iterations?state=opened +GET /projects/:id/iterations?state=closed +GET /projects/:id/iterations?title=1.0 +GET /projects/:id/iterations?search=version +``` + +| Attribute | Type | Required | Description | +| ------------------- | ------- | -------- | ----------- | +| `state` | string | no | Return only `opened`, `upcoming`, `started`, `closed`, or `all` iterations. Defaults to `all`. | +| `search` | string | no | Return only iterations with a title matching the provided string. | +| `include_ancestors` | boolean | no | Include iterations from parent group and its ancestors. Defaults to `true`. | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/iterations" +``` + +Example response: + +```json +[ + { + "id": 53, + "iid": 13, + "group_id": 5, + "title": "Iteration II", + "description": "Ipsum Lorem ipsum", + "state": 2, + "created_at": "2020-01-27T05:07:12.573Z", + "updated_at": "2020-01-27T05:07:12.573Z", + "due_date": "2020-02-01", + "start_date": "2020-02-14" + } +] +``` |