kotovalexarian-likes-gitlab
/
gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity
gitlab-org--gitlab-foss/doc/api/discussions.md

997 lines
37 KiB
Markdown
Raw Normal View History

Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
# Discussions API
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
Discussions are set of related notes on snippets, issues, merge requests or commits.
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
Link to resource label events API
2019-04-16 16:31:23 +00:00
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).
Add pagination to notes and discussions docs
2019-04-15 23:35:20 +00:00
## Discussions pagination
By default, `GET` requests return 20 results at a time because the API results
are paginated.
Read more on [pagination](README.md#pagination).
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
## 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",
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
"noteable_iid": null,
"resolvable": false
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
}
]
},
{
"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",
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
"noteable_iid": null,
"resolvable": false
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
}
]
}
]
```
```bash
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
### 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
### Create new issue discussion
Creates a new discussion to a single project issue. This is similar to creating
Eliminate duplicated words Signed-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>
2018-11-19 13:51:54 +00:00
a note but other comments (replies) can be added to it later.
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
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 |
Document that created_at works for group owners on Discussions
2018-08-23 09:29:24 +00:00
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```bash
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
### Add note to existing issue discussion
Allow replying to an individual note in the API If you can do this in the UI, you should be able to do it in the API. If a discussion is not a single note discussion, or it is replyable, you can reply to it.
2019-05-06 10:59:02 +00:00
Adds a new note to the discussion. This can also
[create a discussion from a single comment](../user/discussions/#start-a-discussion-by-replying-to-a-standard-comment).
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
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 |
Document that created_at works for group owners on Discussions
2018-08-23 09:29:24 +00:00
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```bash
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
### 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
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
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
### 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
## 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",
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
"noteable_id": null,
"resolvable": false
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
}
]
},
{
"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",
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
"noteable_id": null,
"resolvable": false
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
}
]
}
]
```
```bash
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
### 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
### Create new snippet discussion
Creates a new discussion to a single project snippet. This is similar to creating
Eliminate duplicated words Signed-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>
2018-11-19 13:51:54 +00:00
a note but other comments (replies) can be added to it later.
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
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 |
Document that created_at works for group owners on Discussions
2018-08-23 09:29:24 +00:00
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```bash
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
### 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 |
Document that created_at works for group owners on Discussions
2018-08-23 09:29:24 +00:00
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```bash
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
### 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
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
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
### 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636
Add discussion API * adds basic discussions API for issues and snippets * reorganizes notes specs (so same tests can be used for all noteable types - issues, MRs, snippets)
2018-02-28 07:48:23 +00:00
```
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
## 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
### 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
### Create new merge request discussion
Creates a new discussion to a single project merge request. This is similar to creating
Eliminate duplicated words Signed-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>
2018-11-19 13:51:54 +00:00
a note but other comments (replies) can be added to it later.
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
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 |
Document that created_at works for group owners on Discussions
2018-08-23 09:29:24 +00:00
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
| `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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
### 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7?resolved=true
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
### Add note to existing merge request discussion
Allow replying to an individual note in the API If you can do this in the UI, you should be able to do it in the API. If a discussion is not a single note discussion, or it is replyable, you can reply to it.
2019-05-06 10:59:02 +00:00
Adds a new note to the discussion. This can also
[create a discussion from a single comment](../user/discussions/#start-a-discussion-by-replying-to-a-standard-comment).
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
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 |
Document that created_at works for group owners on Discussions
2018-08-23 09:29:24 +00:00
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```bash
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
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
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
### 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
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
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
Resolving a note:
```bash
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
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
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
### 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
## 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
### 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
### Create new commit discussion
Creates a new discussion to a single project commit. This is similar to creating
Eliminate duplicated words Signed-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>
2018-11-19 13:51:54 +00:00
a note but other comments (replies) can be added to it later.
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
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 |
Document that created_at works for group owners on Discussions
2018-08-23 09:29:24 +00:00
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
| `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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions?body=comment
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
### 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 |
Document that created_at works for group owners on Discussions
2018-08-23 09:29:24 +00:00
| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) |
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```bash
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
### 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
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
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
Resolving a note:
```bash
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
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
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```
### 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
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs.
2018-12-27 09:03:08 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/636
Merge request and commit discussions API
2018-05-01 12:39:44 +00:00
```