Notes API

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

Notes are comments on:

This includes system notes, which are notes about changes to the object (for example, when an assignee changes, GitLab posts a system note).

Resource events

Some system notes are not part of this API, but are recorded as separate events:

Notes pagination

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

Rate limits

To help avoid abuse, you can limit your users to a specific number of Create request per minute. See Notes rate limits.

Issues

List project issue notes

Gets a list of all notes for a single issue.

GET /projects/:id/issues/:issue_iid/notes
GET /projects/:id/issues/:issue_iid/notes?sort=asc&order_by=updated_at

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project
`issue_iid`	integer	yes	The IID of an issue
`sort`	string	no	Return issue notes sorted in `asc` or `desc` order. Default is `desc`
`order_by`	string	no	Return issue notes ordered by `created_at` or `updated_at` fields. Default is `created_at`

[
  {
    "id": 302,
    "body": "closed",
    "attachment": null,
    "author": {
      "id": 1,
      "username": "pipin",
      "email": "admin@example.com",
      "name": "Pip",
      "state": "active",
      "created_at": "2013-09-30T13:46:01Z"
    },
    "created_at": "2013-10-02T09:22:45Z",
    "updated_at": "2013-10-02T10:22:45Z",
    "system": true,
    "noteable_id": 377,
    "noteable_type": "Issue",
    "project_id": 5,
    "noteable_iid": 377,
    "resolvable": false,
    "confidential": false,
    "internal": false,
    "imported": false,
    "imported_from": "none"
  },
  {
    "id": 305,
    "body": "Text of the comment\r\n",
    "attachment": null,
    "author": {
      "id": 1,
      "username": "pipin",
      "email": "admin@example.com",
      "name": "Pip",
      "state": "active",
      "created_at": "2013-09-30T13:46:01Z"
    },
    "created_at": "2013-10-02T09:56:03Z",
    "updated_at": "2013-10-02T09:56:03Z",
    "system": true,
    "noteable_id": 121,
    "noteable_type": "Issue",
    "project_id": 5,
    "noteable_iid": 121,
    "resolvable": false,
    "confidential": true,
    "internal": true,
    "imported": false,
    "imported_from": "none"
  }
]

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"

Get single issue note

Returns a single note for a specific project issue

GET /projects/:id/issues/:issue_iid/notes/:note_id

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project
`issue_iid`	integer	yes	The IID of a project issue
`note_id`	integer	yes	The ID of an issue note

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"

Create new issue note

Creates a new note to a single project issue.

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

Parameters:

Attribute	Type	Required	Description
`id`	integer or 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 note. Limited to 1,000,000 characters.
`confidential`	boolean	no	Deprecated: Scheduled to be removed in GitLab 16.0 and renamed to `internal`. The confidential flag of a note. Default is false.
`internal`	boolean	no	The internal flag of a note. Overrides `confidential` when both parameters are submitted. Default is false.
`created_at`	string	no	Date time string, ISO 8601 formatted. It must be after 1970-01-01. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights)

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"

Modify existing issue note

Modify existing note of an issue.

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

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project.
`issue_iid`	integer	yes	The IID of an issue.
`note_id`	integer	yes	The ID of a note.
`body`	string	no	The content of a note. Limited to 1,000,000 characters.
`confidential`	boolean	no	Deprecated: Scheduled to be removed in GitLab 16.0. The confidential flag of a note. Default is false.

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636?body=note"

Delete an issue note

Deletes an existing note of an issue.

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

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project
`issue_iid`	integer	yes	The IID of an issue
`note_id`	integer	yes	The ID of a note

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636"

Snippets

The Snippets Notes API is intended for project-level snippets, and not for personal snippets.

List all snippet notes

Gets a list of all notes for a single snippet. Snippet notes are comments users can post to a snippet.

GET /projects/:id/snippets/:snippet_id/notes
GET /projects/:id/snippets/:snippet_id/notes?sort=asc&order_by=updated_at

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project
`snippet_id`	integer	yes	The ID of a project snippet
`sort`	string	no	Return snippet notes sorted in `asc` or `desc` order. Default is `desc`
`order_by`	string	no	Return snippet notes ordered by `created_at` or `updated_at` fields. Default is `created_at`

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes"

Get single snippet note

Returns a single note for a given snippet.

GET /projects/:id/snippets/:snippet_id/notes/:note_id

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project
`snippet_id`	integer	yes	The ID of a project snippet
`note_id`	integer	yes	The ID of a snippet note

{
  "id": 302,
  "body": "closed",
  "attachment": null,
  "author": {
    "id": 1,
    "username": "pipin",
    "email": "admin@example.com",
    "name": "Pip",
    "state": "active",
    "created_at": "2013-09-30T13:46:01Z"
  },
  "created_at": "2013-10-02T09:22:45Z",
  "updated_at": "2013-10-02T10:22:45Z",
  "system": true,
  "noteable_id": 377,
  "noteable_type": "Issue",
  "project_id": 5,
  "noteable_iid": 377,
  "resolvable": false,
  "confidential": false,
  "internal": false,
  "imported": false,
  "imported_from": "none"
}

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes/11"

Create new snippet note

Creates a new note for a single snippet. Snippet notes are user comments on snippets. If you create a note where the body only contains an emoji reaction, GitLab returns this object.

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

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project
`snippet_id`	integer	yes	The ID of a snippet
`body`	string	yes	The content of a note. Limited to 1,000,000 characters.
`created_at`	string	no	Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights)

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note"

Modify existing snippet note

Modify existing note of a snippet.

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

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project
`snippet_id`	integer	yes	The ID of a snippet
`note_id`	integer	yes	The ID of a snippet note
`body`	string	yes	The content of a note. Limited to 1,000,000 characters.

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes/1659?body=note"

Delete a snippet note

Deletes an existing note of a snippet.

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

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project
`snippet_id`	integer	yes	The ID of a snippet
`note_id`	integer	yes	The ID of a note

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/52/notes/1659"

Merge requests

List all merge request notes

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

GET /projects/:id/merge_requests/:merge_request_iid/notes
GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc&order_by=updated_at

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project
`merge_request_iid`	integer	yes	The IID of a project merge request
`sort`	string	no	Return merge request notes sorted in `asc` or `desc` order. Default is `desc`
`order_by`	string	no	Return merge request notes ordered by `created_at` or `updated_at` fields. Default is `created_at`

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes"

Get single merge request note

Returns a single note for a given merge request.

GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project
`merge_request_iid`	integer	yes	The IID of a project merge request
`note_id`	integer	yes	The ID of a merge request note

{
  "id": 301,
  "body": "Comment for MR",
  "attachment": null,
  "author": {
    "id": 1,
    "username": "pipin",
    "email": "admin@example.com",
    "name": "Pip",
    "state": "active",
    "created_at": "2013-09-30T13:46:01Z"
  },
  "created_at": "2013-10-02T08:57:14Z",
  "updated_at": "2013-10-02T08:57:14Z",
  "system": false,
  "noteable_id": 2,
  "noteable_type": "MergeRequest",
  "project_id": 5,
  "noteable_iid": 2,
  "resolvable": false,
  "confidential": false,
  "internal": false
}

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes/1"

Create new merge request note

Creates a new note for a single merge request. Notes are not attached to specific lines in a merge request. For other approaches with more granular control, see Post comment to commit in the Commits API, and Create a new thread in the merge request diff in the Discussions API.

If you create a note where the body only contains an emoji reaction, GitLab returns this object.

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

Parameters:

Attribute	Type	Required	Description
`body`	string	yes	The content of a note. Limited to 1,000,000 characters.
`id`	integer or string	yes	The ID or URL-encoded path of the project
`merge_request_iid`	integer	yes	The IID of a project merge request
`created_at`	string	no	Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights)
`internal`	boolean	no	The internal flag of a note. Default is false.
`merge_request_diff_head_sha`	string	no	Required for the `/merge` quick action. The SHA of the head commit, which ensures the merge request wasn’t updated after the API request was sent.

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note"

Modify existing merge request note

Modify existing note of a merge request.

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

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project
`merge_request_iid`	integer	yes	The IID of a project merge request
`note_id`	integer	no	The ID of a note
`body`	string	yes	The content of a note. Limited to 1,000,000 characters.
`confidential`	boolean	no	Deprecated: Scheduled to be removed in GitLab 16.0. The confidential flag of a note. Default is false.

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes/1?body=note"

Delete a merge request note

Deletes an existing note of a merge request.

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

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the project
`merge_request_iid`	integer	yes	The IID of a merge request
`note_id`	integer	yes	The ID of a note

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602"

Epics

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

The Epics REST API was deprecated in GitLab 17.0 and is planned for removal in v5 of the API. In GitLab 17.4 or later, if your administrator enabled the new look for epics, use the Work Items API instead. For more information, see the guide how to migrate your existing APIs. This change is a breaking change.

List all epic notes

Gets a list of all notes for a single epic. Epic notes are comments users can post to an epic.

The epics notes API uses the epic ID instead of epic IID. If you use the epic’s IID, GitLab returns either a 404 error or notes for the wrong epic. It’s different from the issue notes API and merge requests notes API.

GET /groups/:id/epics/:epic_id/notes
GET /groups/:id/epics/:epic_id/notes?sort=asc&order_by=updated_at

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group
`epic_id`	integer	yes	The ID of a group epic
`sort`	string	no	Return epic notes sorted in `asc` or `desc` order. Default is `desc`
`order_by`	string	no	Return epic notes ordered by `created_at` or `updated_at` fields. Default is `created_at`

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/notes"

Get single epic note

Returns a single note for a given epic.

GET /groups/:id/epics/:epic_id/notes/:note_id

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group
`epic_id`	integer	yes	The ID of an epic
`note_id`	integer	yes	The ID of a note

{
  "id": 302,
  "body": "Epic note",
  "attachment": null,
  "author": {
    "id": 1,
    "username": "pipin",
    "email": "admin@example.com",
    "name": "Pip",
    "state": "active",
    "created_at": "2013-09-30T13:46:01Z"
  },
  "created_at": "2013-10-02T09:22:45Z",
  "updated_at": "2013-10-02T10:22:45Z",
  "system": true,
  "noteable_id": 11,
  "noteable_type": "Epic",
  "project_id": 5,
  "noteable_iid": 11,
  "resolvable": false,
  "confidential": false,
  "internal": false,
  "imported": false,
  "imported_from": "none"
}

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/notes/1"

Create new epic note

Creates a new note for a single epic. Epic notes are comments users can post to an epic. If you create a note where the body only contains an emoji reaction, GitLab returns this object.

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

Parameters:

Attribute	Type	Required	Description
`body`	string	yes	The content of a note. Limited to 1,000,000 characters.
`epic_id`	integer	yes	The ID of an epic
`id`	integer or string	yes	The ID or URL-encoded path of the group
`confidential`	boolean	no	Deprecated: Scheduled to be removed in GitLab 16.0 and is renamed to `internal`. The confidential flag of a note. Default is `false`.
`internal`	boolean	no	The internal flag of a note. Overrides `confidential` when both parameters are submitted. Default is `false`.

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/notes?body=note"

Modify existing epic note

Modify existing note of an epic.

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

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group
`epic_id`	integer	yes	The ID of an epic
`note_id`	integer	yes	The ID of a note
`body`	string	yes	The content of a note. Limited to 1,000,000 characters.
`confidential`	boolean	no	Deprecated: Scheduled to be removed in GitLab 16.0. The confidential flag of a note. Default is false.

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/notes/1?body=note"

Delete an epic note

Deletes an existing note of an epic.

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

Parameters:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group
`epic_id`	integer	yes	The ID of an epic
`note_id`	integer	yes	The ID of a note

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/52/notes/1659"

Notes API

Resource events

Rate limits

Issues

List project issue notes

Get single issue note

Create new issue note

Modify existing issue note

Delete an issue note

Snippets

List all snippet notes

Get single snippet note

Create new snippet note

Modify existing snippet note

Delete a snippet note

Merge requests

List all merge request notes

Get single merge request note

Create new merge request note

Modify existing merge request note

Delete a merge request note

Epics

List all epic notes

Get single epic note

Create new epic note

Modify existing epic note

Delete an epic note

Help & feedback

Docs

Product

Feature availability and product trials

Get Help