Collections

A Collection bundles several of your quizzes behind one shareable, embeddable link, each item tagged easy / medium / hard so students pick a difficulty and self-start. See the Collections guide for the concept.

Operation	Endpoint	Scope
List collections	GET /api/v1/collections	api:collection:read
Create a collection	POST /api/v1/collections	api:collection:write
Get a collection	GET /api/v1/collections/{collectionAssignmentId}	api:collection:read
Update a collection	PATCH /api/v1/collections/{collectionAssignmentId}	api:collection:write

The {collectionAssignmentId} path segment is the collection_assignment_id returned when you create a collection (also the id in the public /collection/<slug> and /widget/collection/<id> URLs).

List collections

GET /api/v1/collections?page=1&limit=20

Query	Default	Notes
page	1	1–1000.
limit	20	1–100.

{
  "data": [
    { "collection_assignment_id": "…", "collection_id": "…", "title": "…",
      "slug": "…", "use_count": 0, "created_at": "…", "collection_url": "…" }
  ],
  "total": 1, "page": 1, "limit": 20, "totalPages": 1
}

Create a collection

POST /api/v1/collections

Field	Type	Required	Notes
title	string	Yes	1–200 chars.
items	array	Yes	2–50 items, each { quiz_id, difficulty? }. quiz_ids must be distinct and owned by you.
items[].quiz_id	UUID	Yes	A quiz from GET /api/v1/quizzes.
items[].difficulty	"easy" | "medium" | "hard"	No	Defaults to medium.
default_mode	"classic" | "widget"	No	Defaults to widget.
time_limit_seconds	number | null	No	Optional per-quiz time limit.
shuffle_items	boolean	No	Defaults to false.
show_results	boolean	No	Defaults to true.

The public slug is generated automatically (title + a short id suffix); set a custom one later with PATCH (see below).

{
  "data": {
    "collection_id": "…",
    "collection_assignment_id": "…",
    "slug": "my-pack-2bdccf",
    "collection_url": "https://quizzz.techtranslab.com/collection/my-pack-2bdccf",
    "embed_url": "https://quizzz.techtranslab.com/widget/collection/…"
  }
}

Errors:

Status	code	When
400	INVALID_ITEMS	Fewer than 2 items, or a duplicate quiz_id.
400	QUIZ_NOT_FOUND	An items[].quiz_id is not a quiz you own (response includes quiz_ids).
403	quota code	Monthly link quota exceeded.

Get a collection

GET /api/v1/collections/{collectionAssignmentId}

Returns the collection with its items. 404 if it does not exist or is not yours.

{
  "data": {
    "collection_assignment_id": "…", "collection_id": "…", "title": "…",
    "default_mode": "widget", "time_limit_seconds": null,
    "shuffle_items": false, "show_results": true,
    "slug": "…", "collection_url": "…", "embed_url": "…",
    "items": [ { "quiz_id": "…", "difficulty": "easy", "quiz_title": "…" } ]
  }
}

Update a collection

PATCH /api/v1/collections/{collectionAssignmentId}

All fields optional — send only what you want to change.

Field	Type	Notes
title	string	1–200.
items	array	Same shape/rules as create (2–50, distinct, owned). Replaces the item set.
default_mode	"classic" | "widget"	—
time_limit_seconds	number | null	—
shuffle_items	boolean	—
show_results	boolean	—
slug	string	Custom public slug (≤80). Validated for format + uniqueness; 400 INVALID_SLUG if taken or malformed.

Returns the updated collection (same shape as Get). 404 if it is not yours; 400 QUIZ_NOT_FOUND / INVALID_ITEMS on bad items.

Pro plan + scope

The API needs the Pro plan (an api_access entitlement) and a key with the api:collection:read / api:collection:write scope. Prefer plain language? The Claude Connector exposes the same as create_collection / list_collections / get_collection / update_collection.