2020-05-27 03:08:26 +00:00
---
stage: Plan
group: Project Management
2020-11-26 06:09:20 +00:00
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-05-27 03:08:26 +00:00
---
2017-05-18 08:49:03 +00:00
# Award Emoji API
2016-06-17 13:44:38 +00:00
2020-02-06 15:09:11 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4575) in GitLab 8.9. Snippet support added in 8.12.
2016-07-27 08:10:07 +00:00
2019-01-10 03:05:15 +00:00
An [awarded emoji ](../user/award_emojis.md ) tells a thousand words.
2016-06-17 20:03:57 +00:00
2020-12-10 18:10:16 +00:00
We call GitLab objects on which you can award an emoji "awardables". You can award emojis on the following:
2019-01-10 03:05:15 +00:00
2020-12-10 18:10:16 +00:00
- [Epics ](../user/group/epics/index.md ) ([API](epics.md)).
2019-01-16 01:05:11 +00:00
- [Issues ](../user/project/issues/index.md ) ([API](issues.md)).
- [Merge requests ](../user/project/merge_requests/index.md ) ([API](merge_requests.md)).
- [Snippets ](../user/snippets.md ) ([API](snippets.md)).
2019-01-10 03:05:15 +00:00
2020-12-10 18:10:16 +00:00
Emojis can also [be awarded ](../user/award_emojis.md#award-emoji-for-comments ) on comments (also known as notes). See also [Notes API ](notes.md ).
2016-06-17 13:44:38 +00:00
2016-07-27 08:10:07 +00:00
## Issues, merge requests, and snippets
2016-06-17 13:44:38 +00:00
2019-01-11 04:30:02 +00:00
See [Award Emoji on Comments ](#award-emoji-on-comments ) for information on using these endpoints with comments.
2019-01-10 03:05:15 +00:00
2020-12-10 18:10:16 +00:00
### List an awardable's award emojis
2016-06-17 13:44:38 +00:00
2020-12-10 18:10:16 +00:00
Get a list of all award emojis for a specified awardable.
2016-06-17 13:44:38 +00:00
2020-05-20 03:08:04 +00:00
```plaintext
2017-03-01 06:57:34 +00:00
GET /projects/:id/issues/:issue_iid/award_emoji
GET /projects/:id/merge_requests/:merge_request_iid/award_emoji
2016-07-27 08:10:07 +00:00
GET /projects/:id/snippets/:snippet_id/award_emoji
2016-06-17 13:44:38 +00:00
```
Parameters:
2019-01-15 04:04:41 +00:00
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ). |
2019-02-13 19:23:04 +00:00
| `issue_iid` /`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
2016-06-17 13:44:38 +00:00
2019-01-10 03:05:15 +00:00
Example request:
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji"
2016-06-17 13:44:38 +00:00
```
2019-01-10 03:05:15 +00:00
Example response:
2016-06-17 13:44:38 +00:00
```json
[
{
"id": 4,
"name": "1234",
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "http://gitlab.example.com/root"
2016-06-17 13:44:38 +00:00
},
"created_at": "2016-06-15T10:09:34.206Z",
"updated_at": "2016-06-15T10:09:34.206Z",
"awardable_id": 80,
"awardable_type": "Issue"
},
{
"id": 1,
"name": "microphone",
"user": {
"name": "User 4",
"username": "user4",
"id": 26,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "http://gitlab.example.com/user4"
2016-06-17 13:44:38 +00:00
},
"created_at": "2016-06-15T10:09:34.177Z",
"updated_at": "2016-06-15T10:09:34.177Z",
"awardable_id": 80,
"awardable_type": "Issue"
}
]
```
2016-07-21 08:00:17 +00:00
### Get single award emoji
2016-06-17 13:44:38 +00:00
2019-01-10 03:05:15 +00:00
Get a single award emoji from an issue, snippet, or merge request.
2016-06-17 13:44:38 +00:00
2020-05-20 03:08:04 +00:00
```plaintext
2017-03-01 06:57:34 +00:00
GET /projects/:id/issues/:issue_iid/award_emoji/:award_id
GET /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
2016-09-07 12:48:43 +00:00
GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id
2016-06-17 13:44:38 +00:00
```
Parameters:
2019-01-15 04:04:41 +00:00
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ). |
2019-02-13 19:23:04 +00:00
| `issue_iid` /`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
2019-01-15 04:04:41 +00:00
| `award_id` | integer | yes | ID of the award emoji. |
2019-01-10 03:05:15 +00:00
Example request:
2016-06-17 13:44:38 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/1"
2016-06-17 13:44:38 +00:00
```
2019-01-10 03:05:15 +00:00
Example response:
2016-06-17 13:44:38 +00:00
```json
{
"id": 1,
"name": "microphone",
"user": {
"name": "User 4",
"username": "user4",
"id": 26,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "http://gitlab.example.com/user4"
2016-06-17 13:44:38 +00:00
},
"created_at": "2016-06-15T10:09:34.177Z",
"updated_at": "2016-06-15T10:09:34.177Z",
"awardable_id": 80,
"awardable_type": "Issue"
}
```
### Award a new emoji
2019-01-10 03:05:15 +00:00
Create an award emoji on the specified awardable.
2016-06-17 13:44:38 +00:00
2020-05-20 03:08:04 +00:00
```plaintext
2017-03-01 06:57:34 +00:00
POST /projects/:id/issues/:issue_iid/award_emoji
POST /projects/:id/merge_requests/:merge_request_iid/award_emoji
2016-09-07 12:48:43 +00:00
POST /projects/:id/snippets/:snippet_id/award_emoji
2016-06-17 13:44:38 +00:00
```
Parameters:
2019-01-15 04:04:41 +00:00
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ). |
2019-02-13 19:23:04 +00:00
| `issue_iid` /`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
2019-01-15 04:04:41 +00:00
| `name` | string | yes | Name of the emoji without colons. |
2016-06-17 13:44:38 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji?name=blowfish"
2016-06-17 13:44:38 +00:00
```
Example Response:
```json
{
"id": 344,
"name": "blowfish",
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "http://gitlab.example.com/root"
2016-06-17 13:44:38 +00:00
},
"created_at": "2016-06-17T17:47:29.266Z",
"updated_at": "2016-06-17T17:47:29.266Z",
"awardable_id": 80,
"awardable_type": "Issue"
2017-04-08 08:54:00 +00:00
}
2016-06-17 13:44:38 +00:00
```
### Delete an award emoji
2020-12-10 18:10:16 +00:00
Sometimes it's just not meant to be and you need to remove the award.
2016-06-17 13:44:38 +00:00
2020-12-10 18:10:16 +00:00
Only an administrator or the author of the award can delete an award emoji.
2019-01-10 03:05:15 +00:00
2020-05-20 03:08:04 +00:00
```plaintext
2017-03-01 06:57:34 +00:00
DELETE /projects/:id/issues/:issue_iid/award_emoji/:award_id
DELETE /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
2016-07-27 08:10:07 +00:00
DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id
2016-06-17 13:44:38 +00:00
```
Parameters:
2019-01-15 04:04:41 +00:00
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ). |
2019-02-13 19:23:04 +00:00
| `issue_iid` /`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
2019-01-15 04:04:41 +00:00
| `award_id` | integer | yes | ID of an award emoji. |
2016-06-17 13:44:38 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/344"
2016-06-17 13:44:38 +00:00
```
2019-01-11 04:30:02 +00:00
## Award Emoji on Comments
2016-06-17 13:44:38 +00:00
2019-01-11 04:30:02 +00:00
Comments (also known as notes) are a sub-resource of issues, merge requests, and snippets.
2016-06-17 20:03:57 +00:00
2020-12-04 21:09:29 +00:00
NOTE:
2020-12-10 18:10:16 +00:00
The examples below describe working with award emojis on an issue's comments, but can be
adapted to comments on merge requests and snippets. Therefore, you have to replace
2019-02-13 19:23:04 +00:00
`issue_iid` either with `merge_request_iid` or with the `snippet_id` .
2016-06-17 20:03:57 +00:00
2020-12-10 18:10:16 +00:00
### List a comment's award emojis
2019-01-10 03:05:15 +00:00
2020-12-10 18:10:16 +00:00
Get all award emojis for a comment (note).
2019-01-10 03:05:15 +00:00
2020-05-20 03:08:04 +00:00
```plaintext
2017-03-01 06:57:34 +00:00
GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
2016-06-17 20:03:57 +00:00
```
Parameters:
2019-01-15 04:04:41 +00:00
| Attribute | Type | Required | Description |
|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ). |
| `issue_iid` | integer | yes | Internal ID of an issue. |
| `note_id` | integer | yes | ID of a comment (note). |
2016-06-17 20:03:57 +00:00
2019-01-10 03:05:15 +00:00
Example request:
2016-06-17 20:03:57 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji"
2016-06-17 20:03:57 +00:00
```
2019-01-10 03:05:15 +00:00
Example response:
2016-06-17 20:03:57 +00:00
```json
[
{
"id": 2,
"name": "mood_bubble_lightning",
"user": {
"name": "User 4",
"username": "user4",
"id": 26,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "http://gitlab.example.com/user4"
2016-06-17 20:03:57 +00:00
},
"created_at": "2016-06-15T10:09:34.197Z",
"updated_at": "2016-06-15T10:09:34.197Z",
"awardable_id": 1,
"awardable_type": "Note"
}
]
```
2019-01-11 04:30:02 +00:00
### Get an award emoji for a comment
2016-06-17 20:03:57 +00:00
2019-01-11 04:30:02 +00:00
Get a single award emoji for a comment (note).
2019-01-10 03:05:15 +00:00
2020-05-20 03:08:04 +00:00
```plaintext
2017-03-01 06:57:34 +00:00
GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
2016-06-17 20:03:57 +00:00
```
Parameters:
2019-01-15 04:04:41 +00:00
| Attribute | Type | Required | Description |
|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ). |
| `issue_iid` | integer | yes | Internal ID of an issue. |
| `note_id` | integer | yes | ID of a comment (note). |
| `award_id` | integer | yes | ID of the award emoji. |
2019-01-10 03:05:15 +00:00
Example request:
2016-06-17 20:03:57 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji/2"
2016-06-17 20:03:57 +00:00
```
2019-01-10 03:05:15 +00:00
Example response:
2016-06-17 20:03:57 +00:00
```json
{
"id": 2,
"name": "mood_bubble_lightning",
"user": {
"name": "User 4",
"username": "user4",
"id": 26,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/7e65550957227bd38fe2d7fbc6fd2f7b?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "http://gitlab.example.com/user4"
2016-06-17 20:03:57 +00:00
},
"created_at": "2016-06-15T10:09:34.197Z",
"updated_at": "2016-06-15T10:09:34.197Z",
"awardable_id": 1,
"awardable_type": "Note"
}
```
2019-01-11 04:30:02 +00:00
### Award a new emoji on a comment
2016-06-17 20:03:57 +00:00
2019-01-11 04:30:02 +00:00
Create an award emoji on the specified comment (note).
2019-01-10 03:05:15 +00:00
2020-05-20 03:08:04 +00:00
```plaintext
2017-03-01 06:57:34 +00:00
POST /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
2016-06-17 20:03:57 +00:00
```
Parameters:
2019-01-15 04:04:41 +00:00
| Attribute | Type | Required | Description |
|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ). |
| `issue_iid` | integer | yes | Internal ID of an issue. |
| `note_id` | integer | yes | ID of a comment (note). |
| `name` | string | yes | Name of the emoji without colons. |
2016-06-17 20:03:57 +00:00
2019-01-10 03:05:15 +00:00
Example request:
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji?name=rocket"
2016-06-17 20:03:57 +00:00
```
2019-01-10 03:05:15 +00:00
Example response:
2016-06-17 20:03:57 +00:00
```json
{
"id": 345,
"name": "rocket",
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
2016-10-13 11:24:09 +00:00
"web_url": "http://gitlab.example.com/root"
2016-06-17 20:03:57 +00:00
},
"created_at": "2016-06-17T19:59:55.888Z",
"updated_at": "2016-06-17T19:59:55.888Z",
"awardable_id": 1,
"awardable_type": "Note"
}
```
2019-01-11 04:30:02 +00:00
### Delete an award emoji from a comment
2016-06-17 13:44:38 +00:00
2020-12-10 18:10:16 +00:00
Sometimes it's just not meant to be and you need to remove the award.
2016-06-17 20:03:57 +00:00
2020-12-10 18:10:16 +00:00
Only an administrator or the author of the award can delete an award emoji.
2019-01-10 03:05:15 +00:00
2020-05-20 03:08:04 +00:00
```plaintext
2017-03-01 06:57:34 +00:00
DELETE /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
2016-06-17 20:03:57 +00:00
```
Parameters:
2019-01-15 04:04:41 +00:00
| Attribute | Type | Required | Description |
|:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ). |
| `issue_iid` | integer | yes | Internal ID of an issue. |
| `note_id` | integer | yes | ID of a comment (note). |
| `award_id` | integer | yes | ID of an award_emoji. |
2019-01-10 03:05:15 +00:00
Example request:
2016-06-17 20:03:57 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/345"
2016-06-17 20:03:57 +00:00
```