Discussions API

Discussions are set of related notes on snippets, issues, epics, merge requests or commits.

This includes system notes, which are notes about changes to the object (for example, when a milestone changes, there will be a corresponding system note). Label notes are not part of this API, but recorded as separate events in resource label events.

Discussions pagination

By default, GET requests return 20 results at a time because the API results are paginated.

Read more on pagination.

Issues

List project issue discussions

Gets a list of all discussions for a single issue.

GET /projects/:id/issues/:issue_iid/discussions
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
issue_iid integer yes The IID of an issue
[
  {
    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
    "individual_note": false,
    "notes": [
      {
        "id": 1126,
        "type": "DiscussionNote",
        "body": "discussion text",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-03T21:54:39.668Z",
        "updated_at": "2018-03-03T21:54:39.668Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Issue",
        "noteable_iid": null
      },
      {
        "id": 1129,
        "type": "DiscussionNote",
        "body": "reply to the discussion",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T13:38:02.127Z",
        "updated_at": "2018-03-04T13:38:02.127Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Issue",
        "noteable_iid": null,
        "resolvable": false
      }
    ]
  },
  {
    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
    "individual_note": true,
    "notes": [
      {
        "id": 1128,
        "type": null,
        "body": "a single comment",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T09:17:22.520Z",
        "updated_at": "2018-03-04T09:17:22.520Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Issue",
        "noteable_iid": null,
        "resolvable": false
      }
    ]
  }
]
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions

Get single issue discussion

Returns a single discussion for a specific project issue

GET /projects/:id/issues/:issue_iid/discussions/:discussion_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
issue_iid integer yes The IID of an issue
discussion_id integer yes The ID of a discussion
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7

Create new issue discussion

Creates a new discussion to a single project issue. This is similar to creating a note but other comments (replies) can be added to it later.

POST /projects/:id/issues/:issue_iid/discussions

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
issue_iid integer yes The IID of an issue
body string yes The content of a discussion
created_at string no Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights)
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment

Add note to existing issue discussion

Adds a new note to the discussion. This can also create a discussion from a single comment.

POST /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
issue_iid integer yes The IID of an issue
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
body string yes The content of a discussion
created_at string no Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights)
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment

Modify existing issue discussion note

Modify existing discussion note of an issue.

PUT /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes/:note_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
issue_iid integer yes The IID of an issue
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
body string yes The content of a discussion
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment

Delete an issue discussion note

Deletes an existing discussion note of an issue.

DELETE /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes/:note_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
issue_iid integer yes The IID of an issue
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636

Snippets

List project snippet discussions

Gets a list of all discussions for a single snippet.

GET /projects/:id/snippets/:snippet_id/discussions
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
snippet_id integer yes The ID of an snippet
[
  {
    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
    "individual_note": false,
    "notes": [
      {
        "id": 1126,
        "type": "DiscussionNote",
        "body": "discussion text",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-03T21:54:39.668Z",
        "updated_at": "2018-03-03T21:54:39.668Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Snippet",
        "noteable_id": null
      },
      {
        "id": 1129,
        "type": "DiscussionNote",
        "body": "reply to the discussion",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T13:38:02.127Z",
        "updated_at": "2018-03-04T13:38:02.127Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Snippet",
        "noteable_id": null,
        "resolvable": false
      }
    ]
  },
  {
    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
    "individual_note": true,
    "notes": [
      {
        "id": 1128,
        "type": null,
        "body": "a single comment",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T09:17:22.520Z",
        "updated_at": "2018-03-04T09:17:22.520Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Snippet",
        "noteable_id": null,
        "resolvable": false
      }
    ]
  }
]
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions

Get single snippet discussion

Returns a single discussion for a specific project snippet

GET /projects/:id/snippets/:snippet_id/discussions/:discussion_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
snippet_id integer yes The ID of an snippet
discussion_id integer yes The ID of a discussion
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7

Create new snippet discussion

Creates a new discussion to a single project snippet. This is similar to creating a note but other comments (replies) can be added to it later.

POST /projects/:id/snippets/:snippet_id/discussions

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
snippet_id integer yes The ID of an snippet
body string yes The content of a discussion
created_at string no Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights)
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment

Add note to existing snippet discussion

Adds a new note to the discussion.

POST /projects/:id/snippets/:snippet_id/discussions/:discussion_id/notes

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
snippet_id integer yes The ID of an snippet
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
body string yes The content of a discussion
created_at string no Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights)
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment

Modify existing snippet discussion note

Modify existing discussion note of an snippet.

PUT /projects/:id/snippets/:snippet_id/discussions/:discussion_id/notes/:note_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
snippet_id integer yes The ID of an snippet
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
body string yes The content of a discussion
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment

Delete an snippet discussion note

Deletes an existing discussion note of an snippet.

DELETE /projects/:id/snippets/:snippet_id/discussions/:discussion_id/notes/:note_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
snippet_id integer yes The ID of an snippet
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636

Epics

List group epic discussions

Gets a list of all discussions for a single epic.

GET /groups/:id/epics/:epic_id/discussions
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group
epic_id integer yes The ID of an epic
[
  {
    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
    "individual_note": false,
    "notes": [
      {
        "id": 1126,
        "type": "DiscussionNote",
        "body": "discussion text",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-03T21:54:39.668Z",
        "updated_at": "2018-03-03T21:54:39.668Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Epic",
        "noteable_id": null,
        "resolvable": false
      },
      {
        "id": 1129,
        "type": "DiscussionNote",
        "body": "reply to the discussion",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T13:38:02.127Z",
        "updated_at": "2018-03-04T13:38:02.127Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Epic",
        "noteable_id": null,
        "resolvable": false
      }
    ]
  },
  {
    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
    "individual_note": true,
    "notes": [
      {
        "id": 1128,
        "type": null,
        "body": "a single comment",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T09:17:22.520Z",
        "updated_at": "2018-03-04T09:17:22.520Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Epic",
        "noteable_id": null,
        "resolvable": false
      }
    ]
  }
]
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/epics/11/discussions

Get single epic discussion

Returns a single discussion for a specific group epic

GET /groups/:id/epics/:epic_id/discussions/:discussion_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group
epic_id integer yes The ID of an epic
discussion_id integer yes The ID of a discussion
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7

Create new epic discussion

Creates a new discussion to a single group epic. This is similar to creating a note but but another comments (replies) can be added to it later.

POST /groups/:id/epics/:epic_id/discussions

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group
epic_id integer yes The ID of an epic
body string yes The content of a discussion
created_at string no Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights)
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/epics/11/discussions?body=comment

Add note to existing epic discussion

Adds a new note to the discussion. This can also create a discussion from a single comment.

POST /groups/:id/epics/:epic_id/discussions/:discussion_id/notes

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group
epic_id integer yes The ID of an epic
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
body string yes The content of a discussion
created_at string no Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights)
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment

Modify existing epic discussion note

Modify existing discussion note of an epic.

PUT /groups/:id/epics/:epic_id/discussions/:discussion_id/notes/:note_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group
epic_id integer yes The ID of an epic
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
body string yes The content of a discussion
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment

Delete an epic discussion note

Deletes an existing discussion note of an epic.

DELETE /groups/:id/epics/:epic_id/discussions/:discussion_id/notes/:note_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group
epic_id integer yes The ID of an epic
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/636

Merge requests

List project merge request discussions

Gets a list of all discussions for a single merge request.

GET /projects/:id/merge_requests/:merge_request_iid/discussions
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
merge_request_iid integer yes The IID of a merge request
[
  {
    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
    "individual_note": false,
    "notes": [
      {
        "id": 1126,
        "type": "DiscussionNote",
        "body": "discussion text",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-03T21:54:39.668Z",
        "updated_at": "2018-03-03T21:54:39.668Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Merge request",
        "noteable_iid": null,
        "resolved": false,
        "resolvable": true,
        "resolved_by": null
      },
      {
        "id": 1129,
        "type": "DiscussionNote",
        "body": "reply to the discussion",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T13:38:02.127Z",
        "updated_at": "2018-03-04T13:38:02.127Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Merge request",
        "noteable_iid": null,
        "resolved": false,
        "resolvable": true,
        "resolved_by": null
      }
    ]
  },
  {
    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
    "individual_note": true,
    "notes": [
      {
        "id": 1128,
        "type": null,
        "body": "a single comment",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T09:17:22.520Z",
        "updated_at": "2018-03-04T09:17:22.520Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Merge request",
        "noteable_iid": null,
        "resolved": false,
        "resolvable": true,
        "resolved_by": null
      }
    ]
  }
]

Diff comments contain also position:

[
  {
    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
    "individual_note": false,
    "notes": [
      {
        "id": 1128,
        "type": DiffNote,
        "body": "diff comment",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T09:17:22.520Z",
        "updated_at": "2018-03-04T09:17:22.520Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Merge request",
        "noteable_iid": null,
        "position": {
          "base_sha": "b5d6e7b1613fca24d250fa8e5bc7bcc3dd6002ef",
          "start_sha": "7c9c2ead8a320fb7ba0b4e234bd9529a2614e306",
          "head_sha": "4803c71e6b1833ca72b8b26ef2ecd5adc8a38031",
          "old_path": "package.json",
          "new_path": "package.json",
          "position_type": "text",
          "old_line": 27,
          "new_line": 27
        },
        "resolved": false,
        "resolvable": true,
        "resolved_by": null
      }
    ]
  }
]
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions

Get single merge request discussion

Returns a single discussion for a specific project merge request

GET /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
merge_request_iid integer yes The IID of a merge request
discussion_id integer yes The ID of a discussion
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7

Create new merge request discussion

Creates a new discussion to a single project merge request. This is similar to creating a note but other comments (replies) can be added to it later.

POST /projects/:id/merge_requests/:merge_request_iid/discussions

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
merge_request_iid integer yes The IID of a merge request
body string yes The content of a discussion
created_at string no Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights)
position hash no Position when creating a diff note
position[base_sha] string yes Base commit SHA in the source branch
position[start_sha] string yes SHA referencing commit in target branch
position[head_sha] string yes SHA referencing HEAD of this merge request
position[position_type] string yes Type of the position reference’, allowed values: ‘text’ or ‘image’
position[new_path] string no File path after change
position[new_line] integer no Line number after change (for ‘text’ diff notes)
position[old_path] string no File path before change
position[old_line] integer no Line number before change (for ‘text’ diff notes)
position[width] integer no Width of the image (for ‘image’ diff notes)
position[height] integer no Height of the image (for ‘image’ diff notes)
position[x] integer no X coordinate (for ‘image’ diff notes)
position[y] integer no Y coordinate (for ‘image’ diff notes)
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment

Resolve a merge request discussion

Resolve/unresolve whole discussion of a merge request.

PUT /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
merge_request_iid integer yes The IID of a merge request
discussion_id integer yes The ID of a discussion
resolved boolean yes Resolve/unresolve the discussion
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7?resolved=true

Add note to existing merge request discussion

Adds a new note to the discussion. This can also create a discussion from a single comment.

POST /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id/notes

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
merge_request_iid integer yes The IID of a merge request
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
body string yes The content of a discussion
created_at string no Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights)
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment

Modify an existing merge request discussion note

Modify or resolve an existing discussion note of a merge request.

PUT /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id/notes/:note_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
merge_request_iid integer yes The IID of a merge request
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
body string no The content of a discussion (exactly one of body or resolved must be set
resolved boolean no Resolve/unresolve the note (exactly one of body or resolved must be set
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment

Resolving a note:

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?resolved=true

Delete a merge request discussion note

Deletes an existing discussion note of a merge request.

DELETE /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id/notes/:note_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
merge_request_iid integer yes The IID of a merge request
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636

Commits

List project commit discussions

Gets a list of all discussions for a single commit.

GET /projects/:id/commits/:commit_id/discussions
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
commit_id integer yes The ID of a commit
[
  {
    "id": "6a9c1750b37d513a43987b574953fceb50b03ce7",
    "individual_note": false,
    "notes": [
      {
        "id": 1126,
        "type": "DiscussionNote",
        "body": "discussion text",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-03T21:54:39.668Z",
        "updated_at": "2018-03-03T21:54:39.668Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Commit",
        "noteable_iid": null,
        "resolvable": false
      },
      {
        "id": 1129,
        "type": "DiscussionNote",
        "body": "reply to the discussion",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T13:38:02.127Z",
        "updated_at": "2018-03-04T13:38:02.127Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Commit",
        "noteable_iid": null,
        "resolvable": false
      }
    ]
  },
  {
    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
    "individual_note": true,
    "notes": [
      {
        "id": 1128,
        "type": null,
        "body": "a single comment",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T09:17:22.520Z",
        "updated_at": "2018-03-04T09:17:22.520Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Commit",
        "noteable_iid": null,
        "resolvable": false
      }
    ]
  }
]

Diff comments contain also position:

[
  {
    "id": "87805b7c09016a7058e91bdbe7b29d1f284a39e6",
    "individual_note": false,
    "notes": [
      {
        "id": 1128,
        "type": DiffNote,
        "body": "diff comment",
        "attachment": null,
        "author": {
          "id": 1,
          "name": "root",
          "username": "root",
          "state": "active",
          "avatar_url": "https://www.gravatar.com/avatar/00afb8fb6ab07c3ee3e9c1f38777e2f4?s=80&d=identicon",
          "web_url": "http://localhost:3000/root"
        },
        "created_at": "2018-03-04T09:17:22.520Z",
        "updated_at": "2018-03-04T09:17:22.520Z",
        "system": false,
        "noteable_id": 3,
        "noteable_type": "Commit",
        "noteable_iid": null,
        "position": {
          "base_sha": "b5d6e7b1613fca24d250fa8e5bc7bcc3dd6002ef",
          "start_sha": "7c9c2ead8a320fb7ba0b4e234bd9529a2614e306",
          "head_sha": "4803c71e6b1833ca72b8b26ef2ecd5adc8a38031",
          "old_path": "package.json",
          "new_path": "package.json",
          "position_type": "text",
          "old_line": 27,
          "new_line": 27
        },
        "resolvable": false
      }
    ]
  }
]
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions

Get single commit discussion

Returns a single discussion for a specific project commit

GET /projects/:id/commits/:commit_id/discussions/:discussion_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
commit_id integer yes The ID of a commit
discussion_id integer yes The ID of a discussion
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7

Create new commit discussion

Creates a new discussion to a single project commit. This is similar to creating a note but other comments (replies) can be added to it later.

POST /projects/:id/commits/:commit_id/discussions

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
commit_id integer yes The ID of a commit
body string yes The content of a discussion
created_at string no Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights)
position hash no Position when creating a diff note
position[base_sha] string yes Base commit SHA in the source branch
position[start_sha] string yes SHA referencing commit in target branch
position[head_sha] string yes SHA referencing HEAD of this commit
position[position_type] string yes Type of the position reference’, allowed values: ‘text’ or ‘image’
position[new_path] string no File path after change
position[new_line] integer no Line number after change
position[old_path] string no File path before change
position[old_line] integer no Line number before change
position[width] integer no Width of the image (for ‘image’ diff notes)
position[height] integer no Height of the image (for ‘image’ diff notes)
position[x] integer no X coordinate (for ‘image’ diff notes)
position[y] integer no Y coordinate (for ‘image’ diff notes)
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions?body=comment

Add note to existing commit discussion

Adds a new note to the discussion.

POST /projects/:id/commits/:commit_id/discussions/:discussion_id/notes

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
commit_id integer yes The ID of a commit
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
body string yes The content of a discussion
created_at string no Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights)
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment

Modify an existing commit discussion note

Modify or resolve an existing discussion note of a commit.

PUT /projects/:id/commits/:commit_id/discussions/:discussion_id/notes/:note_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
commit_id integer yes The ID of a commit
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
body string no The content of a note
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment

Resolving a note:

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?resolved=true

Delete a commit discussion note

Deletes an existing discussion note of a commit.

DELETE /projects/:id/commits/:commit_id/discussions/:discussion_id/notes/:note_id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
commit_id integer yes The ID of a commit
discussion_id integer yes The ID of a discussion
note_id integer yes The ID of a discussion note
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/636