> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/api-docs-contextual-information/player-labels.md).
# Player Labels
## Description
The **Player Labels API** provide endpoints to manage the labels assigned to a specific user.\
Labels are short identifiers (e.g., `"label1"`, `"label2"`) that categorize or tag users.
#### Salient Points
* Each user can have a **maximum of five unique labels**.
* Labels are case sensitive.
* Labels must be strings containing only alphanumeric, hyphens (-), or underscores (\_).
* A label can have a maximum of 32 characters
## APIs
* `GET` /users/{user\_id}/v1/labels
* Fetches all the labels for a given user\_id
* **Parameters**
* **Path Parameter**
* `user_id`: Unique identifier for the user.
* **Sample call**
```
curl --request GET 'https://api.ggwp.com/users/test-user/v1/labels' \
--header 'x-api-key: api_key'
```
* **Response 200**
```json
{
"data": {
"user_id": "test-user",
"labels": ["label1", "label2"]
},
"message": "success"
}
```
* `POST` /users/{user\_id}/v1/labels
* Replaces existing labels of a user with the provided set.
* Partial label sets are not allowed, i.e., if any of the given label in the set is invalid or if the total crosses five, the entire request is tagged as invalid
* **Parameters**
* **Path Parameter**
* `user_id` : Unique identifier for the user. Passed as path parameter in the endpoint.
* **Request Body**
* **labels** : list of new labels for a user
**Example**
```bash
{
"labels": ["label1", "label2"]
}
```
* **Sample call**
```bash
curl --request POST 'https://api.ggwp.com/users/test-user/v1/labels' \
--header 'x-api-key: api_key'
--header 'Content-Type: application/json' \
--data-raw '{
"labels": ["label1", "label2"]
}'
```
* **Response 201**
```bash
{
"data": {
"user_id": "test-user",
"labels": ["label1", "label2"]
}
}
```
* **4XX Responses**
| Status Code | Error message |
|---|
| 400 | {"message": "Invalid Label, Labels must be strings containing only alphanumeric, hyphens (-), or underscores (_)."} |
| 422 | {"message" :"A user can have a maximum of 5 labels."} |
* `PUT` /users/{user\_id}/v1/labels
* Appends the labels to the given user by eliminating the duplicates.
* Partial updates are not allowed, i.e., if any of the given label in the set is invalid or if the total crosses five, the entire request is tagged as invalid.
* **Parameters**
* **Path Parameter**
* `user_id` : Unique identifier for the user.
* **Request Body**
* **labels :** list of labels
**Example**
{
"labels": ["label3", "label4"]
}
* **Sample Call**
```bash
curl --request PUT 'https://api.ggwp.com/users/test-user/v1/labels' \
--header 'x-api-key: api_key'
--header 'Content-Type: application/json' \
--data-raw '{
"labels": ["label3", "label4"]
}'
```
* **Response 200**
```json
{
"data": {
"user_id": "test-user",
"labels": ["label1", "label2", "label3", "label4"],
"added_labels": ["label3", "label4"]
}
}
```
* **4XX Responses**
| Status Code | Error message |
|---|
| 400 | {"message": "Invalid Label, Labels must be strings containing only alphanumeric, hyphens (-), or underscores (_)."} |
| 422 | {"message" :"A user can have a maximum of 5 labels."} |
* `DELETE` /users/{user\_id}/v1/labels/{label}
* Deletes the given label, if attached to the user
* **Parameters**
* **Path Parameter**
* `user_id`: unique identifier for user
* `label`: name of the label
* **Sample Call**
```bash
curl --request DELETE 'https://api.ggwp.com/users/test-user/v1/labels/label4' \
--header 'x-api-key: api_key'
```
* **Response 200**
```json
{
"data": {
"user_id": "test-user",
"labels": ["label1", "label2", "label3"] //labels left after deletion
}
}
```
* **4XX Responses**
| Status Code | Error message |
|---|
| 404 | {"message": "Label not found for user test-user"} |
* `DELETE` /users/{user\_id}/v1/labels
* Deletes all the labels attached to the user
* **Parameters**
* **Path parameters**
* `user_id`: unique identifier for user
* **Sample Call**
```bash
curl --request DELETE 'https://api.ggwp.com/users/test-user/v1/labels' \
--header 'x-api-key: api_key'
```
* **Response 200**
```json
{
"data": {
"user_id": "test-user",
"labels": []
}
}
```
* **Common 4XX Responses**
| Status Code | Error message |
|---|
| 400 | {"message":"Label name cannot exceed 32 characters} |
| 403 | {"message": "Invalid or missing API key"} |
| 404 | {"message": "user not found"} |
* **Common 5XX Responses**
| Status Code | Error message |
|---|
| 500 | Internal Server Error |
| 504 | Gateway Timeout |