Sliders

Slider management endpoints. A slider is a collection of ordered slides used for hero sections, promotional banners, and featured content. Sliders are standalone entities that can be referenced from page sections.

Base path: /api/v1/sliders

---

List Sliders

GET /api/v1/sliders

Required permission: sliders: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)

Response 200 OK

{
  "data": [
    {
      "id": "uuid",
      "slug": "hero-slider",
      "is_active": true,
      "width": 1920,
      "height": 600,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": null
    }
  ],
  "pagination": {
    "total": 10,
    "page": 1,
    "per_page": 20,
    "pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

---

Create Slider

POST /api/v1/sliders

Required permission: sliders:create

Request body

{
  "slug": "hero-slider",
  "is_active": true,
  "width": 1920,
  "height": 600
}

Field	Type	Required	Constraints
slug	string	✅	2–255 characters, unique
is_active	bool	❌	Default: true
width	int	❌	Default: 1920, min: 1
height	int	❌	Default: 600, min: 1

Response 201 Created — full SliderResponse object.

Errors

Status	Description
409	Slider slug already exists

---

Get Slider

GET /api/v1/sliders/{id}

Required permission: sliders:read

Response 200 OK

{
  "id": "uuid",
  "slug": "hero-slider",
  "is_active": true,
  "width": 1920,
  "height": 600,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": null,
  "slides": [
    {
      "id": "uuid",
      "slider_id": "uuid",
      "type": "image",
      "order": 0,
      "is_active": true,
      "image_id": "uuid",
      "reference_id": null,
      "image": {
        "id": "uuid",
        "filename": "550e8400.jpg",
        "original_filename": "hero-banner.jpg",
        "mime_type": "image/jpeg",
        "size": 204800,
        "path": "uploads/media/550e8400.jpg",
        "alt_text": "Hero banner"
      },
      "translations": [
        {
          "id": "uuid",
          "slide_id": "uuid",
          "language_id": "uuid",
          "data": {
            "title": "Welcome",
            "subtitle": "We build great things",
            "cta_text": "Learn more",
            "cta_url": "/about"
          }
        }
      ],
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": null
    }
  ]
}

Errors

Status	Description
404	Slider not found

---

Update Slider

PATCH /api/v1/sliders/{id}

Required permission: sliders:update

Request body — all fields optional

{
  "slug": "hero-slider-updated",
  "is_active": false,
  "width": 1280,
  "height": 480
}

Response 200 OK — updated SliderResponse object.

Errors

Status	Description
404	Slider not found
409	Slider slug already exists

---

Delete Slider

DELETE /api/v1/sliders/{id}

Required permission: sliders:delete

Response 204 No Content

Warning

Deleting a slider permanently removes all its slides and their translations.

Errors

Status	Description
404	Slider not found

---

Create Slide

POST /api/v1/sliders/{id}/slides

Required permission: sliders:update

Request body

{
  "type": "image",
  "order": 0,
  "is_active": true,
  "image_id": "uuid",
  "reference_id": null,
  "translations": [
    {
      "language_id": "uuid",
      "data": {
        "title": "Welcome",
        "subtitle": "We build great things",
        "cta_text": "Learn more",
        "cta_url": "/about"
      }
    }
  ]
}

Field	Type	Required	Constraints
type	string	✅	One of: image, post, page, custom
order	int	❌	Default: 0, min: 0
is_active	bool	❌	Default: true
image_id	UUID	❌	Must exist in media. Not allowed for custom
reference_id	UUID	⚠️	Required for post and page types
translations	array	❌	List of language-specific data

Slide type rules

Type	image_id	reference_id	data fields
image	Optional	—	title?, subtitle?, cta_text?, cta_url?
post	Optional	✅ Required	title?, subtitle?, cta_text?
page	Optional	✅ Required	title?, subtitle?, cta_text?
custom	—	—	html

Response 200 OK — updated SliderResponse object.

Errors

Status	Description
400	Invalid data for slide type
400	reference_id required for this slide type
400	Custom slides do not use image_id
404	Slider not found
404	Image not found
404	Language not found

---

Update Slide

PATCH /api/v1/sliders/{id}/slides/{slide_id}

Required permission: sliders:update

Request body — all fields optional

{
  "order": 1,
  "is_active": false,
  "image_id": "uuid",
  "reference_id": "uuid",
  "translations": [
    {
      "language_id": "uuid",
      "data": {
        "title": "Updated title"
      }
    }
  ]
}

translations is an optional list — if provided, each entry is upserted by the slide_id + language_id combination. Existing translations for a given language will be updated; if no translation exists for that language, a new record will be created.

Response 200 OK — updated SliderResponse object.

Errors

Status	Description
400	Invalid data for slide type
400	Slide type does not use reference_id
404	Slider not found
404	Slide not found in this slider
404	Image not found
404	Language not found

---

Delete Slide

DELETE /api/v1/sliders/{id}/slides/{slide_id}

Required permission: sliders:delete

Response 204 No Content

Errors

Status	Description
404	Slider not found
404	Slide not found in this slider

---

Reorder Slides

Updates the order field for multiple slides in a single request.

PATCH /api/v1/sliders/{id}/slides/reorder

Required permission: sliders:update

Request body

{
  "slides": [
    { "id": "uuid", "order": 0 },
    { "id": "uuid", "order": 1 },
    { "id": "uuid", "order": 2 }
  ]
}

Response 200 OK — updated SliderResponse object.

Errors

Status	Description
404	Slider not found
404	Slide not found in this slider