Epic Links API

Note: This endpoint was introduced in GitLab 11.8.

Manages parent-child epic relationships.

Every API call to epic_links 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 the Ultimate/Gold tier. If the epics feature is not available, a 403 status code will be returned.

Gets all child epics of an epic.

GET /groups/:id/epics/:epic_iid/epics
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 yes The internal ID of the epic.
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/1/epics/5/epics/

Example response:

[
  {
    "id": 29,
    "iid": 6,
    "group_id": 1,
    "parent_id": 5,
    "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,
    "start_date_is_fixed": false,
    "start_date_fixed": null,
    "start_date_from_milestones": null,
    "end_date": "2018-07-31",
    "due_date": "2018-07-31",
    "due_date_is_fixed": false,
    "due_date_fixed": null,
    "due_date_from_milestones": "2018-07-31",
    "created_at": "2018-07-17T13:36:22.770Z",
    "updated_at": "2018-07-18T12:22:05.239Z",
    "labels": []
  }
]

Assign a child epic

Creates an association between two epics, designating one as the parent epic and the other as the child epic. A parent epic can have multiple child epics. If the new child epic already belonged to another epic, it is unassigned from that previous parent.

POST /groups/:id/epics/:epic_iid/epics
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 yes The internal ID of the epic.
child_epic_id integer yes The global ID of the child epic. Internal ID can’t be used because they can conflict with epics from other groups.
curl --header POST "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/1/epics/5/epics/6

Example response:

{
  "id": 6,
  "iid": 38,
  "group_id": 1,
  "parent_id": 5
  "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,
  "start_date_is_fixed": false,
  "start_date_fixed": null,
  "start_date_from_milestones": null,
  "end_date": "2018-07-31",
  "due_date": "2018-07-31",
  "due_date_is_fixed": false,
  "due_date_fixed": null,
  "due_date_from_milestones": "2018-07-31",
  "created_at": "2018-07-17T13:36:22.770Z",
  "updated_at": "2018-07-18T12:22:05.239Z",
  "labels": []
}

Create and assign a child epic

Creates a a new epic and associates it with provided parent epic. The response is LinkedEpic object.

POST /groups/:id/epics/:epic_iid/epics
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 yes The internal ID of the (future parent) epic.
title integer yes The global ID of the child epic. Internal ID can’t be used because they can conflict with epics from other groups.
curl --header POST "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/1/epics/5/epics?title=Newpic

Example response:

{
  "id": 24,
  "iid": 2,
  "title": "child epic",
  "group_id": 49,
  "parent_id": 23,
  "has_children": false,
  "reference":  "&2",
  "url": "http://localhost/groups/group16/-/epics/2",
  "relation_url": "http://localhost/groups/group16/-/epics/1/links/24"
}

Re-order a child epic

PUT /groups/:id/epics/:epic_iid/epics/:child_epic_id
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 yes The internal ID of the epic.
child_epic_id integer yes The global ID of the child epic. Internal ID can’t be used because they can conflict with epics from other groups.
move_before_id integer no The global ID of a sibling epic that should be placed before the child epic.
move_after_id integer no The global ID of a sibling epic that should be placed after the child epic.
curl --header PUT "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/1/epics/4/epics/5

Example response:

[
  {
    "id": 29,
    "iid": 6,
    "group_id": 1,
    "parent_id": 5,
    "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,
    "start_date_is_fixed": false,
    "start_date_fixed": null,
    "start_date_from_milestones": null,
    "end_date": "2018-07-31",
    "due_date": "2018-07-31",
    "due_date_is_fixed": false,
    "due_date_fixed": null,
    "due_date_from_milestones": "2018-07-31",
    "created_at": "2018-07-17T13:36:22.770Z",
    "updated_at": "2018-07-18T12:22:05.239Z",
    "labels": []
  }
]

Unassign a child epic

Unassigns a child epic from a parent epic.

DELETE /groups/:id/epics/:epic_iid/epics/:child_epic_id
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 yes The internal ID of the epic.
child_epic_id integer yes The global ID of the child epic. Internal ID can’t be used because they can conflict with epics from other groups.
curl --header DELETE "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/1/epics/4/epics/5

Example response:

{
  "id": 5,
  "iid": 38,
  "group_id": 1,
  "parent_id": null,
  "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,
  "start_date_is_fixed": false,
  "start_date_fixed": null,
  "start_date_from_milestones": null,
  "end_date": "2018-07-31",
  "due_date": "2018-07-31",
  "due_date_is_fixed": false,
  "due_date_fixed": null,
  "due_date_from_milestones": "2018-07-31",
  "created_at": "2018-07-17T13:36:22.770Z",
  "updated_at": "2018-07-18T12:22:05.239Z",
  "labels": []
}