986 lines
37 KiB
Markdown
986 lines
37 KiB
Markdown
# Discussions API
|
|
|
|
Discussions are set of related notes on snippets, issues, merge requests or commits.
|
|
|
|
## Issues
|
|
|
|
### List project issue discussions
|
|
|
|
Gets a list of all discussions for a single issue.
|
|
|
|
```
|
|
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",
|
|
"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": "Issue",
|
|
"noteable_iid": null,
|
|
"resolvable": false
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
```bash
|
|
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions
|
|
```
|
|
|
|
### Get single issue discussion
|
|
|
|
Returns a single discussion for a specific project issue
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
|
|
```bash
|
|
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
|
|
```
|
|
|
|
### Create new issue discussion
|
|
|
|
Creates a new discussion to a single project issue. This is similar to creating
|
|
a note but other comments (replies) can be added to it later.
|
|
|
|
```
|
|
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 |
|
|
| `body` | string | yes | The content of a discussion |
|
|
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
|
|
|
|
```bash
|
|
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment
|
|
```
|
|
|
|
### Add note to existing issue discussion
|
|
|
|
Adds a new note to the discussion.
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
| `note_id` | integer | yes | The ID of a discussion note |
|
|
| `body` | string | yes | The content of a discussion |
|
|
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
|
|
|
|
```bash
|
|
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment
|
|
```
|
|
|
|
### Modify existing issue discussion note
|
|
|
|
Modify existing discussion note of an issue.
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
| `note_id` | integer | yes | The ID of a discussion note |
|
|
| `body` | string | yes | The content of a discussion |
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
### Delete an issue discussion note
|
|
|
|
Deletes an existing discussion note of an issue.
|
|
|
|
```
|
|
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 |
|
|
|
|
```bash
|
|
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636
|
|
```
|
|
|
|
## Snippets
|
|
|
|
### List project snippet discussions
|
|
|
|
Gets a list of all discussions for a single snippet.
|
|
|
|
```
|
|
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",
|
|
"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": "Snippet",
|
|
"noteable_id": null,
|
|
"resolvable": false
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
```bash
|
|
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions
|
|
```
|
|
|
|
### Get single snippet discussion
|
|
|
|
Returns a single discussion for a specific project snippet
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
|
|
```bash
|
|
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
|
|
```
|
|
|
|
### Create new snippet discussion
|
|
|
|
Creates a new discussion to a single project snippet. This is similar to creating
|
|
a note but other comments (replies) can be added to it later.
|
|
|
|
```
|
|
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 |
|
|
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
|
|
|
|
```bash
|
|
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment
|
|
```
|
|
|
|
### Add note to existing snippet discussion
|
|
|
|
Adds a new note to the discussion.
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
| `note_id` | integer | yes | The ID of a discussion note |
|
|
| `body` | string | yes | The content of a discussion |
|
|
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
|
|
|
|
```bash
|
|
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment
|
|
```
|
|
|
|
### Modify existing snippet discussion note
|
|
|
|
Modify existing discussion note of an snippet.
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
| `note_id` | integer | yes | The ID of a discussion note |
|
|
| `body` | string | yes | The content of a discussion |
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
### Delete an snippet discussion note
|
|
|
|
Deletes an existing discussion note of an snippet.
|
|
|
|
```
|
|
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 |
|
|
|
|
```bash
|
|
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636
|
|
```
|
|
|
|
## Merge requests
|
|
|
|
### List project merge request discussions
|
|
|
|
Gets a list of all discussions for a single merge request.
|
|
|
|
```
|
|
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,
|
|
"resolved_by": 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": "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
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
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": "Merge request",
|
|
"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
|
|
},
|
|
"resolved": false,
|
|
"resolvable": true,
|
|
"resolved_by": null
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
```bash
|
|
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions
|
|
```
|
|
|
|
### Get single merge request discussion
|
|
|
|
Returns a single discussion for a specific project merge request
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
|
|
```bash
|
|
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
|
|
```
|
|
|
|
### Create new merge request discussion
|
|
|
|
Creates a new discussion to a single project merge request. This is similar to creating
|
|
a note but other comments (replies) can be added to it later.
|
|
|
|
```
|
|
POST /projects/:id/merge_requests/:merge_request_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) |
|
|
| `merge_request_iid` | integer | yes | The IID of a merge request |
|
|
| `body` | string | yes | The content of a discussion |
|
|
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
|
|
| `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[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) |
|
|
|
|
```bash
|
|
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment
|
|
```
|
|
|
|
### Resolve a merge request discussion
|
|
|
|
Resolve/unresolve whole discussion of a merge request.
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
| `resolved` | boolean | yes | Resolve/unresolve the discussion |
|
|
|
|
```bash
|
|
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7?resolved=true
|
|
```
|
|
|
|
|
|
### Add note to existing merge request discussion
|
|
|
|
Adds a new note to the discussion.
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
| `note_id` | integer | yes | The ID of a discussion note |
|
|
| `body` | string | yes | The content of a discussion |
|
|
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
### Modify an existing merge request discussion note
|
|
|
|
Modify or resolve an existing discussion note of a merge request.
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
| `note_id` | integer | yes | The ID of a discussion note |
|
|
| `body` | string | no | The content of a discussion (exactly one of `body` or `resolved` must be set |
|
|
| `resolved` | boolean | no | Resolve/unresolve the note (exactly one of `body` or `resolved` must be set |
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
Resolving a note:
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
### Delete a merge request discussion note
|
|
|
|
Deletes an existing discussion note of a merge request.
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
| `note_id` | integer | yes | The ID of a discussion note |
|
|
|
|
```bash
|
|
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636
|
|
```
|
|
|
|
## Commits
|
|
|
|
### List project commit discussions
|
|
|
|
Gets a list of all discussions for a single commit.
|
|
|
|
```
|
|
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
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
```bash
|
|
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions
|
|
```
|
|
|
|
### Get single commit discussion
|
|
|
|
Returns a single discussion for a specific project commit
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
|
|
```bash
|
|
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
|
|
```
|
|
|
|
### Create new commit discussion
|
|
|
|
Creates a new discussion to a single project commit. This is similar to creating
|
|
a note but other comments (replies) can be added to it later.
|
|
|
|
```
|
|
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 |
|
|
| `body` | string | yes | The content of a discussion |
|
|
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
|
|
| `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) |
|
|
|
|
```bash
|
|
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions?body=comment
|
|
```
|
|
|
|
### Add note to existing commit discussion
|
|
|
|
Adds a new note to the discussion.
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
| `note_id` | integer | yes | The ID of a discussion note |
|
|
| `body` | string | yes | The content of a discussion |
|
|
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
|
|
|
|
```bash
|
|
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment
|
|
```
|
|
|
|
### Modify an existing commit discussion note
|
|
|
|
Modify or resolve an existing discussion note of a commit.
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
| `note_id` | integer | yes | The ID of a discussion note |
|
|
| `body` | string | no | The content of a note |
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
Resolving a note:
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
### Delete a commit discussion note
|
|
|
|
Deletes an existing discussion note of a commit.
|
|
|
|
```
|
|
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 |
|
|
| `discussion_id` | integer | yes | The ID of a discussion |
|
|
| `note_id` | integer | yes | The ID of a discussion note |
|
|
|
|
```bash
|
|
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/636
|
|
```
|