> Introduced in [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354)
NOTE:
NOTE:
> `references.relative` is relative to the group that the epic is being requested. When epic is fetched from its origin group
> `references.relative` is relative to the group that the epic is being requested. When epic is fetched from its origin group
...
@@ -62,7 +63,7 @@ GET /groups/:id/epics?state=opened
...
@@ -62,7 +63,7 @@ GET /groups/:id/epics?state=opened
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
| `author_id` | integer | no | Return epics created by the given user `id` |
| `author_id` | integer | no | Return epics created by the given user `id` |
| `labels` | string | no | Return epics matching a comma separated list of labels names. Label names from the epic group or a parent group can be used |
| `labels` | string | no | Return epics matching a comma separated list of labels names. Label names from the epic group or a parent group can be used |
| `with_labels_details` | boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413)|
| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Available in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) and later |
| `order_by` | string | no | Return epics ordered by `created_at` or `updated_at` fields. Default is `created_at` |
| `order_by` | string | no | Return epics ordered by `created_at` or `updated_at` fields. Default is `created_at` |
| `sort` | string | no | Return epics sorted in `asc` or `desc` order. Default is `desc` |
| `sort` | string | no | Return epics sorted in `asc` or `desc` order. Default is `desc` |
| `search` | string | no | Search epics against their `title` and `description` |
| `search` | string | no | Search epics against their `title` and `description` |
...
@@ -73,7 +74,7 @@ GET /groups/:id/epics?state=opened
...
@@ -73,7 +74,7 @@ GET /groups/:id/epics?state=opened
| `updated_before` | datetime | no | Return epics updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `updated_before` | datetime | no | Return epics updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `include_ancestor_groups` | boolean | no | Include epics from the requested group's ancestors. Default is `false` |
| `include_ancestor_groups` | boolean | no | Include epics from the requested group's ancestors. Default is `false` |
| `include_descendant_groups` | boolean | no | Include epics from the requested group's descendants. Default is `true` |
| `include_descendant_groups` | boolean | no | Include epics from the requested group's descendants. Default is `true` |
| `my_reaction_emoji` | string | no | Return epics reacted by the authenticated user by the given emoji. `None` returns epics not given a reaction. `Any` returns epics given at least one reaction. Introduced in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31479)|
| `my_reaction_emoji` | string | no | Return epics reacted by the authenticated user by the given emoji. `None` returns epics not given a reaction. `Any` returns epics given at least one reaction. Available in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31479) and later |
| `labels` | string | no | The comma separated list of labels |
| `labels` | string | no | The comma separated list of labels |
| `description` | string | no | The description of the epic. Limited to 1,048,576 characters. |
| `description` | string | no | The description of the epic. Limited to 1,048,576 characters. |
| `confidential` | boolean | no | Whether the epic should be confidential |
| `confidential` | boolean | no | Whether the epic should be confidential |
| `created_at` | string | no | When the epic was created. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` . Requires administrator or project/group owner privileges ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255309) in GitLab 13.5) |
| `created_at` | string | no | When the epic was created. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` . Requires administrator or project/group owner privileges ([available](https://gitlab.com/gitlab-org/gitlab/-/issues/255309) in GitLab 13.5 and later) |
| `start_date_is_fixed` | boolean | no | Whether start date should be sourced from `start_date_fixed` or from milestones (since 11.3) |
| `start_date_is_fixed` | boolean | no | Whether start date should be sourced from `start_date_fixed` or from milestones (in GitLab 11.3 and later) |
| `start_date_fixed` | string | no | The fixed start date of an epic (since 11.3) |
| `start_date_fixed` | string | no | The fixed start date of an epic (in GitLab 11.3 and later) |
| `due_date_is_fixed` | boolean | no | Whether due date should be sourced from `due_date_fixed` or from milestones (since 11.3) |
| `due_date_is_fixed` | boolean | no | Whether due date should be sourced from `due_date_fixed` or from milestones (in GitLab 11.3 and later) |
| `due_date_fixed` | string | no | The fixed due date of an epic (since 11.3) |
| `due_date_fixed` | string | no | The fixed due date of an epic (in GitLab 11.3 and later) |
| `parent_id` | integer/string | no | The ID of a parent epic (since 11.11) |
| `parent_id` | integer/string | no | The ID of a parent epic (in GitLab 11.11 and later) |
```shell
```shell
curl --request POST --header"PRIVATE-TOKEN: <your_access_token>""https://gitlab.example.com/api/v4/groups/1/epics?title=Epic&description=Epic%20description"
curl --request POST --header"PRIVATE-TOKEN: <your_access_token>""https://gitlab.example.com/api/v4/groups/1/epics?title=Epic&description=Epic%20description"
...
@@ -352,12 +353,12 @@ PUT /groups/:id/epics/:epic_iid
...
@@ -352,12 +353,12 @@ PUT /groups/:id/epics/:epic_iid
| `labels` | string | no | Comma-separated label names for an issue. Set to an empty string to unassign all labels. |
| `labels` | string | no | Comma-separated label names for an issue. Set to an empty string to unassign all labels. |
| `add_labels` | string | no | Comma-separated label names to add to an issue. |
| `add_labels` | string | no | Comma-separated label names to add to an issue. |
| `remove_labels` | string | no | Comma-separated label names to remove from an issue. |
| `remove_labels` | string | no | Comma-separated label names to remove from an issue. |
| `updated_at` | string | no | When the epic was updated. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` . Requires administrator or project/group owner privileges ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255309) in GitLab 13.5) |
| `updated_at` | string | no | When the epic was updated. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` . Requires administrator or project/group owner privileges ([available](https://gitlab.com/gitlab-org/gitlab/-/issues/255309) in GitLab 13.5 and later) |
| `start_date_is_fixed` | boolean | no | Whether start date should be sourced from `start_date_fixed` or from milestones (since 11.3) |
| `start_date_is_fixed` | boolean | no | Whether start date should be sourced from `start_date_fixed` or from milestones (in GitLab 11.3 and later) |
| `start_date_fixed` | string | no | The fixed start date of an epic (since 11.3) |
| `start_date_fixed` | string | no | The fixed start date of an epic (in GitLab 11.3 and later) |
| `due_date_is_fixed` | boolean | no | Whether due date should be sourced from `due_date_fixed` or from milestones (since 11.3) |
| `due_date_is_fixed` | boolean | no | Whether due date should be sourced from `due_date_fixed` or from milestones (in GitLab 11.3 and later) |
| `due_date_fixed` | string | no | The fixed due date of an epic (since 11.3) |
| `due_date_fixed` | string | no | The fixed due date of an epic (in GitLab 11.3 and later) |
| `state_event` | string | no | State event for an epic. Set `close` to close the epic and `reopen` to reopen it (since 11.4) |
| `state_event` | string | no | State event for an epic. Set `close` to close the epic and `reopen` to reopen it (in GitLab 11.4 and later) |
```shell
```shell
curl --request PUT --header"PRIVATE-TOKEN: <your_access_token>""https://gitlab.example.com/api/v4/groups/1/epics/5?title=New%20Title"
curl --request PUT --header"PRIVATE-TOKEN: <your_access_token>""https://gitlab.example.com/api/v4/groups/1/epics/5?title=New%20Title"