# Add labels to a trainee

`POST https://api.coach-platform.com/api/public/trainees/{traineeId}/labels`

Add labels to a trainee. Labels are matched by text and created if new; existing labels can be passed by id.

- Resource: Labels
- Authentication: API key in the `Authorization: Bearer cp_live_...` header
- HTML version: https://www.coach-platform.com/docs/api/reference/post-trainees-trainee-id-labels
- OpenAPI spec: https://www.coach-platform.com/openapi.json

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `traineeId` | string | Yes |   |

## Header parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | string | No | Optional. Send a unique key (e.g. a UUID) to make this POST safe to retry. The same key within 24h returns the original result instead of creating a duplicate. |

## Request body

Content type: `application/json`. Required.

| Field | Type | Required | Description |
|---|---|---|---|
| `labels` | object[] | Yes | Minimum items: `1`. Maximum items: `100`. |
| `labels[].id` | string | No | Existing label id to attach |
| `labels[].text` | string | No | Label text; created if new |
| `labels[].color` | string | No | Tailwind color key, e.g. "blue-500" |

## Responses

| Status | Description |
|---|---|
| `200` OK | Successful response |
| `400` Bad Request |  |
| `401` Unauthorized |  |
| `403` Forbidden |  |
| `404` Not Found |  |
| `409` Conflict |  |
| `429` Too Many Requests |  |
| `500` Internal Server Error |  |

### 200 OK

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `data` | object |   |

Example:

```json
{
  "data": {}
}
```

### Error responses 400, 401, 403, 404, 409, 429, 500

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `error` | object |   |
| `error.code` | string |   |
| `error.message` | string |   |
| `error.fix` | string \| null |   |
| `error.details` | object \| null |   |
| `error.retryAfterMs` | number \| null |   |

Example:

```json
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "fix": "<string>",
    "details": {},
    "retryAfterMs": 123
  }
}
```

## Examples

### cURL

```bash
curl --request POST \
  --url 'https://api.coach-platform.com/api/public/trainees/<traineeId>/labels' \
  --header 'Authorization: Bearer cp_live_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "labels": [
    {
      "id": "<string>"
    }
  ]
}'
```

### JavaScript (fetch)

```js
const response = await fetch('https://api.coach-platform.com/api/public/trainees/<traineeId>/labels', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cp_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "labels": [
      {
        "id": "<string>"
      }
    ]
  }),
});

const data = await response.json();
```

## Related endpoints

- [List labels](https://www.coach-platform.com/docs/api/reference/get-labels/index.md): `GET /api/public/labels`. List all trainee labels (tags) defined by the coach.
- [Remove a label from a trainee](https://www.coach-platform.com/docs/api/reference/delete-trainees-trainee-id-labels-label-id/index.md): `DELETE /api/public/trainees/{traineeId}/labels/{labelId}`. Detach a single label from one trainee.
- [Update a label](https://www.coach-platform.com/docs/api/reference/patch-labels-label-id/index.md): `PATCH /api/public/labels/{labelId}`. Rename a label or change its color.
- [Delete a label](https://www.coach-platform.com/docs/api/reference/delete-labels-label-id/index.md): `DELETE /api/public/labels/{labelId}`. Delete a label.
- Previous: [List labels](https://www.coach-platform.com/docs/api/reference/get-labels/index.md): `GET /api/public/labels`. List all trainee labels (tags) defined by the coach.
- Next: [Remove a label from a trainee](https://www.coach-platform.com/docs/api/reference/delete-trainees-trainee-id-labels-label-id/index.md): `DELETE /api/public/trainees/{traineeId}/labels/{labelId}`. Detach a single label from one trainee.