Collections

Collections are reusable data tables in your workspace (e.g. Teams, Players, Venues, Sponsors). Each collection has a defined schema of typed fields, and contains items (rows).

List Collections

Returns all collections in your workspace.

GET /api/cms/collections

Auth: read

Request:

curl https://ideal-heron-677.convex.site/api/cms/collections \
  -H "Authorization: Bearer lw_your_key"

Response:

{
  "collections": [
    {
      "_id": "j572abc123...",
      "name": "Teams",
      "icon": "🏈",
      "titleField": "name",
      "fields": [
        { "key": "name", "label": "Team Name", "type": "text" },
        { "key": "abbreviation", "label": "Abbreviation", "type": "text" },
        { "key": "logo", "label": "Logo", "type": "image" },
        { "key": "primaryColor", "label": "Primary Color", "type": "color" }
      ],
      "ownerType": "team",
      "ownerId": "j572teamid...",
      "updatedAt": 1711929600000
    }
  ]
}

List Collection Items

Returns paginated items from a specific collection.

POST /api/cms/collections/by-id/items

Auth: read

Request:

curl -X POST https://ideal-heron-677.convex.site/api/cms/collections/by-id/items \
  -H "Authorization: Bearer lw_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionId": "j572abc123...",
    "limit": 50,
    "cursor": null
  }'

Field	Type	Required	Description
`collectionId`	string	Yes	The collection ID
`limit`	number	No	Page size (1-100, default 50)
`cursor`	string or null	No	Pagination cursor from a previous response

Response:

{
  "items": [
    {
      "_id": "j572item1...",
      "collectionId": "j572abc123...",
      "data": {
        "name": "Dallas Cowboys",
        "abbreviation": "DAL",
        "logo": "j572assetid...",
        "primaryColor": "#003594"
      },
      "updatedAt": 1711929600000
    }
  ],
  "cursor": "eyJwb3...",
  "isDone": false
}

Pass the returned cursor in the next request to fetch the next page. When isDone is true, there are no more items.

Create Collection Item

Add a new item to a collection. The data object must conform to the collection's field schema.

POST /api/cms/collections/items/create

Auth: readwrite

Request:

curl -X POST https://ideal-heron-677.convex.site/api/cms/collections/items/create \
  -H "Authorization: Bearer lw_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionId": "j572abc123...",
    "data": {
      "name": "Philadelphia Eagles",
      "abbreviation": "PHI",
      "primaryColor": "#004C54"
    }
  }'

Field	Type	Required	Description
`collectionId`	string	Yes	The collection to add the item to
`data`	object	Yes	Field values conforming to the collection schema

Response (201):

{
  "itemId": "j572newitem..."
}

Update Collection Item

Patch an existing item's data. Only the provided fields are updated; other fields remain unchanged.

POST /api/cms/collections/items/update

Auth: readwrite

Request:

curl -X POST https://ideal-heron-677.convex.site/api/cms/collections/items/update \
  -H "Authorization: Bearer lw_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "itemId": "j572item1...",
    "data": {
      "primaryColor": "#006778"
    }
  }'

Field	Type	Required	Description
`itemId`	string	Yes	The collection item ID to update
`data`	object	Yes	Partial field values to merge into the existing data

Response:

{
  "ok": true
}

Updating a collection item automatically triggers snapshot and manifest refresh for all productions that reference it.

Delete (Archive) Collection Item

Archive a collection item. Archived items are hidden from list queries but remain in the database.

POST /api/cms/collections/items/delete

Auth: readwrite

Request:

curl -X POST https://ideal-heron-677.convex.site/api/cms/collections/items/delete \
  -H "Authorization: Bearer lw_your_key" \
  -H "Content-Type: application/json" \
  -d '{"itemId": "j572item1..."}'

Field	Type	Required	Description
`itemId`	string	Yes	The collection item ID to archive

Response:

{
  "ok": true
}

Field Types

Collection fields use typed schemas. Valid field types:

Type	Description	Example Value
`text`	Short text	`"Dallas Cowboys"`
`longText`	Multi-line text	`"A longer description..."`
`number`	Numeric value	`42`
`boolean`	True/false	`true`
`select`	Single choice from options	`"home"`
`multiSelect`	Multiple choices	`["offense", "defense"]`
`color`	Hex color code	`"#003594"`
`image`	Reference to a graphic asset ID	`"j572assetid..."`
`date`	Unix timestamp (ms)	`1711929600000`
`url`	URL string	`"https://example.com"`
`reference`	ID of an item in another collection	`"j572otheritem..."`

Error Cases

Error	Cause
`"Collection not found"`	ID is invalid or collection is not in your workspace
`"Item not found"`	Item ID is invalid or not in your workspace
`"Missing required field: name"`	A required field was not provided
`"Field \"foo\" has invalid type"`	Value does not match the field's declared type

Collections

List Collections

List Collection Items

Create Collection Item

Update Collection Item

Delete (Archive) Collection Item

Field Types

Error Cases

On this page