Skip to content

Tags

Tag management endpoints. Tags are flat labels assigned to content for easier discovery and grouping. Unlike categories, tags have no hierarchy.

Base path: /api/v1/tags

List Tags

GET /api/v1/tags

Required permission: tags:read

Query parameters

Parameter Type Default Description
skip int 0 Pagination offset
limit int 100 Pagination limit

Response 200 OK 

[
  {
    "id": "uuid",
    "slug": "fifa",
    "is_active": true
  }
]

Create Tag

POST /api/v1/tags

Required permission: tags:create

Request body 

{
  "slug": "fifa",
  "is_active": true,
  "translations": [
    {
      "language_id": "uuid",
      "name": "FIFA"
    }
  ]
}

Field Type Required Constraints
slug string ✅ 2–255 characters, unique
is_active bool ❌ Default: true
translations array ❌ List of translations

Response 201 Created — full TagResponse object.

Errors

Status Description
409 Tag slug already exists

Get Tag

GET /api/v1/tags/{id}

Required permission: tags:read

Response 200 OK 

{
  "id": "uuid",
  "slug": "fifa",
  "is_active": true,
  "created_by": "uuid",
  "translations": [
    {
      "id": "uuid",
      "tag_id": "uuid",
      "language_id": "uuid",
      "name": "FIFA",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": null
    }
  ],
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": null
}

Errors

Status Description
404 Tag not found

Update Tag

PATCH /api/v1/tags/{id}

Required permission: tags:update

Request body — all fields optional 

{
  "slug": "fifa-world-cup",
  "is_active": false
}

Response 200 OK — updated TagResponse object.

Errors

Status Description
404 Tag not found
409 Tag slug already exists

Delete Tag

Soft-deletes a tag. 

DELETE /api/v1/tags/{id}

Required permission: tags:delete

Response 204 No Content

Errors

Status Description
404 Tag not found

Upsert Translation

Creates or updates a translation for a specific language. If a translation for the given language already exists, it will be updated. 

PUT /api/v1/tags/{id}/translations

Required permission: tags:update

Request body 

{
  "language_id": "uuid",
  "name": "FIFA"
}

Field Type Required Constraints
language_id UUID ✅ Must exist in DB
name string ✅ Min 1 character

Response 200 OK — updated TagResponse object.

Errors

Status Description
404 Tag not found
404 Language not found

Delete Translation

Removes a translation for a specific language from a tag. 

DELETE /api/v1/tags/{id}/translations/{language_id}

Required permission: tags:update

Response 200 OK — updated TagResponse object.

Errors

Status Description
404 Tag not found
404 Translation not found