Tags

Tags are structured metadata on media items, organized as label (group) → value[] pairs. For example: { "color": ["red", "blue"], "category": ["product"] }.

Tags are stored inside metadata.tags (JSONB) on the media record.

Add a Tag

Add a single tag value to a media item.

Endpoint

POST /api/media/{mediaId}/tags

Request Body

Field	Type	Required	Description
`label`	string	Yes	Tag group name (e.g. `"color"`)
`value`	string	Yes	Tag value to add (e.g. `"red"`)

Example Request

curl -X POST https://lab.coreviz.io/api/media/MEDIA_ID/tags \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "color", "value": "red" }'

Response

Status Code: 200 OK — returns the updated media object.

{ "media": { "id": "...", "metadata": { "tags": { "color": ["red"] } }, ... } }

409 Conflict if the tag value already exists on this item.

Remove a Tag

Remove a single tag value from a media item. If this was the last value in the group, the group is removed entirely.

Endpoint

DELETE /api/media/{mediaId}/tags

Request Body

Field	Type	Required	Description
`label`	string	Yes	Tag group name
`value`	string	Yes	Tag value to remove

Example Request

curl -X DELETE https://lab.coreviz.io/api/media/MEDIA_ID/tags \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "color", "value": "red" }'

Response

Status Code: 200 OK — returns the updated media object.

Aggregate all unique tag groups and their distinct values across an entire collection.

Endpoint

GET /api/dataset/{collectionId}/tags

Example Request

curl -H "x-api-key: YOUR_API_KEY" \
  "https://lab.coreviz.io/api/dataset/COLLECTION_ID/tags"

Response

Status Code: 200 OK

{
  "tags": {
    "color": ["blue", "green", "red"],
    "category": ["editorial", "lifestyle", "product"],
    "season": ["fall", "spring", "summer"]
  }
}

Values within each group are sorted alphabetically. Only groups with at least one active, current-version media item are returned.

Filtering by Tags

Use the tagFilters query parameter on GET /api/dataset/{collectionId}/media to filter results by tag:

# Items tagged with color=red AND (season=spring OR season=fall)
curl -H "x-api-key: YOUR_API_KEY" \
  "https://lab.coreviz.io/api/dataset/COLLECTION_ID/media?tagFilters=%7B%22color%22%3A%5B%22red%22%5D%2C%22season%22%3A%5B%22spring%22%2C%22fall%22%5D%7D"

The filter logic is: AND between groups, OR within a group.

JavaScript Example

const headers = { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' };

// Add tag
await fetch('https://lab.coreviz.io/api/media/MEDIA_ID/tags', {
  method: 'POST',
  headers,
  body: JSON.stringify({ label: 'color', value: 'red' }),
});

// Remove tag
await fetch('https://lab.coreviz.io/api/media/MEDIA_ID/tags', {
  method: 'DELETE',
  headers,
  body: JSON.stringify({ label: 'color', value: 'red' }),
});

// List all tags in a collection
const { tags } = await fetch(
  'https://lab.coreviz.io/api/dataset/COLLECTION_ID/tags',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
).then(r => r.json());

Tags

On this page