---
method: POST
path: /api/devices/:id/shelves
auth: jwt
area: devices
---
<!-- source: internal/handlers/media.go:256 MediaHandler.AddToShelf -->

# Add to Shelf

Add a media item to a device's shelf (Kobo reading shelf).

**Endpoint**: `POST /api/devices/:id/shelves`
**Auth**: Required
**Content-Type**: `application/json`

## Path Parameters

| Parameter | Type          | Required | Description |
| --------- | ------------- | -------- | ----------- |
| id        | string (UUID) | Yes      | Device UUID |

## Request Body

| Field          | Type            | Required | Description                     |
| -------------- | --------------- | -------- | ------------------------------- |
| media_item_ids | array of string | Yes      | Media item UUIDs to add to shelf |
| shelf_name     | string          | No       | Shelf name (default "Default")  |
| shelf_position | int             | No       | Starting shelf position         |

### Example Request

```json example-request
{
  "media_item_ids": ["550e8400-e29b-41d4-a716-446655440001"],
  "shelf_name": "Default",
  "shelf_position": 0
}
```

## Response (200 OK)

```json example-response
{
  "status": "success",
  "added_count": 1,
  "shelf_name": "Default",
  "total_count": 1
}
```

## Error Responses

| Code | Description                    |
| ---- | ------------------------------ |
| 400  | Invalid request data           |
| 401  | Invalid or expired token       |
| 404  | Device or media item not found |
| 409  | Item already on shelf          |