Notes API

Notes are comments on:

  • Snippets
  • Issues
  • Merge requests
  • Epics

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

Version history
  • Introduced in GitLab 13.3 for state, milestone, and weight events.
  • Introduced in GitLab 13.4 for iteration 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.

Read more on pagination.

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",
    "noteable_iid": 377,
    "resolvable": false,
    "confidential": false
  },
  {
    "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",
    "noteable_iid": 121,
    "resolvable": false,
    "confidential": true
  }
]
curl --header "PRIVATE-TOKEN: <your_access_token>" "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>" "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 The confidential flag of a note. Default is false.
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>" "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: will be removed in GitLab 16.0. The confidential flag of a note. Default is false.
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?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>" "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>" "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": 52,
  "title": "Snippet",
  "file_name": "snippet.rb",
  "author": {
    "id": 1,
    "username": "pipin",
    "email": "admin@example.com",
    "name": "Pip",
    "state": "active",
    "created_at": "2013-09-30T13:46:01Z"
  },
  "expires_at": null,
  "updated_at": "2013-10-02T07:34:20Z",
  "created_at": "2013-10-02T07:34:20Z"
}
curl --header "PRIVATE-TOKEN: <your_access_token>" "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 sn