正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

エピックAPI（非推奨）

  • プラン: Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

エピックREST APIはGitLab 17.0で非推奨になり、APIのv5で削除される予定です。GitLab 17.4から18.0までのバージョンで、エピックの新しい外観が有効になっている場合は、GitLab 18.1以降で、代わりに作業アイテムAPIを使用してください。詳細については、作業アイテムにエピックAPIを移行するを参照してください。これは破壊的な変更です。

エピックへのすべてのAPIコールは認証する必要があります。

ユーザーがプライベートグループのメンバーでない場合、そのグループへのGETリクエストは404ステータスコードを返します。

エピック機能が利用できない場合、403ステータスコードが返されます。

従来のエピックIDとWorkItem ID

従来のエピックIDはWorkItem IDと同じではありません。iidのみが一致します。ただし、エピックに対応するWorkItem IDを取得するには、レスポンスにwork_item_idが含まれます。

このIDはWorkItem GraphQL APIで使用できます。例えば、work_item_idはWorkItem GraphQL API上でGlobal ID gid://gitlab/WorkItem/123となります。

エピックイシューAPI

The エピックイシューAPIを使用すると、エピックに関連付けられたイシューを操作できます。

マイルストーン日付インテグレーション

開始日と期日は関連するイシューのマイルストーンから動的に取得できるため、ユーザーが編集権限を持っている場合に限り、追加のフィールドが表示されます。これらには、2つのブール型フィールドstart_date_is_fixedとdue_date_is_fixed、および4つの日付フィールドstart_date_fixed、start_date_from_inherited_source、due_date_fixed、due_date_from_inherited_sourceが含まれます。

  • due_dateを優先して、end_dateは非推奨になりました。
  • start_date_from_milestonesは、start_date_from_inherited_sourceに非推奨となりました。
  • due_date_from_milestonesは、due_date_from_inherited_sourceに非推奨となりました。

すべてのグループエピックを一覧表示

指定されたグループとそのサブグループのすべてのエピックを一覧表示します。

レスポンスはページ付けされています。デフォルトでは20件の結果が返されます。

references.relativeは、エピックがリクエストされているグループに対して相対的です。エピックがそのoriginグループからフェッチされる場合、relative形式はshort形式と同じです。エピックが複数のグループにわたってリクエストされる場合、relative形式はfull形式と同じであると想定されます。

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整数または文字列はいグループのIDまたはURLエンコードされたパス
author_id整数いいえ指定されたユーザーidによって作成されたエピックを返します。
author_username文字列いいえ指定されたusernameを持つユーザーによって作成されたエピックを返します。
labels文字列いいえコンマ区切りのラベル名リストに一致するエピックを返します。エピックグループまたは親グループのラベル名を使用できます。
with_labels_detailsブール値いいえtrueの場合、レスポンスではラベルフィールドの各ラベルに関する詳細（:name、:color、:description、:description_html、:text_color）が返されます。デフォルトはfalseです。
order_by文字列いいえcreated_at、updated_at、またはtitleフィールドで並べ替えられたエピックを返します。デフォルトはcreated_atです。
sort文字列いいえascまたはdescの順序でソートされたエピックを返します。デフォルトはdescです。
search文字列いいえエピックのtitleとdescriptionに対して検索します。
state文字列いいえエピックのstateに対して検索します。可能なフィルター: opened、closed、all。デフォルト: all
created_after日時いいえ指定された時刻以降に作成されたエピックを返します。ISO 8601形式（2019-03-15T08:00:00Z）で指定します。
created_before日時いいえ指定された時刻以前に作成されたエピックを返します。ISO 8601形式（2019-03-15T08:00:00Z）で指定します。
updated_after日時いいえ指定された時刻以降に更新されたエピックを返します。ISO 8601形式（2019-03-15T08:00:00Z）で指定します。
updated_before日時いいえ指定された時刻以前に更新されたエピックを返します。ISO 8601形式（2019-03-15T08:00:00Z）で指定します。
include_ancestor_groupsブール値いいえリクエストされたグループの祖先からのエピックを含めます。デフォルトはfalseです。
include_descendant_groupsブール値いいえリクエストされたグループの子孫からのエピックを含めます。デフォルトはtrueです。
my_reaction_emoji文字列いいえ認証済みユーザーによって指定された絵文字でリアクションされたエピックを返します。Noneはリアクションが付けられていないエピックを返します。Anyは少なくとも1つのリアクションが付けられたエピックを返します。
notハッシュいいえ指定されたパラメータに一致しないエピックを返します。以下を受け入れます: author_id、author_username、labels。
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/epics"

レスポンス例:

[
  {
  "id": 29,
  "work_item_id": 1032,
  "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,
  "work_item_id": 1035,
  "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整数または文字列はいグループのIDまたはURLエンコードされたパス
epic_iid整数または文字列はいエピックの内部ID。
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/epics/5"

レスポンス例:

{
  "id": 30,
  "work_item_id": 1099,
  "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
  }
}

エピックを作成する

指定されたグループにエピックを作成します。

GitLab 11.3以降、start_dateとend_dateは複合値を表すようになったため、直接割り当てるべきではありません。代わりに*_is_fixedと*_fixedフィールドを介して設定できます。

POST /groups/:id/epics
属性型必須説明
id整数または文字列はいグループのIDまたはURLエンコードされたパス
title文字列はいエピックのタイトル
labels文字列いいえコンマ区切りのラベルリスト
description文字列いいえエピックの説明。1,048,576文字に制限されています。
color文字列いいえエピックの色。epic_highlight_colorという機能フラグの背後にあります（デフォルトで無効）。
confidentialブール値いいえそのエピックが機密であるべきかどうか
created_at文字列いいえエピックが作成された日時。日付時刻文字列、ISO 8601形式。例: 2016-03-11T03:45:40Z。管理者またはプロジェクト/グループオーナーの権限が必要です。
start_date_is_fixedブール値いいえ開始日がstart_date_fixedから取得されるべきか、またはマイルストーンから取得されるべきか。
start_date_fixed文字列いいえエピックの固定開始日。
due_date_is_fixedブール値いいえ期日がdue_date_fixedから取得されるべきか、またはマイルストーンから取得されるべきか。
due_date_fixed文字列いいえエピックの固定期日。
parent_id整数または文字列いいえ親エピックのID
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/epics?title=Epic&description=Epic%20description&parent_id=29"

レスポンス例:

{
  "id": 33,
  "work_item_id": 1020,
  "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整数または文字列はいグループのIDまたはURLエンコードされたパス
epic_iid整数または文字列はいエピックの内部ID
add_labels文字列いいえイシューに追加するラベル名のカンマ区切りリスト。
confidentialブール値いいえそのエピックが機密であるべきかどうか
description文字列いいえエピックの説明。1,048,576文字に制限されています。
due_date_fixed文字列いいえエピックの固定期日。
due_date_is_fixedブール値いいえ期日がdue_date_fixedから取得されるべきか、またはマイルストーンから取得されるべきか。
labels文字列いいえイシューのラベル名のカンマ区切りリスト。すべてのラベルの割り当てを解除するには、空の文字列を設定します。
parent_id整数または文字列いいえ親エピックのID。
remove_labels文字列いいえイシューから削除するラベル名のカンマ区切りリスト。
start_date_fixed文字列いいえエピックの固定開始日。
start_date_is_fixedブール値いいえ開始日がstart_date_fixedから取得されるべきか、またはマイルストーンから取得されるべきか。
state_event文字列いいえエピックのステートイベント。closeを設定してエピックをクローズし、reopenを設定して再オープンします。
title文字列いいえエピックのタイトル
updated_at文字列いいえエピックが更新された日時。日付時刻文字列、ISO 8601形式。例: 2016-03-11T03:45:40Z。管理者またはプロジェクト/グループオーナーの権限が必要です。
color文字列いいえエピックの色。epic_highlight_colorという機能フラグの背後にあります（デフォルトで無効）。
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/epics/5?title=New%20Title&parent_id=29"

レスポンス例:

{
  "id": 33,
  "work_item_id": 1019,
  "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"
}

エピックを削除する

指定されたグループからエピックを削除します。

DELETE /groups/:id/epics/:epic_iid
属性型必須説明
id整数または文字列はいグループのIDまたはURLエンコードされたパス
epic_iid整数または文字列はいエピックの内部ID。
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/epics/5"

エピックのTo-Doアイテムを作成する

指定されたエピックで現在のユーザーのTo-Doアイテムを作成します。そのエピックでユーザーのTo-Doアイテムがすでに存在する場合、ステータスコード304が返されます。

POST /groups/:id/epics/:epic_iid/todo
属性型必須説明
id整数または文字列はいグループのIDまたはURLエンコードされたパス
epic_iid整数はいグループのエピックの内部ID
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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"
}