{{< details >}}

  • Tier: 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

{{< alert type=”warning” >}}

史诗 REST API 已在极狐GitLab 17.0 中被弃用，并计划在 API v5 中移除。在极狐GitLab 17.0 及以后版本中，如果启用了新的史诗外观，使用工作项 API 取而代之。更多详情，可以查看如何迁移基友 API 的指南。此变更是一个破坏性变更。

{{< /alert >}}

每次对史诗的 API 调用都必须经过认证。

如果用户不是私有群组的成员，对该群组的 GET 请求将导致 404 状态码。

如果史诗功能不可用，将返回 403 状态码。

史诗议题 API

史诗议题 API 允许您与与史诗相关的议题进行交互。

里程碑日期集成

由于开始日期和截止日期可以动态地从相关议题的里程碑中获取，当用户具有编辑权限时，将显示其他字段。这些包括两个布尔字段 start_date_is_fixed 和 due_date_is_fixed，以及四个日期字段 start_date_fixed、start_date_from_inherited_source、due_date_fixed 和 due_date_from_inherited_source。

  • end_date 已被弃用，建议使用 due_date。
  • start_date_from_milestones 已被弃用，建议使用 start_date_from_inherited_source。
  • due_date_from_milestones 已被弃用，建议使用 due_date_from_inherited_source。

史诗分页

默认情况下，GET 请求一次返回 20 个结果，因为 API 结果是分页的。

阅读更多关于 分页 的内容。

{{< alert type=”warning” >}}

在极狐GitLab 12.6 及更高版本中，响应中的 reference 属性已被弃用，建议使用 references。

{{< /alert >}}

{{< alert type=”note” >}}

references.relative 是相对于请求史诗的群组。当从其原始群组获取史诗时，relative 格式与 short 格式相同。当跨群组请求史诗时，relative 格式预计与 full 格式相同。

{{< /alert >}}

列出群组的史诗

获取请求群组及其子群组的所有史诗。

GET /groups/:id/epics
GET /groups/:id/epics?author_id=5
GET /groups/:id/epics?labels=bug,reproduced
GET /groups/:id/epics?state=opened
属性 类型 必需 描述
id integer/string 是 群组的 ID 或 URL 编码路径
author_id integer 否 返回由给定用户 id 创建的史诗
author_username string 否 返回由给定 username 创建的用户的史诗
labels string 否 返回与用逗号分隔的标签名称匹配的史诗。可以使用史诗群组或父群组的标签名称
with_labels_details boolean 否 如果 true，响应在标签字段中返回每个标签的更多详细信息：:name、:color、:description、:description_html、:text_color。默认值为 false。
order_by string 否 返回按 created_at、updated_at 或 title 字段排序的史诗。默认值为 created_at
sort string 否 返回以 asc 或 desc 顺序排序的史诗。默认值为 desc
search string 否 根据史诗的 title 和 description 搜索史诗
state string 否 根据史诗的 state 搜索史诗，可能的过滤器：opened、closed 和 all，默认值：all
created_after datetime 否 返回在给定时间或之后创建的史诗。期望为 ISO 8601 格式（2019-03-15T08:00:00Z）
created_before datetime 否 返回在给定时间或之前创建的史诗。期望为 ISO 8601 格式（2019-03-15T08:00:00Z）
updated_after datetime 否 返回在给定时间或之后更新的史诗。期望为 ISO 8601 格式（2019-03-15T08:00:00Z）
updated_before datetime 否 返回在给定时间或之前更新的史诗。期望为 ISO 8601 格式（2019-03-15T08:00:00Z）
include_ancestor_groups boolean 否 包含来自请求群组祖先的史诗。默认值为 false
include_descendant_groups boolean 否 包含来自请求群组后代的史诗。默认值为 true
my_reaction_emoji string 否 返回由认证用户通过给定表情符号做出反应的史诗。None 返回未给予反应的史诗。Any 返回给予至少一个反应的史诗。
not Hash 否 返回不匹配提供参数的史诗。接受：author_id、author_username 和 labels。 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics"

示例响应：

[
  {
  "id": 29,
  "iid": 4,
  "group_id": 7,
  "parent_id": 23,
  "parent_iid": 3,
  "title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.",
  "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
  "state": "opened",
  "confidential": "false",
  "web_url": "http://gitlab.example.com/groups/test/-/epics/4",
  "reference": "&4",
  "references": {
    "short": "&4",
    "relative": "&4",
    "full": "test&4"
  },
  "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://gitlab.example.com/kam"
  },
  "start_date": null,
  "start_date_is_fixed": false,
  "start_date_fixed": null,
  "start_date_from_milestones": null,       //deprecated in favor of start_date_from_inherited_source
  "start_date_from_inherited_source": null,
  "end_date": "2018-07-31",                 //deprecated in favor of due_date
  "due_date": "2018-07-31",
  "due_date_is_fixed": false,
  "due_date_fixed": null,
  "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
  "due_date_from_inherited_source": "2018-07-31",
  "created_at": "2018-07-17T13:36:22.770Z",
  "updated_at": "2018-07-18T12:22:05.239Z",
  "closed_at": "2018-08-18T12:22:05.239Z",
  "labels": [],
  "upvotes": 4,
  "downvotes": 0,
  "color": "#1068bf",
  "_links":{
      "self": "http://gitlab.example.com/api/v4/groups/7/epics/4",
      "epic_issues": "http://gitlab.example.com/api/v4/groups/7/epics/4/issues",
      "group":"http://gitlab.example.com/api/v4/groups/7",
      "parent":"http://gitlab.example.com/api/v4/groups/7/epics/3"
  }
  },
  {
  "id": 50,
  "iid": 35,
  "group_id": 17,
  "parent_id": 19,
  "parent_iid": 1,
  "title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.",
  "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
  "state": "opened",
  "web_url": "http://gitlab.example.com/groups/test/sample/-/epics/35",
  "reference": "&4",
  "references": {
    "short": "&4",
    "relative": "sample&4",
    "full": "test/sample&4"
  },
  "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://gitlab.example.com/kam"
  },
  "start_date": null,
  "start_date_is_fixed": false,
  "start_date_fixed": null,
  "start_date_from_milestones": null,       //deprecated in favor of start_date_from_inherited_source
  "start_date_from_inherited_source": null,
  "end_date": "2018-07-31",                 //deprecated in favor of due_date
  "due_date": "2018-07-31",
  "due_date_is_fixed": false,
  "due_date_fixed": null,
  "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
  "due_date_from_inherited_source": "2018-07-31",
  "created_at": "2018-07-17T13:36:22.770Z",
  "updated_at": "2018-07-18T12:22:05.239Z",
  "closed_at": "2018-08-18T12:22:05.239Z",
  "imported": false,
  "imported_from": "none",
  "labels": [],
  "upvotes": 4,
  "downvotes": 0,
  "color": "#1068bf",
  "_links":{
      "self": "http://gitlab.example.com/api/v4/groups/17/epics/35",
      "epic_issues": "http://gitlab.example.com/api/v4/groups/17/epics/35/issues",
      "group":"http://gitlab.example.com/api/v4/groups/17",
      "parent":"http://gitlab.example.com/api/v4/groups/17/epics/1"
  }
  }
]

单个史诗

获取单个史诗

GET /groups/:id/epics/:epic_iid
属性 类型 必需 描述
id integer/string 是 群组的 ID 或 URL 编码路径
epic_iid integer/string 是 史诗的内部 ID。 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5"

示例响应：

{
  "id": 30,
  "iid": 5,
  "group_id": 7,
  "parent_id": null,
  "parent_iid": null,
  "title": "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.",
  "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
  "state": "opened",
  "imported": false,
  "imported_from": "none",
  "web_url": "http://gitlab.example.com/groups/test/-/epics/5",
  "reference": "&5",
  "references": {
    "short": "&5",
    "relative": "&5",
    "full": "test&5"
  },
  "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://gitlab.example.com/arnita"
  },
  "start_date": null,
  "start_date_is_fixed": false,
  "start_date_fixed": null,
  "start_date_from_milestones": null,       //deprecated in favor of start_date_from_inherited_source
  "start_date_from_inherited_source": null,
  "end_date": "2018-07-31",                 //deprecated in favor of due_date
  "due_date": "2018-07-31",
  "due_date_is_fixed": false,
  "due_date_fixed": null,
  "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
  "due_date_from_inherited_source": "2018-07-31",
  "created_at": "2018-07-17T13:36:22.770Z",
  "updated_at": "2018-07-18T12:22:05.239Z",
  "closed_at": "2018-08-18T12:22:05.239Z",
  "labels": [],
  "upvotes": 4,
  "downvotes": 0,
  "color": "#1068bf",
  "subscribed": true,
  "_links":{
      "self": "http://gitlab.example.com/api/v4/groups/7/epics/5",
      "epic_issues": "http://gitlab.example.com/api/v4/groups/7/epics/5/issues",
      "group":"http://gitlab.example.com/api/v4/groups/7",
      "parent": null
  }
}

新建史诗

创建一个新史诗。

{{< alert type=”note” >}}

从极狐GitLab 11.3 开始，start_date 和 end_date 不再应直接分配，因为它们现在表示复合值。您可以通过 *_is_fixed 和 *_fixed 字段进行配置。

{{< /alert >}}

POST /groups/:id/epics
属性 类型 必需 描述
id integer/string 是 群组的 ID 或 URL 编码路径
title string 是 史诗的标题
labels string 否 用逗号分隔的标签列表
description string 否 史诗的描述。限制为 1,048,576 个字符。
color string 否 史诗的颜色。位于名为 epic_highlight_color 的功能标志后面（默认禁用）
confidential boolean 否 史诗是否应为保密
created_at string 否 史诗创建时间。日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z 。需要管理员或项目/群组所有者权限
start_date_is_fixed boolean 否 开始日期是否应从 start_date_fixed 或里程碑中获取
start_date_fixed string 否 史诗的固定开始日期
due_date_is_fixed boolean 否 截止日期是否应从 due_date_fixed 或里程碑中获取
due_date_fixed string 否 史诗的固定截止日期
parent_id integer/string 否 父史诗的 ID 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics?title=Epic&description=Epic%20description&parent_id=29"

示例响应：

{
  "id": 33,
  "iid": 6,
  "group_id": 7,
  "parent_id": 29,
  "parent_iid": 4,
  "title": "Epic",
  "description": "Epic description",
  "state": "opened",
  "imported": false,
  "imported_from": "none",
  "confidential": "false",
  "web_url": "http://gitlab.example.com/groups/test/-/epics/6",
  "reference": "&6",
  "references": {
    "short": "&6",
    "relative": "&6",
    "full": "test&6"
  },
  "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,
  "start_date_is_fixed": false,
  "start_date_fixed": null,
  "start_date_from_milestones": null,       //deprecated in favor of start_date_from_inherited_source
  "start_date_from_inherited_source": null,
  "end_date": "2018-07-31",                 //deprecated in favor of due_date
  "due_date": "2018-07-31",
  "due_date_is_fixed": false,
  "due_date_fixed": null,
  "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
  "due_date_from_inherited_source": "2018-07-31",
  "created_at": "2018-07-17T13:36:22.770Z",
  "updated_at": "2018-07-18T12:22:05.239Z",
  "closed_at": "2018-08-18T12:22:05.239Z",
  "labels": [],
  "upvotes": 4,
  "downvotes": 0,
  "color": "#1068bf",
  "_links":{
    "self": "http://gitlab.example.com/api/v4/groups/7/epics/6",
    "epic_issues": "http://gitlab.example.com/api/v4/groups/7/epics/6/issues",
    "group":"http://gitlab.example.com/api/v4/groups/7",
    "parent": "http://gitlab.example.com/api/v4/groups/7/epics/4"
  }
}

更新史诗

更新史诗。

PUT /groups/:id/epics/:epic_iid
属性 类型 必需 描述
id integer/string 是 群组的 ID 或 URL 编码路径
epic_iid integer/string 是 史诗的内部 ID
add_labels string 否 要添加到议题的用逗号分隔的标签名称。
confidential boolean 否 史诗是否应为保密
description string 否 史诗的描述。限制为 1,048,576 个字符。
due_date_fixed string 否 史诗的固定截止日期
due_date_is_fixed boolean 否 截止日期是否应从 due_date_fixed 或里程碑中获取
labels string 否 议题的用逗号分隔的标签名称。设置为空字符串以取消分配所有标签。
parent_id integer/string 否 父史诗的 ID。
remove_labels string 否 要从议题中删除的用逗号分隔的标签名称。
start_date_fixed string 否 史诗的固定开始日期
start_date_is_fixed boolean 否 开始日期是否应从 start_date_fixed 或里程碑中获取
state_event string 否 史诗的状态事件。设置 close 以关闭史诗，设置 reopen 以重新打开它
title string 否 史诗的标题
updated_at string 否 史诗更新的时间。日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z 。需要管理员或项目/群组所有者权限
color string 否 史诗的颜色。位于名为 epic_highlight_color 的功能标志后面（默认禁用） 
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5?title=New%20Title&parent_id=29"

示例响应：

{
  "id": 33,
  "iid": 6,
  "group_id": 7,
  "parent_id": 29,
  "parent_iid": 4,
  "title": "New Title",
  "description": "Epic description",
  "state": "opened",
  "imported": false,
  "imported_from": "none",
  "confidential": "false",
  "web_url": "http://gitlab.example.com/groups/test/-/epics/6",
  "reference": "&6",
  "references": {
    "short": "&6",
    "relative": "&6",
    "full": "test&6"
  },
  "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,
  "start_date_is_fixed": false,
  "start_date_fixed": null,
  "start_date_from_milestones": null,       //deprecated in favor of start_date_from_inherited_source
  "start_date_from_inherited_source": null,
  "end_date": "2018-07-31",                 //deprecated in favor of due_date
  "due_date": "2018-07-31",
  "due_date_is_fixed": false,
  "due_date_fixed": null,
  "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
  "due_date_from_inherited_source": "2018-07-31",
  "created_at": "2018-07-17T13:36:22.770Z",
  "updated_at": "2018-07-18T12:22:05.239Z",
  "closed_at": "2018-08-18T12:22:05.239Z",
  "labels": [],
  "upvotes": 4,
  "downvotes": 0,
  "color": "#1068bf"
}

删除史诗

{{< history >}}

  • 在极狐GitLab 16.11 中发生变更。在 16.11 及更早版本中，如果你删除了史诗，其所有子史诗和它们的子代也会被删除。如果需要，你可以在你将其删除之前从父史诗删除子史诗。

{{< /history >}}

删除一个史诗

DELETE /groups/:id/epics/:epic_iid
属性 类型 必需 描述
id integer/string 是 群组的 ID 或 URL 编码路径
epic_iid integer/string 是 史诗的内部 ID。 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5"

创建待办事项

手动为当前用户在史诗上创建待办事项。如果用户在该史诗上已经存在待办事项，则返回状态码 304。

POST /groups/:id/epics/:epic_iid/todo
属性 类型 必需 描述
id integer/string 是 群组的 ID 或 URL 编码路径
epic_iid integer 是 群组史诗的内部 ID 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5/todo"

示例响应：

{
  "id": 112,
  "group": {
    "id": 1,
    "name": "Gitlab",
    "path": "gitlab",
    "kind": "group",
    "full_path": "base/gitlab",
    "parent_id": null
  },
  "author": {
    "name": "Administrator",
    "username": "root",
    "id": 1,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/root"
  },
  "action_name": "marked",
  "target_type": "epic",
  "target": {
    "id": 30,
    "iid": 5,
    "group_id": 1,
    "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://gitlab.example.com/arnita"
    },
    "web_url": "http://gitlab.example.com/groups/test/-/epics/5",
    "reference": "&5",
    "references": {
      "short": "&5",
      "relative": "&5",
      "full": "test&5"
    },
    "start_date": null,
    "end_date": null,
    "created_at": "2018-01-21T06:21:13.165Z",
    "updated_at": "2018-01-22T12:41:41.166Z",
    "closed_at": "2018-08-18T12:22:05.239Z"
  },
  "target_url": "https://gitlab.example.com/groups/epics/5",
  "body": "Vel voluptas atque dicta mollitia adipisci qui at.",
  "state": "pending",
  "created_at": "2016-07-01T11:09:13.992Z"
}