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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable
`order_by` Query	String	Return notes ordered by `created_at` or `updated_at` fields Allowed values: `created_at`, `updated_at` Default: `created_at`
`sort` Query	String	Return notes sorted in `asc` or `desc` order Allowed values: `asc`, `desc` Default: `desc`
`activity_filter` Query	String	The type of notables which are returned Allowed values: `all_notes`, `only_comments`, `only_activity` Default: `all_notes`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items 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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable

Request body (application/json)

Property	Type	Description
`body` Required	String	The content of a note
`confidential`	Boolean	[Deprecated in 15.5] Renamed to internal
`created_at`	String	The creation date of the note
`internal`	Boolean	Internal note flag, default is false
`merge_request_diff_head_sha`	String	The SHA of the head commit

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	The ID of a project
`note_id` Path, required	Integer	The ID of a note
`noteable_id` Path, required	Integer	The ID of the noteable

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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable
`note_id` Path, required	Integer	The ID of a note

Request body (application/json)

Property	Type	Description
`body`	String	The content of a note
`confidential`	Boolean	[Deprecated in 14.10] No longer allowed to update confidentiality of notes

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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable
`note_id` Path, required	Integer	The ID of a 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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable
`order_by` Query	String	Return notes ordered by `created_at` or `updated_at` fields Allowed values: `created_at`, `updated_at` Default: `created_at`
`sort` Query	String	Return notes sorted in `asc` or `desc` order Allowed values: `asc`, `desc` Default: `desc`
`activity_filter` Query	String	The type of notables which are returned Allowed values: `all_notes`, `only_comments`, `only_activity` Default: `all_notes`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items 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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable

Request body (application/json)

Property	Type	Description
`body` Required	String	The content of a note
`confidential`	Boolean	[Deprecated in 15.5] Renamed to internal
`created_at`	String	The creation date of the note
`internal`	Boolean	Internal note flag, default is false
`merge_request_diff_head_sha`	String	The SHA of the head commit

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	The ID of a project
`note_id` Path, required	Integer	The ID of a note
`noteable_id` Path, required	Integer	The ID of the noteable

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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable
`note_id` Path, required	Integer	The ID of a note

Request body (application/json)

Property	Type	Description
`body`	String	The content of a note
`confidential`	Boolean	[Deprecated in 14.10] No longer allowed to update confidentiality of notes

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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable
`note_id` Path, required	Integer	The ID of a 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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable
`order_by` Query	String	Return notes ordered by `created_at` or `updated_at` fields Allowed values: `created_at`, `updated_at` Default: `created_at`
`sort` Query	String	Return notes sorted in `asc` or `desc` order Allowed values: `asc`, `desc` Default: `desc`
`activity_filter` Query	String	The type of notables which are returned Allowed values: `all_notes`, `only_comments`, `only_activity` Default: `all_notes`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items 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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable

Request body (application/json)

Property	Type	Description
`body` Required	String	The content of a note
`confidential`	Boolean	[Deprecated in 15.5] Renamed to internal
`created_at`	String	The creation date of the note
`internal`	Boolean	Internal note flag, default is false
`merge_request_diff_head_sha`	String	The SHA of the head commit

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	The ID of a project
`note_id` Path, required	Integer	The ID of a note
`noteable_id` Path, required	Integer	The ID of the noteable

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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable
`note_id` Path, required	Integer	The ID of a note

Request body (application/json)

Property	Type	Description
`body`	String	The content of a note
`confidential`	Boolean	[Deprecated in 14.10] No longer allowed to update confidentiality of notes

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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable
`note_id` Path, required	Integer	The ID of a 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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable
`order_by` Query	String	Return notes ordered by `created_at` or `updated_at` fields Allowed values: `created_at`, `updated_at` Default: `created_at`
`sort` Query	String	Return notes sorted in `asc` or `desc` order Allowed values: `asc`, `desc` Default: `desc`
`activity_filter` Query	String	The type of notables which are returned Allowed values: `all_notes`, `only_comments`, `only_activity` Default: `all_notes`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items 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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable

Request body (application/json)

Property	Type	Description
`body` Required	String	The content of a note
`confidential`	Boolean	[Deprecated in 15.5] Renamed to internal
`created_at`	String	The creation date of the note
`internal`	Boolean	Internal note flag, default is false
`merge_request_diff_head_sha`	String	The SHA of the head commit

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	The ID of a project
`note_id` Path, required	Integer	The ID of a note
`noteable_id` Path, required	Integer	The ID of the noteable

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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable
`note_id` Path, required	Integer	The ID of a note

Request body (application/json)

Property	Type	Description
`body`	String	The content of a note
`confidential`	Boolean	[Deprecated in 14.10] No longer allowed to update confidentiality of notes

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	The ID of a project
`noteable_id` Path, required	Integer	The ID of the noteable
`note_id` Path, required	Integer	The ID of a 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