Reference Groups API

Endpoints for managing saved reference image groups.

List Reference Groups

GET /api/reference-groups

Query Parameters

Parameter	Type	Default	Description
search	string	-	Filter by name/description
limit	integer	50	Max results (max 100)
offset	integer	0	Pagination offset
sort_by	string	name	name, created, used, recent

Response

{
  "data": [
    {
      "id": 12,
      "groupName": "Brand Style",
      "description": "Primary product refs",
      "imageCount": 3,
      "timesUsed": 7,
      "createdAt": "2025-12-01T10:00:00.000Z",
      "lastUsedAt": "2025-12-05T14:20:00.000Z"
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 1 }
}

---

Create Reference Group

POST /api/reference-groups

Request Body

Field	Type	Required	Description
group_name	string	Yes	Unique name (1–100 chars)
description	string	No	Optional notes
reference_image_ids	integer[]	Yes	Image IDs to include (1–20)

Response

{
  "data": {
    "id": 12,
    "groupName": "Brand Style",
    "referenceImages": [{ "id": 101, "url": "https://pub-xxx.r2.dev/..." }]
  }
}

---

Get / Update / Delete Group

Operate on a single group by numeric ID or URL‑encoded name:

GET    /api/reference-groups/:id_or_name
PATCH  /api/reference-groups/:id_or_name
DELETE /api/reference-groups/:id_or_name

Update Body (PATCH)

Provide any of:

Field	Type	Description
new_group_name	string	Rename group
description	string | null	Update/clear description
reference_image_ids	integer[]	Replace images

Delete returns { data: { deleted: true } } on success.