Skip to content

Epics API

Every API call to epic must be authenticated.

If a user is not a member of a group and the group is private, a GET request on that group will result to a 404 status code.

Epics are available only in Ultimate. If epics feature is not available a 403 status code will be returned.

Epic issues API

The epic issues API allows you to interact with issues associated with an epic.

List epics for a group

Gets all epics of the requested group and its subgroups.

GET /groups/:id/-/epics
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user 
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/1/-/epics

Example response:

[
  {
  "id": 29,
  "iid": 4,
  "group_id": 7,
  "title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.",
  "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
  "author": {
    "id": 10,
    "name": "Lu Mayer",
    "username": "kam",
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon",
    "web_url": "http://localhost:3001/kam"
  },
  "start_date": null,
  "end_date": null
  }
]

Single epic

Gets a single epic

GET /groups/:id/-/epics/:epic_iid
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user
epic_iid integer/string yes The internal ID of the epic. 
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/1/-/epics/5

Example response:

{
  "id": 30,
  "iid": 5,
  "group_id": 7,
  "title": "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.",
  "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
  "author":{
    "id": 7,
    "name": "Pamella Huel",
    "username": "arnita",
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",
    "web_url": "http://localhost:3001/arnita"
  },
  "start_date": null,
  "end_date": null
}

New epic

Creates a new epic

POST /groups/:id/-/epics
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user
title string yes The title of the epic
description string no The description of the epic
start_date string no The start date of the epic
end_date string. no The end date of the epic 
curl --header POST "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/1/-/epics?title=Epic&description=Epic%20description

Example response:

{
  "id": 33,
  "iid": 6,
  "group_id": 7,
  "title": "Epic",
  "description": "Epic description",
  "author": {
    "name" : "Alexandra Bashirian",
    "avatar_url" : null,
    "state" : "active",
    "web_url" : "https://gitlab.example.com/eileen.lowe",
    "id" : 18,
    "username" : "eileen.lowe"
  },
  "start_date": null,
  "end_date": null
}

Update epic

Updates an epic

PUT /groups/:id/-/epics/:epic_iid
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user
epic_iid integer/string yes The internal ID of the epic
title string no The title of an epic
description string no The description of an epic
start_date string no The start date of an epic
end_date string. no The end date of an epic 
curl --header PUT "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/1/-/epics/5?title=New%20Title

Example response:

{
  "id": 33,
  "iid": 6,
  "group_id": 7,
  "title": "New Title",
  "description": "Epic description",
  "author": {
    "name" : "Alexandra Bashirian",
    "avatar_url" : null,
    "state" : "active",
    "web_url" : "https://gitlab.example.com/eileen.lowe",
    "id" : 18,
    "username" : "eileen.lowe"
  },
  "start_date": null,
  "end_date": null
}

Delete epic

Deletes an epic

DELETE /groups/:id/-/epics/:epic_iid
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user
epic_iid integer/string yes The internal ID of the epic. 
curl --header DELETE "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/1/-/epics/5?title=New%20Title