bookhoard/docs/api/collections/create_collection.md

Create Collection

Create a new collection.

Endpoint: POST /api/collections Auth: Required Content-Type: application/json

Request Body

Field	Type	Required	Description
name	string	Yes	Collection name (max 255 chars)
description	string	No	Collection description
color	string	No	Hex color code (e.g., "#FF5733")
icon	string	No	Emoji icon (e.g., "🚀", "📖")
auto_assign_rules	array	No	Array of rule objects
view_settings	object	No	Per-device display preferences

Auto-Assign Rule Object

Field	Type	Required	Description
field	string	Yes	Field to match on (genre, author, series, language, publisher, copyright_year, tags)
operator	string	Yes	Comparison operator (equals, not_equals, contains, not_contains, starts_with, ends_with, greater_than, less_than)
value	string/number	Yes	Value to compare against
priority	integer	No	Rule priority (1 = highest, default: 1)
enabled	boolean	No	Whether rule is active (default: true)

Example Request

{
  "name": "To Read",
  "description": "Books I want to read soon",
  "color": "#00FF00",
  "icon": "📖",
  "auto_assign_rules": [
    {
      "field": "tags",
      "operator": "contains",
      "value": "to-read",
      "priority": 1,
      "enabled": true
    }
  ],
  "view_settings": {
    "kobo": {
      "view_mode": "grid"
    },
    "koreader": {
      "view_mode": "list"
    }
  }
}

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "To Read",
  "description": "Books I want to read soon",
  "color": "#00FF00",
  "icon": "📖",
  "auto_assign_rules": [
    {
      "field": "tags",
      "operator": "contains",
      "value": "to-read",
      "priority": 1,
      "enabled": true
    }
  ],
  "view_settings": {
    "kobo": {
      "view_mode": "grid"
    },
    "koreader": {
      "view_mode": "list"
    }
  },
  "created_at": "2026-02-01T10:00:00Z"
}

Error Responses

Code	Description
400	Invalid request (validation failed)
401	Authentication required
500	Internal server error

Try It Out