エピックAPI

エピックへの API 呼び出しはすべて認証が必要です。

ユーザーが非公開グループのメンバーでない場合、そのグループに対するGET リクエストは404 ステータスコードになります。

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

エピック課題API

エピック・イシューAPIでは、エピックに関連するイシューとやり取りすることができます。

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

GitLab 11.3で導入されました。

開始日と期限日は関連するイシューのマイルストーンから動的に取得できるため、ユーザーに編集権限がある場合、追加のフィールドが表示されます。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 が含まれます。

  • end_date は非推奨となり、due_date に変更されました。
  • start_date_from_milestones は非推奨となりstart_date_from_inherited_source
  • due_date_from_milestones は非推奨となりdue_date_from_inherited_source

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

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

ページ分割についての詳細はこちらをご覧ください。

caution
GitLab 12.6以降では、レスポンスのreference 属性は廃止され、references.
note
references.relative は、エピックがリクエストされたグループからの相対パスです。エピックがオリジンのグループから取得される場合、relative 形式はshort 形式と同じです。エピックがグループ間でリクエストされる場合、relative 形式はfull 形式と同じであることが期待されます。

グループのエピック一覧

parent_iid と_links[parent] のレスポンスは GitLab 14.6 で導入されました。

要求されたグループとそのサブグループのすべてのエピックを取得します。

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整数/文字列yes認証ユーザーが所有するグループのIDまたはURLエンコードされたパス
author_id整数。いいえ指定されたユーザーが作成したエピックを返します。id
author_username文字列です。いいえ与えられたusername でユーザーが作成したエピックを返します。GitLab 14.7以降で利用可能です。
labels文字列です。いいえカンマで区切られたラベル名のリストにマッチするエピックを返します。エピックグループまたは親グループのラベル名を使用できます。
with_labels_detailsbooleanいいえ true の場合、labels フィールドの各ラベルの詳細を返します：:name :color,:description,:description_html,:text_color.デフォルトはfalse。GitLab 12.7以降で利用可能。
order_by文字列です。いいえ created_at 、updated_at 、title フィールドの順に並べたエピックを返します。デフォルトはcreated_at
sort文字列です。いいえ asc またはdesc 順序で descソートされたエピックを返しますdesc 。デフォルトは desc
search文字列です。いいえエピックはtitle と照らし合わせて検索してください。description
state文字列です。いいえ stateに対してエピックを検索します：opened closed とall, デフォルト all：
created_afterdatetimeいいえ指定された時刻以降に作成されたエピックを返します。ISO 8601 形式 (2019-03-15T08:00:00Z) で返されます。
created_beforedatetimeいいえ指定された時刻以前に作成されたエピックを返します。ISO 8601 形式 (2019-03-15T08:00:00Z) で返されます。
updated_afterdatetimeいいえ指定された時刻以降に更新されたエピックを返します。ISO 8601 形式で期待される形式 (2019-03-15T08:00:00Z)
updated_beforedatetimeいいえ指定された時刻以前に更新されたエピックを返します。ISO 8601 形式 (2019-03-15T08:00:00Z) で返されます。
include_ancestor_groupsbooleanいいえ要求されたグループの祖先からのエピックも含めます。デフォルトはfalse
include_descendant_groupsbooleanいいえ要求されたグループの子孫のエピックも含めます。デフォルトはtrue
my_reaction_emoji文字列です。いいえ認証されたユーザーが指定された絵文字でリアクションしたエピックを返します。None リアクションが与えられていないエピックを返します。Any 少なくとも1つのリアクションが与えられたエピックを返します。GitLab 13.0以降で利用可能です。
notハッシュいいえ与えられたパラメータにマッチしないエピックを返します。使えます：author_id,author_username (GitLab 14.7以降) とlabels 。GitLab 14.6以降で利用可能。
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",
  "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"
  }
  }
]

シングルエピック

parent_iid と_links[parent] のレスポンスは GitLab 14.6 で導入されました。

単一のエピック

GET /groups/:id/epics/:epic_iid
属性種類必須説明
id整数/文字列yes認証ユーザーが所有するグループのIDまたはURLエンコードされたパス
epic_iid整数/文字列yesエピック内部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",
  "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
  }
}

新しいエピック

parent_iid と_links[parent] のレスポンスは GitLab 14.6 で導入されました。

新しいエピックを作成します。

note
GitLab11.3から、start_date とend_date は複合値を表すようになったため、直接割り当てられないようになりました。代わりに*_is_fixed と*_fixed フィールドで設定できます。
POST /groups/:id/epics
属性種類必須説明
id整数/文字列yes認証ユーザーが所有するグループのIDまたはURLエンコードされたパス
title文字列です。yesエピックのタイトル
labels文字列です。いいえカンマで区切られたラベルのリスト
description文字列です。いいえエピックについての説明。1,048,576文字まで。
color文字列です。いいえエピックの色。GitLab 14.8 で導入され、epic_highlight_color という機能フラグの背後にあります (デフォルトでは無効)。
confidentialbooleanいいえエピックの機密性の有無
created_at文字列です。いいえエピックが作成された日時。ISO 8601形式の日付時刻文字列、例：2016-03-11T03:45:40Z 。管理者またはプロジェクト/グループオーナー権限が必要(GitLab 13.5 以降で利用可能)
start_date_is_fixedbooleanいいえ開始日をstart_date_fixed から取得するか、マイルストーンから取得するか (GitLab 11.3 以降)
start_date_fixed文字列です。いいえエピックの固定開始日(GitLab 11.3以降)
due_date_is_fixedbooleanいいえ期日をdue_date_fixed から取得するかマイルストーンから取得するか (GitLab 11.3 以降)
due_date_fixed文字列です。いいえエピック（GitLab 11.3以降）の固定期限日
parent_id整数/文字列いいえ親エピックのID (GitLab 11.11以降)
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",
  "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"
  }
}

エピック更新

parent_iid と_links[parent] のレスポンスは GitLab 14.6 で導入されました。

エピックを更新しました。

note
GitLab11.3から、start_date とend_date は複合値を表すようになったため、直接割り当てられないようになりました。代わりに*_is_fixed と*_fixed フィールドで設定できます。
PUT /groups/:id/epics/:epic_iid
属性種類必須説明
id整数/文字列yes認証ユーザーが所有するグループのIDまたはURLエンコードされたパス
epic_iid整数/文字列yesエピック内部ID
add_labels文字列です。いいえイシューに追加するラベル名をカンマ区切りで指定します。
confidentialbooleanいいえエピックの機密性の有無
description文字列です。いいえエピックについての説明。1,048,576文字まで。
due_date_fixed文字列です。いいえエピック（GitLab 11.3以降）の固定期限日
due_date_is_fixedbooleanいいえ期日をdue_date_fixed から取得するかマイルストーンから取得するか (GitLab 11.3 以降)
labels文字列です。いいえイシューのラベル名をカンマ区切りで指定します。すべてのラベルの割り当てを解除するには空文字列を設定します。
parent_id整数/文字列いいえ親エピックのID。GitLab 14.6以降で利用可能。
remove_labels文字列です。いいえイシューから削除するラベル名をカンマ区切りで指定します。
start_date_fixed文字列です。いいえエピックの固定開始日(GitLab 11.3以降)
start_date_is_fixedbooleanいいえ開始日をstart_date_fixed から取得するか、マイルストーンから取得するか (GitLab 11.3 以降)
state_event文字列です。いいえエピックの状態イベント。close を設定するとエピックが閉じ、reopen を設定するとエピックが再び開きます（GitLab 11.4 以降）。
title文字列です。いいえエピックのタイトル
updated_at文字列です。いいえエピックが更新された日時。ISO 8601形式の日付時刻文字列、例えば2016-03-11T03:45:40Z 。管理者またはプロジェクト/グループオーナー権限が必要(GitLab 13.5 以降で利用可能)
color文字列です。いいえエピックの色。GitLab 14.8 で導入され、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",
  "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整数/文字列yes認証ユーザーが所有するグループのIDまたはURLエンコードされたパス
epic_iid整数/文字列yesエピック内部ID。
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5"

To-Do 項目の作成

エピック上の現在のユーザーの To-Do 項目を手動で作成します。そのエピックにユーザーのToDo項目が既に存在する場合、ステータスコード304 が返されます。

POST /groups/:id/epics/:epic_iid/todo
属性種類必須説明
id整数/文字列yes認証ユーザーが所有するグループのIDまたはURLエンコードされたパス
epic_iid整数。yesグループのエピック内部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"
}