---
method: POST
path: /api/collections/:id/books
auth: jwt
area: collections
---
<!-- source: internal/handlers/collections.go:506 CollectionHandler.AddBooks -->

# Bulk Assign Books

Add multiple books to a collection at once.

**Endpoint**: `POST /api/collections/{id}/books`
**Auth**: Required
**Content-Type**: `application/json`

## Path Parameters

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

## Request Body

| Field    | Type          | Required | Description              |
| -------- | ------------- | -------- | ------------------------ |
| book_ids | array of UUID | Yes      | Array of book IDs to add |

### Example Request

```json example-request
{
  "book_ids": [
    "660e8400-e29b-41d4-a716-446655440000",
    "770e8400-e29b-41d4-a716-446655440000",
    "880e8400-e29b-41d4-a716-446655440000"
  ]
}
```

## Response (204 No Content)

Books added to collection successfully. No response body.

## Notes

- Books already in the collection are ignored
- This is more efficient than adding books individually
- Maximum 1000 books per request

```json example-response
{
  "results": [
    {
      "book_id": "660e8400-e29b-41d4-a716-446655440001",
      "status": "added"
    }
  ],
  "total": 1
}
```

Each result carries the operation outcome for one book (`added`/`error`
variants come from the per-book loop; malformed ids report their own
status instead of failing the batch).

## Error Responses

| Code | Description                         |
| ---- | ----------------------------------- |
| 400  | Invalid request (validation failed) |
| 401  | Authentication required             |
| 404  | Collection or book(s) not found     |
| 500  | Internal server error               |

## Try It Out