Linked epics API

Tier: Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
History

If the Related Epics feature is not available in your GitLab plan, a 403 status code is returned.

Get a list of a given group’s related epic links within group and sub-groups, filtered according to the user authorizations. The user needs to have access to the source_epic and target_epic to access the related epic link. 

GET /groups/:id/related_epic_links

Supported attributes:

Attribute Type Required Description
id integer/string Yes ID or URL-encoded path of the group.
created_after string no Return related epic links created on or after the given time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)
created_before string no Return related epic links created on or before the given time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)
updated_after string no Return related epic links updated on or after the given time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)
updated_before string no Return related epic links updated on or before the given time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)

Example request: 

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/related_epic_links"

Example response: 

[ { "id": 1, "created_at": "2022-01-31T15:10:44.988Z", "updated_at": "2022-01-31T15:10:44.988Z", "link_type": "relates_to", "source_epic": { "id": 21, "iid": 1, "color": "#1068bf", "text_color": "#FFFFFF", "group_id": 26, "parent_id": null, "parent_iid": null, "title": "Aspernatur recusandae distinctio omnis et qui est iste.", "description": "some description", "confidential": false, "author": { "id": 15, "username": "trina", "name": "Theresia Robel", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/085e28df717e16484cbf6ceca75e9a93?s=80&d=identicon", "web_url": "http://gitlab.example.com/trina" }, "start_date": null, "end_date": null, "due_date": null, "state": "opened", "web_url": "http://gitlab.example.com/groups/flightjs/-/epics/1", "references": { "short": "&1", "relative": "&1", "full": "flightjs&1" }, "created_at": "2022-01-31T15:10:44.988Z", "updated_at": "2022-03-16T09:32:35.712Z", "closed_at": null, "labels": [], "upvotes": 0, "downvotes": 0, "_links": { "self": "http://gitlab.example.com/api/v4/groups/26/epics/1", "epic_issues": "http://gitlab.example.com/api/v4/groups/26/epics/1/issues", "group": "http://gitlab.example.com/api/v4/groups/26", "parent": null } }, "target_epic": { "id": 25, "iid": 5, "color": "#1068bf", "text_color": "#FFFFFF", "group_id": 26, "parent_id": null, "parent_iid": null, "title": "Aut assumenda id nihil distinctio fugiat vel numquam est.", "description": "some description", "confidential": false, "author": { "id": 3, "username": "valerie", "name": "Erika Wolf", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/9ef7666abb101418a4716a8ed4dded80?s=80&d=identicon", "web_url": "http://gitlab.example.com/valerie" }, "start_date": null, "end_date": null, "due_date": null, "state": "opened", "web_url": "http://gitlab.example.com/groups/flightjs/-/epics/5", "references": { "short": "&5", "relative": "&5", "full": "flightjs&5" }, "created_at": "2022-01-31T15:10:45.080Z", "updated_at": "2022-03-16T09:32:35.842Z", "closed_at": null, "labels": [], "upvotes": 0, "downvotes": 0, "_links": { "self": "http://gitlab.example.com/api/v4/groups/26/epics/5", "epic_issues": "http://gitlab.example.com/api/v4/groups/26/epics/5/issues", "group": "http://gitlab.example.com/api/v4/groups/26", "parent": null } }, } ]

List linked epics from an epic

Get a list of a given epic’s linked epics filtered according to the user authorizations. 

GET /groups/:id/epics/:epic_iid/related_epics

Supported attributes:

Attribute Type Required Description
epic_iid integer Yes Internal ID of a group’s epic
id integer/string Yes ID or URL-encoded path of the group.

Example request: 

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/epics/:epic_iid/related_epics"

Example response: 

[ { "id":2, "iid":2, "color":"#1068bf", "text_color":"#FFFFFF", "group_id":2, "parent_id":null, "parent_iid":null, "title":"My title 2", "description":null, "confidential":false, "author":{ "id":3, "username":"user3", "name":"Sidney Jones4", "state":"active", "avatar_url":"https://www.gravatar.com/avatar/82797019f038ab535a84c6591e7bc936?s=80u0026d=identicon", "web_url":"http://localhost/user3" }, "start_date":null, "end_date":null, "due_date":null, "state":"opened", "web_url":"http://localhost/groups/group1/-/epics/2", "references":{ "short":"u00262", "relative":"u00262", "full":"group1u00262" }, "created_at":"2022-03-10T18:35:24.479Z", "updated_at":"2022-03-10T18:35:24.479Z", "closed_at":null, "labels":[ ], "upvotes":0, "downvotes":0, "_links":{ "self":"http://localhost/api/v4/groups/2/epics/2", "epic_issues":"http://localhost/api/v4/groups/2/epics/2/issues", "group":"http://localhost/api/v4/groups/2", "parent":null }, "related_epic_link_id":1, "link_type":"relates_to", "link_created_at":"2022-03-10T18:35:24.496+00:00", "link_updated_at":"2022-03-10T18:35:24.496+00:00" } ]
History
  • Minimum required role for the group changed from Reporter to Guest in GitLab 15.8.

Create a two-way relation between two epics. The user must have at least the Guest role for both groups. 

POST /groups/:id/epics/:epic_iid/related_epics

Supported attributes:

Attribute Type Required Description
epic_iid integer Yes Internal ID of a group’s epic.
id integer/string Yes ID or URL-encoded path of the group owned by the authenticated user.
target_epic_iid integer/string Yes Internal ID of a target group’s epic.
target_group_id integer/string Yes ID or URL-encoded path of the target group.
link_type string No Type of the relation (relates_to, blocks, is_blocked_by), defaults to relates_to.

Example request: 

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/26/epics/1/related_epics?target_group_id=26&target_epic_iid=5"

Example response: 

{ "id": 1, "created_at": "2022-01-31T15:10:44.988Z", "updated_at": "2022-01-31T15:10:44.988Z", "link_type": "relates_to", "source_epic": { "id": 21, "iid": 1, "color": "#1068bf", "text_color": "#FFFFFF", "group_id": 26, "parent_id": null, "parent_iid": null, "title": "Aspernatur recusandae distinctio omnis et qui est iste.", "description": "some description", "confidential": false, "author": { "id": 15, "username": "trina", "name": "Theresia Robel", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/085e28df717e16484cbf6ceca75e9a93?s=80&d=identicon", "web_url": "http://gitlab.example.com/trina" }, "start_date": null, "end_date": null, "due_date": null, "state": "opened", "web_url": "http://gitlab.example.com/groups/flightjs/-/epics/1", "references": { "short": "&1", "relative": "&1", "full": "flightjs&1" }, "created_at": "2022-01-31T15:10:44.988Z", "updated_at": "2022-03-16T09:32:35.712Z", "closed_at": null, "labels": [], "upvotes": 0, "downvotes": 0, "_links": { "self": "http://gitlab.example.com/api/v4/groups/26/epics/1", "epic_issues": "http://gitlab.example.com/api/v4/groups/26/epics/1/issues", "group": "http://gitlab.example.com/api/v4/groups/26", "parent": null } }, "target_epic": { "id": 25, "iid": 5, "color": "#1068bf", "text_color": "#FFFFFF", "group_id": 26, "parent_id": null, "parent_iid": null, "title": "Aut assumenda id nihil distinctio fugiat vel numquam est.", "description": "some description", "confidential": false, "author": { "id": 3, "username": "valerie", "name": "Erika Wolf", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/9ef7666abb101418a4716a8ed4dded80?s=80&d=identicon", "web_url": "http://gitlab.example.com/valerie" }, "start_date": null, "end_date": null, "due_date": null, "state": "opened", "web_url": "http://gitlab.example.com/groups/flightjs/-/epics/5", "references": { "short": "&5", "relative": "&5", "full": "flightjs&5" }, "created_at": "2022-01-31T15:10:45.080Z", "updated_at": "2022-03-16T09:32:35.842Z", "closed_at": null, "labels": [], "upvotes": 0, "downvotes": 0, "_links": { "self": "http://gitlab.example.com/api/v4/groups/26/epics/5", "epic_issues": "http://gitlab.example.com/api/v4/groups/26/epics/5/issues", "group": "http://gitlab.example.com/api/v4/groups/26", "parent": null } }, }
History
  • Minimum required role for the group changed from Reporter to Guest in GitLab 15.8.

Delete a two-way relation between two epics. The user must have at least the Guest role for both groups. 

DELETE /groups/:id/epics/:epic_iid/related_epics/:related_epic_link_id

Supported attributes:

Attribute Type Required Description
epic_iid integer Yes Internal ID of a group’s epic.
id integer/string Yes ID or URL-encoded path of the group owned by the authenticated user.
related_epic_link_id integer/string Yes Internal ID of a related epic link.

Example request: 

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/26/epics/1/related_epics/1"

Example response: 

{ "id": 1, "created_at": "2022-01-31T15:10:44.988Z", "updated_at": "2022-01-31T15:10:44.988Z", "link_type": "relates_to", "source_epic": { "id": 21, "iid": 1, "color": "#1068bf", "text_color": "#FFFFFF", "group_id": 26, "parent_id": null, "parent_iid": null, "title": "Aspernatur recusandae distinctio omnis et qui est iste.", "description": "some description", "confidential": false, "author": { "id": 15, "username": "trina", "name": "Theresia Robel", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/085e28df717e16484cbf6ceca75e9a93?s=80&d=identicon", "web_url": "http://gitlab.example.com/trina" }, "start_date": null, "end_date": null, "due_date": null, "state": "opened", "web_url": "http://gitlab.example.com/groups/flightjs/-/epics/1", "references": { "short": "&1", "relative": "&1", "full": "flightjs&1" }, "created_at": "2022-01-31T15:10:44.988Z", "updated_at": "2022-03-16T09:32:35.712Z", "closed_at": null, "labels": [], "upvotes": 0, "downvotes": 0, "_links": { "self": "http://gitlab.example.com/api/v4/groups/26/epics/1", "epic_issues": "http://gitlab.example.com/api/v4/groups/26/epics/1/issues", "group": "http://gitlab.example.com/api/v4/groups/26", "parent": null } }, "target_epic": { "id": 25, "iid": 5, "color": "#1068bf", "text_color": "#FFFFFF", "group_id": 26, "parent_id": null, "parent_iid": null, "title": "Aut assumenda id nihil distinctio fugiat vel numquam est.", "description": "some description", "confidential": false, "author": { "id": 3, "username": "valerie", "name": "Erika Wolf", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/9ef7666abb101418a4716a8ed4dded80?s=80&d=identicon", "web_url": "http://gitlab.example.com/valerie" }, "start_date": null, "end_date": null, "due_date": null, "state": "opened", "web_url": "http://gitlab.example.com/groups/flightjs/-/epics/5", "references": { "short": "&5", "relative": "&5", "full": "flightjs&5" }, "created_at": "2022-01-31T15:10:45.080Z", "updated_at": "2022-03-16T09:32:35.842Z", "closed_at": null, "labels": [], "upvotes": 0, "downvotes": 0, "_links": { "self": "http://gitlab.example.com/api/v4/groups/26/epics/5", "epic_issues": "http://gitlab.example.com/api/v4/groups/26/epics/5/issues", "group": "http://gitlab.example.com/api/v4/groups/26", "parent": null } }, }