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
page int 1 Page number
per_page int 20 Items per page
slug string — Filter by slug (case-insensitive)
is_active boolean — Filter by active status

Response 200 OK 

{
  "data": [
    {
      "id": "uuid",
      "slug": "fifa",
      "is_active": true
    }
  ],
  "pagination": {
    "total": 50,
    "page": 1,
    "per_page": 20,
    "pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

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