# GitLab Epics API **Canonical:** https://apis.io/apis/gitlab/gitlab-epics-api/ **Provider:** GitLab — https://apis.io/providers/gitlab/ **Base URL:** https://gitlab.com/api/v4 **Documentation:** https://docs.gitlab.com/api/rest/ GitLab Epics API is one of 189 APIs that [GitLab](https://apis.io/providers/gitlab/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification. This API exposes 16 JSON Schema definitions. Tagged areas include Epic. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, authentication docs, an API reference, rate-limit docs, an AsyncAPI specification, and 16 JSON Schemas. > [!warning] > The Epics REST API was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/460668) in GitLab 17.0 > and is planned for removal in v5 of the API. From GitLab 17.4 to 18.0, if > [the new look for epics](https://docs.gitlab.com/user/group/epics/#epics-as-work-items) is enabled, > or in GitLab 18.1 and later, use the Work Items API instead. For more information, see > [migrate epic APIs to work items](https://docs.gitlab.com/api/graphql/epic_work_items_api_migration_guide/). > This change is a breaking change. Use this API to manage [epics](https://docs.gitlab.com/user/group/epics/), the issues assigned to them, their child and [related epics](https://docs.gitlab.com/user/group/epics/linked_epics/), and [group epic boards](https://docs.gitlab.com/user/group/epics/epic_boards/). Every call to this API must be authenticated. If a user is not a member of a private group, a `GET` request on that group results in a `404` status code. Epics are available only in GitLab [Premium and Ultimate](https://about.gitlab.com/pricing/). If the Epics or Related Epics feature is not available, a `403` status code is returned. ## Operations (26) | Method | Path | Summary | |---|---|---| | GET | `/api/v4/groups/{id}/related_epic_links` | List all related epic links for a group | | GET | `/api/v4/groups/{id}/epics/{epic_iid}/related_epics` | List all linked epics for an epic | | POST | `/api/v4/groups/{id}/epics/{epic_iid}/related_epics` | Create a related epic link | | DELETE | `/api/v4/groups/{id}/epics/{epic_iid}/related_epics/{related_epic_link_id}` | Delete a related epic link | | GET | `/api/v4/groups/{id}/epic_boards` | List all epic boards in a group | | GET | `/api/v4/groups/{id}/epic_boards/{board_id}` | Retrieve a group epic board | | GET | `/api/v4/groups/{id}/epic_boards/{board_id}/lists` | List all group epic board lists | | GET | `/api/v4/groups/{id}/epic_boards/{board_id}/lists/{list_id}` | Retrieve a group epic board list | | GET | `/api/v4/groups/{id}/epics` | List all group epics | | GET | `/api/v4/groups/{id}/-/epics` | List all group epics | | GET | `/api/v4/groups/{id}/epics/{epic_iid}` | Get details of an epic | | GET | `/api/v4/groups/{id}/-/epics/{epic_iid}` | Get details of an epic | | POST | `/api/v4/groups/{id}/(-/)epics` | Create a new epic | | PUT | `/api/v4/groups/{id}/(-/)epics/{epic_iid}` | Update an epic | | DELETE | `/api/v4/groups/{id}/(-/)epics/{epic_iid}` | Destroy an epic | | GET | `/api/v4/groups/{id}/(-/)epics/{epic_iid}/epics` | Get related epics | | POST | `/api/v4/groups/{id}/(-/)epics/{epic_iid}/epics` | Create and relate epic to a parent | | POST | `/api/v4/groups/{id}/(-/)epics/{epic_iid}/epics/{child_epic_id}` | Relate epics | | DELETE | `/api/v4/groups/{id}/(-/)epics/{epic_iid}/epics/{child_epic_id}` | Remove epics relation | | PUT | `/api/v4/groups/{id}/(-/)epics/{epic_iid}/epics/{child_epic_id}` | Reorder child epics | | PUT | `/api/v4/groups/{id}/(-/)epics/{epic_iid}/issues/{epic_issue_id}` | Update a related epic link | | POST | `/api/v4/groups/{id}/(-/)epics/{epic_iid}/issues/{epic_issue_id}` | Add an issue to an epic | | DELETE | `/api/v4/groups/{id}/(-/)epics/{epic_iid}/issues/{epic_issue_id}` | Remove an issue from the epic | | GET | `/api/v4/groups/{id}/epics/{epic_iid}/issues` | List all issues for an epic | | GET | `/api/v4/groups/{id}/-/epics/{epic_iid}/issues` | List all issues for an epic | | POST | `/api/v4/groups/{id}/epics/{epic_iid}/todo` | Create a to-do item for an epic | ## Machine-readable artifacts (65) - **OpenAPI** — https://artifacts.apis.io/gitlab/openapi/gitlab-epics-api-openapi.yml - **Documentation** — https://docs.gitlab.com/api/openapi/ - **Documentation** — https://docs.gitlab.com/api/issues/ - **Authentication** — https://docs.gitlab.com/api/rest/authentication/ - **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-put-api-v4-application-settings-request-schema.json - **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-apientities-geo-node-status-schema.json - **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-apientities-geo-site-status-schema.json - **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-apientities-application-setting-schema.json - **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-post-api-v4-geo-status-request-schema.json - **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-put-api-v4-projects-id-request-schema.json - **Documentation** — https://docs.gitlab.com/api/merge_requests/ - **Documentation** — https://docs.gitlab.com/api/pipelines/ - **Documentation** — https://docs.gitlab.com/api/jobs/ - **Documentation** — https://docs.gitlab.com/api/runners/ - **Documentation** — https://docs.gitlab.com/api/users/ - **Documentation** — https://docs.gitlab.com/api/repositories/ - **Documentation** — https://docs.gitlab.com/api/commits/ - **Documentation** — https://docs.gitlab.com/api/branches/ - **Documentation** — https://docs.gitlab.com/api/tags/ - **Documentation** — https://docs.gitlab.com/api/releases/ - **Documentation** — https://docs.gitlab.com/api/environments/ - **Documentation** — https://docs.gitlab.com/api/deployments/ - **Documentation** — https://docs.gitlab.com/api/pipeline_schedules/ - **Documentation** — https://docs.gitlab.com/api/labels/ - **Documentation** — https://docs.gitlab.com/api/milestones/ - **Documentation** — https://docs.gitlab.com/api/notes/ - **Documentation** — https://docs.gitlab.com/api/snippets/ - **Documentation** — https://docs.gitlab.com/api/packages/ - **Documentation** — https://docs.gitlab.com/api/container_registry/ - **Documentation** — https://docs.gitlab.com/api/vulnerabilities/ - **Documentation** — https://docs.gitlab.com/api/deploy_keys/ - **Documentation** — https://docs.gitlab.com/api/protected_branches/ - **Documentation** — https://docs.gitlab.com/api/wikis/ - **Documentation** — https://docs.gitlab.com/api/events/ - **Documentation** — https://docs.gitlab.com/api/search/ - **Documentation** — https://docs.gitlab.com/api/namespaces/ - **Documentation** — https://docs.gitlab.com/api/groups/ - **Documentation** — https://docs.gitlab.com/api/projects/ - **Documentation** — https://docs.gitlab.com/api/applications/ - **Documentation** — https://docs.gitlab.com/api/avatar/ - …and 25 more, listed in full on the page. ## Other GitLab APIs (12) - [GitLab Orbit gRPC API](https://apis.io/apis/gitlab/gitlab-orbit-api/) - [GitLab GraphQL API](https://apis.io/apis/gitlab/gitlab-graphql-api/) - [GitLab Applications API](https://apis.io/apis/gitlab/gitlab-applications-api/) - [GitLab Authorization API](https://apis.io/apis/gitlab/gitlab-authorization-api/) - [GitLab Broadcast Messages API](https://apis.io/apis/gitlab/gitlab-broadcast-messages-api/) - [GitLab Groups API](https://apis.io/apis/gitlab/gitlab-groups-api/) - [GitLab Metadata API](https://apis.io/apis/gitlab/gitlab-metadata-api/) - [GitLab Project Webhooks API](https://apis.io/apis/gitlab/gitlab-project-webhooks-api/) - [GitLab Projects API](https://apis.io/apis/gitlab/gitlab-projects-api/) - [GitLab Tokens API](https://apis.io/apis/gitlab/gitlab-tokens-api/) - [GitLab User Info API](https://apis.io/apis/gitlab/gitlab-user-info-api/) - [GitLab Webhook Configuration API](https://apis.io/apis/gitlab/gitlab-webhook-configuration-api/) ## Tags Epic --- Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/gitlab/gitlab-epics-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/gitlab/.