正式なドキュメントは英語版であり、この日本語訳は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ステータスcodeが返されます。

従来のエピックIDとWorkItem ID

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

このIDはWorkItem GraphQL APIに使用できます。例：work_item_idはWorkItem GraphQL APIのグローバルID gid://gitlab/WorkItem/123になります。

エピックイシューAPI

エピックイシュー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_inherited_sourceを優先して、start_date_from_milestonesは非推奨になりました。
  • due_date_from_inherited_sourceを優先して、due_date_from_milestonesは非推奨になりました。

エピックのページネーション

APIの結果はページネーションされるため、デフォルトでは、GETリクエストは一度に20件の結果を返します。

詳細については、ページネーションを参照してください。

GitLab 12.6以降、レスポンスのreference属性は、referencesの代わりに非推奨になりました。

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というfeature flag（デフォルトでは無効）の背後
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というfeature flag（デフォルトでは無効）の背後
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"
}