debian-mirror-gitlab/doc/api/discussions.md

1240 lines
47 KiB
Markdown
Raw Normal View History

2020-06-23 00:09:42 +05:30
---
2020-10-24 23:57:45 +05:30
stage: Create
group: Source Code
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-24 23:57:45 +05:30
type: reference, api
2020-06-23 00:09:42 +05:30
---
2021-03-11 19:13:27 +05:30
# Discussions API **(FREE)**
2018-03-27 19:54:05 +05:30
2019-09-04 21:01:54 +05:30
Discussions are a set of related notes on:
- Snippets
- Issues
2019-09-30 21:07:59 +05:30
- Epics **(ULTIMATE)**
2019-09-04 21:01:54 +05:30
- Merge requests
- Commits
2018-03-27 19:54:05 +05:30
2019-07-31 22:56:46 +05:30
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](resource_label_events.md).
## Discussions pagination
2019-09-30 21:07:59 +05:30
By default, `GET` requests return 20 results at a time because the API results are paginated.
2019-07-31 22:56:46 +05:30
Read more on [pagination](README.md#pagination).
2018-03-27 19:54:05 +05:30
## Issues
2019-09-30 21:07:59 +05:30
### List project issue discussion items
2018-03-27 19:54:05 +05:30
2019-09-30 21:07:59 +05:30
Gets a list of all discussion items for a single issue.
2018-03-27 19:54:05 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-27 19:54:05 +05:30
GET /projects/:id/issues/:issue_iid/discussions
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ------------ |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `issue_iid` | integer | yes | The IID of an issue |
```json
[
{
"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",
2018-10-15 14:42:47 +05:30
"noteable_iid": null,
"resolvable": false
2018-03-27 19:54:05 +05:30
}
]
},
{
"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",
2018-10-15 14:42:47 +05:30
"noteable_iid": null,
"resolvable": false
2018-03-27 19:54:05 +05:30
}
]
}
]
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions"
2018-03-27 19:54:05 +05:30
```
2019-09-30 21:07:59 +05:30
### Get single issue discussion item
2018-03-27 19:54:05 +05:30
2019-09-30 21:07:59 +05:30
Returns a single discussion item for a specific project issue
2018-03-27 19:54:05 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-27 19:54:05 +05:30
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](README.md#namespaced-path-encoding) |
| `issue_iid` | integer | yes | The IID of an issue |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a discussion item |
2018-03-27 19:54:05 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7"
2018-03-27 19:54:05 +05:30
```
2019-09-30 21:07:59 +05:30
### Create new issue thread
2018-03-27 19:54:05 +05:30
2019-09-30 21:07:59 +05:30
Creates a new thread to a single project issue. This is similar to creating a note but other comments (replies) can be added to it later.
2018-03-27 19:54:05 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-27 19:54:05 +05:30
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](README.md#namespaced-path-encoding) |
| `issue_iid` | integer | yes | The IID of an issue |
2019-09-30 21:07:59 +05:30
| `body` | string | yes | The content of the thread |
2021-03-11 19:13:27 +05:30
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) |
2018-03-27 19:54:05 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment"
2018-03-27 19:54:05 +05:30
```
2019-09-30 21:07:59 +05:30
### Add note to existing issue thread
Adds a new note to the thread. This can also [create a thread from a single comment](../user/discussions/#start-a-thread-by-replying-to-a-standard-comment).
2018-03-27 19:54:05 +05:30
2019-09-30 21:07:59 +05:30
**WARNING**
2019-12-04 20:38:33 +05:30
Notes can be added to other items than comments (system notes, etc.) making them threads.
2018-03-27 19:54:05 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-27 19:54:05 +05:30
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](README.md#namespaced-path-encoding) |
| `issue_iid` | integer | yes | The IID of an issue |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a thread |
| `note_id` | integer | yes | The ID of a thread note |
| `body` | string | yes | The content of the note/reply |
2021-03-11 19:13:27 +05:30
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) |
2018-03-27 19:54:05 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment"
2018-03-27 19:54:05 +05:30
```
2019-09-30 21:07:59 +05:30
### Modify existing issue thread note
2018-03-27 19:54:05 +05:30
2019-09-30 21:07:59 +05:30
Modify existing thread note of an issue.
2018-03-27 19:54:05 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-27 19:54:05 +05:30
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](README.md#namespaced-path-encoding) |
| `issue_iid` | integer | yes | The IID of an issue |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a thread |
| `note_id` | integer | yes | The ID of a thread note |
| `body` | string | yes | The content of the note/reply |
2018-03-27 19:54:05 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2018-03-27 19:54:05 +05:30
```
2019-09-30 21:07:59 +05:30
### Delete an issue thread note
2018-03-27 19:54:05 +05:30
2019-09-30 21:07:59 +05:30
Deletes an existing thread note of an issue.
2018-03-27 19:54:05 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-27 19:54:05 +05:30
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](README.md#namespaced-path-encoding) |
| `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 |
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636"
2018-03-27 19:54:05 +05:30
```
## Snippets
2019-09-30 21:07:59 +05:30
### List project snippet discussion items
2018-03-27 19:54:05 +05:30
2019-09-30 21:07:59 +05:30
Gets a list of all discussion items for a single snippet.
2018-03-27 19:54:05 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-27 19:54:05 +05:30
GET /projects/:id/snippets/:snippet_id/discussions
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `snippet_id` | integer | yes | The ID of an snippet |
```json
[
{
"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",
2018-10-15 14:42:47 +05:30
"noteable_id": null,
"resolvable": false
2018-03-27 19:54:05 +05:30
}
]
},
{
"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",
2018-10-15 14:42:47 +05:30
"noteable_id": null,
"resolvable": false
2018-03-27 19:54:05 +05:30
}
]
}
]
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions"
2018-03-27 19:54:05 +05:30
```
2019-09-30 21:07:59 +05:30
### Get single snippet discussion item
2018-03-27 19:54:05 +05:30
2019-09-30 21:07:59 +05:30
Returns a single discussion item for a specific project snippet
2018-03-27 19:54:05 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-27 19:54:05 +05:30
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](README.md#namespaced-path-encoding) |
| `snippet_id` | integer | yes | The ID of an snippet |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a discussion item |
2018-03-27 19:54:05 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7"
2018-03-27 19:54:05 +05:30
```
2019-09-30 21:07:59 +05:30
### Create new snippet thread
2018-03-27 19:54:05 +05:30
2019-09-30 21:07:59 +05:30
Creates a new thread to a single project snippet. This is similar to creating
2019-02-15 15:39:39 +05:30
a note but other comments (replies) can be added to it later.
2018-03-27 19:54:05 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-27 19:54:05 +05:30
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](README.md#namespaced-path-encoding) |
| `snippet_id` | integer | yes | The ID of an snippet |
| `body` | string | yes | The content of a discussion |
2021-03-11 19:13:27 +05:30
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) |
2018-03-27 19:54:05 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment"
2018-03-27 19:54:05 +05:30
```
2019-09-30 21:07:59 +05:30
### Add note to existing snippet thread
2018-03-27 19:54:05 +05:30
2019-09-30 21:07:59 +05:30
Adds a new note to the thread.
2018-03-27 19:54:05 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-27 19:54:05 +05:30
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](README.md#namespaced-path-encoding) |
| `snippet_id` | integer | yes | The ID of an snippet |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a thread |
| `note_id` | integer | yes | The ID of a thread note |
| `body` | string | yes | The content of the note/reply |
2021-03-11 19:13:27 +05:30
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) |
2018-03-27 19:54:05 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment"
2018-03-27 19:54:05 +05:30
```
2019-09-30 21:07:59 +05:30
### Modify existing snippet thread note
2018-03-27 19:54:05 +05:30
2019-09-30 21:07:59 +05:30
Modify existing thread note of a snippet.
2018-03-27 19:54:05 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-27 19:54:05 +05:30
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](README.md#namespaced-path-encoding) |
| `snippet_id` | integer | yes | The ID of an snippet |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a thread |
| `note_id` | integer | yes | The ID of a thread note |
| `body` | string | yes | The content of the note/reply |
2018-03-27 19:54:05 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2018-03-27 19:54:05 +05:30
```
2019-09-30 21:07:59 +05:30
### Delete a snippet thread note
2018-03-27 19:54:05 +05:30
2019-09-30 21:07:59 +05:30
Deletes an existing thread note of a snippet.
2018-03-27 19:54:05 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-27 19:54:05 +05:30
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](README.md#namespaced-path-encoding) |
| `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 |
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636"
2018-03-27 19:54:05 +05:30
```
2018-10-15 14:42:47 +05:30
2019-09-30 21:07:59 +05:30
## Epics **(ULTIMATE)**
2019-09-04 21:01:54 +05:30
2019-09-30 21:07:59 +05:30
### List group epic discussion items
2019-09-04 21:01:54 +05:30
2019-09-30 21:07:59 +05:30
Gets a list of all discussion items for a single epic.
2019-09-04 21:01:54 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
GET /groups/:id/epics/:epic_id/discussions
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ------------ |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
| `epic_id` | integer | yes | The ID of an epic |
```json
[
{
"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
}
]
}
]
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions"
2019-09-04 21:01:54 +05:30
```
2019-09-30 21:07:59 +05:30
### Get single epic discussion item
2019-09-04 21:01:54 +05:30
2019-09-30 21:07:59 +05:30
Returns a single discussion item for a specific group epic
2019-09-04 21:01:54 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
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](README.md#namespaced-path-encoding) |
| `epic_id` | integer | yes | The ID of an epic |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a discussion item |
2019-09-04 21:01:54 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7"
2019-09-04 21:01:54 +05:30
```
2019-09-30 21:07:59 +05:30
### Create new epic thread
2019-09-04 21:01:54 +05:30
2019-09-30 21:07:59 +05:30
Creates a new thread to a single group epic. This is similar to creating
2020-04-22 19:07:51 +05:30
a note but other comments (replies) can be added to it later.
2019-09-04 21:01:54 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
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](README.md#namespaced-path-encoding) |
| `epic_id` | integer | yes | The ID of an epic |
2019-09-30 21:07:59 +05:30
| `body` | string | yes | The content of the thread |
2021-03-11 19:13:27 +05:30
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) |
2019-09-04 21:01:54 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions?body=comment"
2019-09-04 21:01:54 +05:30
```
2019-09-30 21:07:59 +05:30
### Add note to existing epic thread
2019-09-04 21:01:54 +05:30
2019-09-30 21:07:59 +05:30
Adds a new note to the thread. This can also
[create a thread from a single comment](../user/discussions/#start-a-thread-by-replying-to-a-standard-comment).
2019-09-04 21:01:54 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
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](README.md#namespaced-path-encoding) |
2019-09-30 21:07:59 +05:30
| `epic_id` | integer | yes | The ID of an epic |
| `discussion_id` | integer | yes | The ID of a thread |
| `note_id` | integer | yes | The ID of a thread note |
| `body` | string | yes | The content of the note/reply |
2021-03-11 19:13:27 +05:30
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) |
2019-09-04 21:01:54 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment"
2019-09-04 21:01:54 +05:30
```
2019-09-30 21:07:59 +05:30
### Modify existing epic thread note
2019-09-04 21:01:54 +05:30
2019-09-30 21:07:59 +05:30
Modify existing thread note of an epic.
2019-09-04 21:01:54 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
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](README.md#namespaced-path-encoding) |
| `epic_id` | integer | yes | The ID of an epic |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a thread |
| `note_id` | integer | yes | The ID of a thread note |
| `body` | string | yes | The content of note/reply |
2019-09-04 21:01:54 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2019-09-04 21:01:54 +05:30
```
2019-09-30 21:07:59 +05:30
### Delete an epic thread note
2019-09-04 21:01:54 +05:30
2019-09-30 21:07:59 +05:30
Deletes an existing thread note of an epic.
2019-09-04 21:01:54 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
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](README.md#namespaced-path-encoding) |
| `epic_id` | integer | yes | The ID of an epic |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a thread |
| `note_id` | integer | yes | The ID of a thread note |
2019-09-04 21:01:54 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/636"
2019-09-04 21:01:54 +05:30
```
2018-10-15 14:42:47 +05:30
## Merge requests
2019-09-30 21:07:59 +05:30
### List project merge request discussion items
2018-10-15 14:42:47 +05:30
2019-09-30 21:07:59 +05:30
Gets a list of all discussion items for a single merge request.
2018-10-15 14:42:47 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-10-15 14:42:47 +05:30
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](README.md#namespaced-path-encoding) |
| `merge_request_iid` | integer | yes | The IID of a merge request |
```json
[
{
"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,
2021-03-08 18:12:59 +05:30
"resolved_by": null,
"resolved_at": null
2018-10-15 14:42:47 +05:30
},
{
"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
}
]
}
]
```
2020-04-22 19:07:51 +05:30
Diff comments also contain position:
2018-10-15 14:42:47 +05:30
```json
[
{
"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,
2021-02-22 17:27:13 +05:30
"commit_id": "4803c71e6b1833ca72b8b26ef2ecd5adc8a38031",
2018-10-15 14:42:47 +05:30
"position": {
"base_sha": "b5d6e7b1613fca24d250fa8e5bc7bcc3dd6002ef",
"start_sha": "7c9c2ead8a320fb7ba0b4e234bd9529a2614e306",
"head_sha": "4803c71e6b1833ca72b8b26ef2ecd5adc8a38031",
"old_path": "package.json",
"new_path": "package.json",
"position_type": "text",
"old_line": 27,
2020-04-22 19:07:51 +05:30
"new_line": 27,
"line_range": {
2020-07-28 23:09:34 +05:30
"start": {
"line_code": "588440f66559714280628a4f9799f0c4eb880a4a_10_10",
"type": "new",
},
"end": {
"line_code": "588440f66559714280628a4f9799f0c4eb880a4a_11_11",
"type": "old"
},
2020-04-22 19:07:51 +05:30
}
2018-10-15 14:42:47 +05:30
},
"resolved": false,
"resolvable": true,
"resolved_by": null
}
]
}
]
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions"
2018-10-15 14:42:47 +05:30
```
2019-09-30 21:07:59 +05:30
### Get single merge request discussion item
2018-10-15 14:42:47 +05:30
2019-09-30 21:07:59 +05:30
Returns a single discussion item for a specific project merge request
2018-10-15 14:42:47 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-10-15 14:42:47 +05:30
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](README.md#namespaced-path-encoding) |
| `merge_request_iid` | integer | yes | The IID of a merge request |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a discussion item |
2018-10-15 14:42:47 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
2018-10-15 14:42:47 +05:30
```
2019-09-30 21:07:59 +05:30
### Create new merge request thread
2018-10-15 14:42:47 +05:30
2021-02-22 17:27:13 +05:30
> The `commit id` entry was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47130) in GitLab 13.7.
2019-09-30 21:07:59 +05:30
Creates a new thread to a single project merge request. This is similar to creating
2019-02-15 15:39:39 +05:30
a note but other comments (replies) can be added to it later.
2018-10-15 14:42:47 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-10-15 14:42:47 +05:30
POST /projects/:id/merge_requests/:merge_request_iid/discussions
```
Parameters:
2020-07-28 23:09:34 +05:30
| Attribute | Type | Required | Description |
| ---------------------------------------- | -------------- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `merge_request_iid` | integer | yes | The IID of a merge request |
| `body` | string | yes | The content of the thread |
2021-02-22 17:27:13 +05:30
| `commit_id` | string | no | SHA referencing commit to start this thread on |
2021-03-11 19:13:27 +05:30
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) |
2020-07-28 23:09:34 +05:30
| `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[line_range]` | hash | no | Line range for a multi-line diff note |
| `position[line_range][start]` | hash | no | Multiline note starting line |
| `position[line_range][start][line_code]` | string | yes | Line code for the start line |
| `position[line_range][start][type]` | string | yes | Line type for the start line |
| `position[line_range][end]` | hash | no | Multiline note ending line |
| `position[line_range][end][line_code]` | string | yes | Line code for the end line |
| `position[line_range][end][type]` | string | yes | Line type for the end line |
| `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) |
2018-10-15 14:42:47 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment"
2018-10-15 14:42:47 +05:30
```
2019-09-30 21:07:59 +05:30
### Resolve a merge request thread
2018-10-15 14:42:47 +05:30
2019-09-30 21:07:59 +05:30
Resolve/unresolve whole thread of a merge request.
2018-10-15 14:42:47 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-10-15 14:42:47 +05:30
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](README.md#namespaced-path-encoding) |
| `merge_request_iid` | integer | yes | The IID of a merge request |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a thread |
2018-10-15 14:42:47 +05:30
| `resolved` | boolean | yes | Resolve/unresolve the discussion |
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7?resolved=true"
2018-10-15 14:42:47 +05:30
```
2019-09-30 21:07:59 +05:30
### Add note to existing merge request thread
2018-10-15 14:42:47 +05:30
2019-09-30 21:07:59 +05:30
Adds a new note to the thread. This can also
[create a thread from a single comment](../user/discussions/#start-a-thread-by-replying-to-a-standard-comment).
2018-10-15 14:42:47 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-10-15 14:42:47 +05:30
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](README.md#namespaced-path-encoding) |
| `merge_request_iid` | integer | yes | The IID of a merge request |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a thread |
| `note_id` | integer | yes | The ID of a thread note |
| `body` | string | yes | The content of the note/reply |
2021-03-11 19:13:27 +05:30
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) |
2018-10-15 14:42:47 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2018-10-15 14:42:47 +05:30
```
2019-09-30 21:07:59 +05:30
### Modify an existing merge request thread note
2018-10-15 14:42:47 +05:30
2019-09-30 21:07:59 +05:30
Modify or resolve an existing thread note of a merge request.
2018-10-15 14:42:47 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-10-15 14:42:47 +05:30
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](README.md#namespaced-path-encoding) |
| `merge_request_iid` | integer | yes | The IID of a merge request |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a thread |
| `note_id` | integer | yes | The ID of a thread note |
| `body` | string | no | The content of the note/reply (exactly one of `body` or `resolved` must be set |
2018-10-15 14:42:47 +05:30
| `resolved` | boolean | no | Resolve/unresolve the note (exactly one of `body` or `resolved` must be set |
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2018-10-15 14:42:47 +05:30
```
Resolving a note:
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2018-10-15 14:42:47 +05:30
```
2019-09-30 21:07:59 +05:30
### Delete a merge request thread note
2018-10-15 14:42:47 +05:30
2019-09-30 21:07:59 +05:30
Deletes an existing thread note of a merge request.
2018-10-15 14:42:47 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-10-15 14:42:47 +05:30
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](README.md#namespaced-path-encoding) |
| `merge_request_iid` | integer | yes | The IID of a merge request |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a thread |
| `note_id` | integer | yes | The ID of a thread note |
2018-10-15 14:42:47 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636"
2018-10-15 14:42:47 +05:30
```
## Commits
2019-09-30 21:07:59 +05:30
### List project commit discussion items
2018-10-15 14:42:47 +05:30
2019-09-30 21:07:59 +05:30
Gets a list of all discussion items for a single commit.
2018-10-15 14:42:47 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-10-15 14:42:47 +05:30
GET /projects/:id/commits/:commit_id/discussions
```
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ------------ |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `commit_id` | integer | yes | The ID of a commit |
```json
[
{
"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:
```json
[
{
"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
}
]
}
]
```
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions"
2018-10-15 14:42:47 +05:30
```
2019-09-30 21:07:59 +05:30
### Get single commit discussion item
2018-10-15 14:42:47 +05:30
2019-09-30 21:07:59 +05:30
Returns a single discussion item for a specific project commit
2018-10-15 14:42:47 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-10-15 14:42:47 +05:30
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](README.md#namespaced-path-encoding) |
| `commit_id` | integer | yes | The ID of a commit |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a discussion item |
2018-10-15 14:42:47 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7"
2018-10-15 14:42:47 +05:30
```
2019-09-30 21:07:59 +05:30
### Create new commit thread
2018-10-15 14:42:47 +05:30
2019-09-30 21:07:59 +05:30
Creates a new thread to a single project commit. This is similar to creating
2019-02-15 15:39:39 +05:30
a note but other comments (replies) can be added to it later.
2018-10-15 14:42:47 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-10-15 14:42:47 +05:30
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](README.md#namespaced-path-encoding) |
| `commit_id` | integer | yes | The ID of a commit |
2019-09-30 21:07:59 +05:30
| `body` | string | yes | The content of the thread |
2021-03-11 19:13:27 +05:30
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) |
2018-10-15 14:42:47 +05:30
| `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) |
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions?body=comment"
2018-10-15 14:42:47 +05:30
```
2019-09-30 21:07:59 +05:30
### Add note to existing commit thread
2018-10-15 14:42:47 +05:30
2019-09-30 21:07:59 +05:30
Adds a new note to the thread.
2018-10-15 14:42:47 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-10-15 14:42:47 +05:30
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](README.md#namespaced-path-encoding) |
| `commit_id` | integer | yes | The ID of a commit |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a thread |
| `note_id` | integer | yes | The ID of a thread note |
| `body` | string | yes | The content of the note/reply |
2021-03-11 19:13:27 +05:30
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) |
2018-10-15 14:42:47 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment
2018-10-15 14:42:47 +05:30
```
2019-09-30 21:07:59 +05:30
### Modify an existing commit thread note
2018-10-15 14:42:47 +05:30
2019-09-30 21:07:59 +05:30
Modify or resolve an existing thread note of a commit.
2018-10-15 14:42:47 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-10-15 14:42:47 +05:30
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](README.md#namespaced-path-encoding) |
| `commit_id` | integer | yes | The ID of a commit |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a thread |
| `note_id` | integer | yes | The ID of a thread note |
2018-10-15 14:42:47 +05:30
| `body` | string | no | The content of a note |
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2018-10-15 14:42:47 +05:30
```
Resolving a note:
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
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"
2018-10-15 14:42:47 +05:30
```
2019-09-30 21:07:59 +05:30
### Delete a commit thread note
2018-10-15 14:42:47 +05:30
2019-09-30 21:07:59 +05:30
Deletes an existing thread note of a commit.
2018-10-15 14:42:47 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-10-15 14:42:47 +05:30
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](README.md#namespaced-path-encoding) |
| `commit_id` | integer | yes | The ID of a commit |
2019-09-30 21:07:59 +05:30
| `discussion_id` | integer | yes | The ID of a thread |
| `note_id` | integer | yes | The ID of a thread note |
2018-10-15 14:42:47 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/636"
2018-10-15 14:42:47 +05:30
```