Notes

Use this API to manage the comments and system records attached to GitLab content. You can:

Create and modify comments on issues, merge requests, epics, snippets, commits, and wiki pages.
Retrieve system-generated notes about object changes.
Control visibility with confidential and internal flags.

Some system-generated notes are tracked as separate resource events instead, including label, state, milestone, weight, and iteration events.

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

List all issue notes

GET /api/v4/projects/{id}/issues/{noteable_id}/notes

Lists all notes for a specified issue.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to
`order_by` Query	String	Sort results by the specified field Allowed values: `created_at`, `updated_at` Default: `created_at`
`sort` Query	String	Sort results in ascending or descending order Allowed values: `asc`, `desc` Default: `desc`
`activity_filter` Query	String	Filter notes by activity type Allowed values: `all_notes`, `only_comments`, `only_activity` Default: `all_notes`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Create an issue note

POST /api/v4/projects/{id}/issues/{noteable_id}/notes

Creates a note for an issue.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to

Request body (application/json)

Property	Type	Description
`body` Required	String	Content of the note. Limited to 1,000,000 characters
`confidential`	Boolean	If `true`, marks the note as internal. Deprecated. Use `internal` instead
`created_at`	String	Date and time the note was created, in ISO 8601 format such as `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights
`internal`	Boolean	Internal note flag Default: `false`
`merge_request_diff_head_sha`	String	SHA of the head commit, which ensures the merge request wasn’t updated after the API request was sent. Required for the `/merge` quick action

Responses

Code	Description	Schema
`201`	Created	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Retrieve an issue note

GET /api/v4/projects/{id}/issues/{noteable_id}/notes/{note_id}

Retrieves a specified note for an issue.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`note_id` Path, required	Integer	ID of the note
`noteable_id` Path, required	Integer	ID of the resource the note is attached to

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Update an issue note

PUT /api/v4/projects/{id}/issues/{noteable_id}/notes/{note_id}

Updates an existing note for an issue.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to
`note_id` Path, required	Integer	ID of the note

Request body (application/json)

Property	Type	Description
`body`	String	Content of the note. Limited to 1,000,000 characters
`confidential`	Boolean	If `true`, the note must already be confidential. If `false`, it must not be. Confidentiality cannot be changed after a note is created. Deprecated

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Delete an issue note

DELETE /api/v4/projects/{id}/issues/{noteable_id}/notes/{note_id}

Deletes a specified note from an issue.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to
`note_id` Path, required	Integer	ID of the note

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

List all merge request notes

GET /api/v4/projects/{id}/merge_requests/{noteable_id}/notes

Lists all notes for a specified merge request.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to
`order_by` Query	String	Sort results by the specified field Allowed values: `created_at`, `updated_at` Default: `created_at`
`sort` Query	String	Sort results in ascending or descending order Allowed values: `asc`, `desc` Default: `desc`
`activity_filter` Query	String	Filter notes by activity type Allowed values: `all_notes`, `only_comments`, `only_activity` Default: `all_notes`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Create a merge request note

POST /api/v4/projects/{id}/merge_requests/{noteable_id}/notes

Creates a note for a merge request.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to

Request body (application/json)

Property	Type	Description
`body` Required	String	Content of the note. Limited to 1,000,000 characters
`confidential`	Boolean	If `true`, marks the note as internal. Deprecated. Use `internal` instead
`created_at`	String	Date and time the note was created, in ISO 8601 format such as `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights
`internal`	Boolean	Internal note flag Default: `false`
`merge_request_diff_head_sha`	String	SHA of the head commit, which ensures the merge request wasn’t updated after the API request was sent. Required for the `/merge` quick action

Responses

Code	Description	Schema
`201`	Created	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Retrieve a merge request note

GET /api/v4/projects/{id}/merge_requests/{noteable_id}/notes/{note_id}

Retrieves a specified note for a merge request.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`note_id` Path, required	Integer	ID of the note
`noteable_id` Path, required	Integer	ID of the resource the note is attached to

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Update a merge request note

PUT /api/v4/projects/{id}/merge_requests/{noteable_id}/notes/{note_id}

Updates an existing note for a merge request.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to
`note_id` Path, required	Integer	ID of the note

Request body (application/json)

Property	Type	Description
`body`	String	Content of the note. Limited to 1,000,000 characters
`confidential`	Boolean	If `true`, the note must already be confidential. If `false`, it must not be. Confidentiality cannot be changed after a note is created. Deprecated

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Delete a merge request note

DELETE /api/v4/projects/{id}/merge_requests/{noteable_id}/notes/{note_id}

Deletes a specified note from a merge request.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to
`note_id` Path, required	Integer	ID of the note

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

List all snippet notes

GET /api/v4/projects/{id}/snippets/{noteable_id}/notes

Lists all notes for a specified snippet.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to
`order_by` Query	String	Sort results by the specified field Allowed values: `created_at`, `updated_at` Default: `created_at`
`sort` Query	String	Sort results in ascending or descending order Allowed values: `asc`, `desc` Default: `desc`
`activity_filter` Query	String	Filter notes by activity type Allowed values: `all_notes`, `only_comments`, `only_activity` Default: `all_notes`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Create a snippet note

POST /api/v4/projects/{id}/snippets/{noteable_id}/notes

Creates a note for a snippet.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to

Request body (application/json)

Property	Type	Description
`body` Required	String	Content of the note. Limited to 1,000,000 characters
`confidential`	Boolean	If `true`, marks the note as internal. Deprecated. Use `internal` instead
`created_at`	String	Date and time the note was created, in ISO 8601 format such as `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights
`internal`	Boolean	Internal note flag Default: `false`
`merge_request_diff_head_sha`	String	SHA of the head commit, which ensures the merge request wasn’t updated after the API request was sent. Required for the `/merge` quick action

Responses

Code	Description	Schema
`201`	Created	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Retrieve a snippet note

GET /api/v4/projects/{id}/snippets/{noteable_id}/notes/{note_id}

Retrieves a specified note for a snippet.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`note_id` Path, required	Integer	ID of the note
`noteable_id` Path, required	Integer	ID of the resource the note is attached to

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Update a snippet note

PUT /api/v4/projects/{id}/snippets/{noteable_id}/notes/{note_id}

Updates an existing note for a snippet.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to
`note_id` Path, required	Integer	ID of the note

Request body (application/json)

Property	Type	Description
`body`	String	Content of the note. Limited to 1,000,000 characters
`confidential`	Boolean	If `true`, the note must already be confidential. If `false`, it must not be. Confidentiality cannot be changed after a note is created. Deprecated

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Delete a snippet note

DELETE /api/v4/projects/{id}/snippets/{noteable_id}/notes/{note_id}

Deletes a specified note from a snippet.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to
`note_id` Path, required	Integer	ID of the note

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

List all wiki page meta notes

GET /api/v4/projects/{id}/wiki_pages/{noteable_id}/notes

Lists all notes for a specified wiki page meta.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to
`order_by` Query	String	Sort results by the specified field Allowed values: `created_at`, `updated_at` Default: `created_at`
`sort` Query	String	Sort results in ascending or descending order Allowed values: `asc`, `desc` Default: `desc`
`activity_filter` Query	String	Filter notes by activity type Allowed values: `all_notes`, `only_comments`, `only_activity` Default: `all_notes`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Create a wiki page meta note

POST /api/v4/projects/{id}/wiki_pages/{noteable_id}/notes

Creates a note for a wiki page meta.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to

Request body (application/json)

Property	Type	Description
`body` Required	String	Content of the note. Limited to 1,000,000 characters
`confidential`	Boolean	If `true`, marks the note as internal. Deprecated. Use `internal` instead
`created_at`	String	Date and time the note was created, in ISO 8601 format such as `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights
`internal`	Boolean	Internal note flag Default: `false`
`merge_request_diff_head_sha`	String	SHA of the head commit, which ensures the merge request wasn’t updated after the API request was sent. Required for the `/merge` quick action

Responses

Code	Description	Schema
`201`	Created	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Retrieve a wiki page meta note

GET /api/v4/projects/{id}/wiki_pages/{noteable_id}/notes/{note_id}

Retrieves a specified note for a wiki page meta.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`note_id` Path, required	Integer	ID of the note
`noteable_id` Path, required	Integer	ID of the resource the note is attached to

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Update a wiki page meta note

PUT /api/v4/projects/{id}/wiki_pages/{noteable_id}/notes/{note_id}

Updates an existing note for a wiki page meta.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to
`note_id` Path, required	Integer	ID of the note

Request body (application/json)

Property	Type	Description
`body`	String	Content of the note. Limited to 1,000,000 characters
`confidential`	Boolean	If `true`, the note must already be confidential. If `false`, it must not be. Confidentiality cannot be changed after a note is created. Deprecated

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Delete a wiki page meta note

DELETE /api/v4/projects/{id}/wiki_pages/{noteable_id}/notes/{note_id}

Deletes a specified note from a wiki page meta.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the project
`noteable_id` Path, required	Integer	ID of the resource the note is attached to
`note_id` Path, required	Integer	ID of the note

Responses

Code	Description	Schema
`200`	OK	APIEntitiesNote
`400`	Bad Request	—
`404`	Not Found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCustomAttribute

Property	Type	Description
`key`	String	Example: `foo`
`value`	String	Example: `bar`

APIEntitiesNote

Property	Type	Description
`author`	APIEntitiesUserBasic	—
`body`	String	Example: `Note body.`
`commands_changes`	Object	—
`commit_id`	String	Example: `7b09ce7e6f80347baf0316c8c94cdba9a0a7e91d`
`confidential`	Boolean	Example: `false`
`created_at`	String (date-time)	Example: `2022-01-31T15:10:44.988Z`
`id`	Integer (int64)	Example: `1`
`imported`	Boolean	Example: `false`
`imported_from`	String	Example: `github`
`internal`	Boolean	Example: `false`
`noteable_id`	Integer (int64)	Example: `1`
`noteable_iid`	Integer	Example: `1`
`noteable_type`	String	Example: `Issue`
`position`	Object	—
`project_id`	Integer (int64)	Example: `1`
`resolvable`	Boolean	Example: `false`
`resolved`	Boolean	Example: `false`
`resolved_at`	String (date-time)	Example: `2022-01-31T15:10:44.988Z`
`resolved_by`	APIEntitiesUserBasic	—
`suggestions`	APIEntitiesSuggestion	—
`system`	Boolean	Example: `false`
`type`	String	Example: `DiscussionNote`
`updated_at`	String (date-time)	Example: `2022-01-31T15:10:44.988Z`

APIEntitiesSuggestion

Property	Type	Description
`appliable`	Boolean	Example: `true`
`applied`	Boolean	Example: `false`
`from_content`	String	Example: `Original content`
`from_line`	Integer	Example: `1`
`id`	Integer (int64)	Example: `1`
`to_content`	String	Example: `New content`
`to_line`	Integer	Example: `1`

APIEntitiesUserBasic

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`id`	Integer (int64)	Example: `1`
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`

List all issue notes

Create an issue note

Retrieve an issue note

Update an issue note

Delete an issue note

List all merge request notes

Create a merge request note

Retrieve a merge request note

Update a merge request note

Delete a merge request note

List all snippet notes

Create a snippet note

Retrieve a snippet note

Update a snippet note

Delete a snippet note

List all wiki page meta notes

Create a wiki page meta note

Retrieve a wiki page meta note

Update a wiki page meta note

Delete a wiki page meta note

Schemas

APIEntitiesCustomAttribute

APIEntitiesNote

APIEntitiesSuggestion

APIEntitiesUserBasic

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC compliance report

Thank you

Error

Request partner program details

Request received

Error