Medien (öffentlich)

Die öffentlichen Medien-Endpunkte liefern Bilder und Dateien aus der PIM-Mediathek, die für die Website freigegeben sind. Für das CMS mit Token gibt es eigene Endpunkte, siehe Medien für das CMS.

Methode	Pfad	Anmeldung
`GET`	`/media`	keine
`GET`	`/media/{media}`	keine
`GET`	`/media-folders`	keine
`GET`	`/image-formats`	keine

Was ist öffentlich?

Ein Asset erscheint nur, wenn alle Bedingungen erfüllt sind:

Freigabestatus „Freigegeben – uneingeschränkt“ oder „Freigegeben – nur bestimmte Kanäle“ mit dem Kanal Website.
Nicht abgelaufen: „Gültig bis“ ist leer oder liegt in der Zukunft.
Es liegt in einem aktiven Ordner oder in gar keinem Ordner.
Es liegt nicht im Papierkorb.

Felder eines Mediums

Feld	Typ	Bedeutung
`id`	Integer	Interne ID
`name`	String	Anzeigename
`file_name`	String	Dateiname
`mime_type`	String	z. B. `image/jpeg`, `application/pdf`
`type`	String	Asset-Typ: `image`, `datasheet`, `manual`, `brochure`, `three_d_view`, `view_360`, `technical_drawing`, `video`, `audio`, `logo`, `icon`, `cad`, `interactive_image`
`usages`	String[]	Nur bei Bildern, die über ein Produkt kommen: wofür die Verknüpfung gedacht ist (`configurator`, `price_list`, `website`, `catalog`)
`size`	Integer	Dateigröße in Byte
`url`	String \| null	URL der Originaldatei. `null`, wenn die Datei noch nicht ins PIM übernommen wurde
`thumb_url`	String \| null	URL des Vorschaubilds `thumb`, falls erzeugt
`conversions`	Objekt	Erzeugte Bildformate: Schlüssel → `{ url, width, height, fit }`. Leer bei Nicht-Bildern und SVG
`srcset`	String \| null	Fertige `srcset`-Zeile, nach Breite sortiert
`alt`	String \| null	Alt-Text in der Server-Sprache (Fallback Deutsch)
`title`	String \| null	Titel in der Server-Sprache
`caption`	String \| null	Bildunterschrift
`description`	String \| null	Beschreibung
`copyright`	String \| null	Copyright / Fotograf
`license`	String \| null	Nutzungsrecht / Lizenz
`ki_status`	String \| null	`ungeprueft_altbestand`, `ki_generiert` oder `kein_ki`
`ki_label`	String \| null	Deutsche Bezeichnung dazu. Bei `ki_generiert` muss die Website das Bild sichtbar kennzeichnen
`folder`	Objekt \| null	`{ id, name, slug }` des Ordners
`created_at`	Datum	Hochgeladen am

width/height in conversions sind die Zielmaße des Formats, nicht die exakten Pixel der Datei. Bei fit: "crop" stimmen sie, bei max ist es die Obergrenze. Für srcset und zum Vorab-Bemaßen eines <img> reicht das.

Medien auflisten

GET /media

Liefert freigegebene Medien, neueste zuerst, seitenweise.

Query-Parameter

Parameter	Typ	Bedeutung
`type`	String	Nur dieser Asset-Typ, z. B. `image`
`renderable`	Boolean (`1`/`0`)	Nur Bilddateien: JPEG, PNG, WebP, AVIF, GIF, TIFF, HEIC/HEIF und SVG. TIFF und HEIC zeigt ein Browser nicht direkt an; nehmen Sie dafür die URLs aus `conversions`. Gut für Bild-Auswahlen: erfasst auch Logos, Icons und Zeichnungen
`ids`	Integer[]	Nur diese IDs, z. B. alle Bilder einer Seite in einer Anfrage: `ids[]=512&ids[]=513`. Eine Komma-Liste (`ids=512,513`) wird nicht verstanden
`folder`	String	Slug eines Ordners
`search`	String	Katalogsuche in Name, Dateiname, Schlagwörtern und Synonymen
`page`	Integer	Seite, Standard 1
`per_page`	Integer	Standard 24, mindestens 1, höchstens 200

Beispiel

curlJavaScriptPHP

bash

curl -sS 'https://admin.matev.eu/api/v1/media?renderable=1&folder=winterdienst&per_page=48' \
  -H 'Accept: application/json'

const params = new URLSearchParams({ renderable: '1', folder: 'winterdienst', per_page: '48' })
const res = await fetch(`https://admin.matev.eu/api/v1/media?${params}`, {
  headers: { Accept: 'application/json' },
})
const { data: media, links } = await res.json()

// Mehrere IDs auf einmal
const ids = [512, 513, 520].map((id) => `ids[]=${id}`).join('&')
const batch = await (await fetch(`https://admin.matev.eu/api/v1/media?${ids}`)).json()

php

use Illuminate\Support\Facades\Http;

$media = Http::acceptJson()
    ->get('https://admin.matev.eu/api/v1/media', [
        'renderable' => 1,
        'folder' => 'winterdienst',
        'per_page' => 48,
    ])
    ->throw()
    ->json('data');

// Laravel sends arrays as ids[0]=512&ids[1]=513, which PHP reads correctly.
$batch = Http::acceptJson()->get('https://admin.matev.eu/api/v1/media', ['ids' => [512, 513]])->json('data');

Antwort `200`

json

{
  "data": [
    {
      "id": 512,
      "name": "SP 250 im Einsatz",
      "file_name": "sp-250-einsatz.jpg",
      "mime_type": "image/jpeg",
      "type": "image",
      "size": 2483112,
      "url": "https://admin.matev.eu/storage/media/512/sp-250-einsatz.jpg",
      "thumb_url": "https://admin.matev.eu/storage/media/512/conversions/sp-250-einsatz-thumb.jpg",
      "conversions": {
        "thumb": { "url": "https://admin.matev.eu/storage/media/512/conversions/sp-250-einsatz-thumb.jpg", "width": 300, "height": 300, "fit": "crop" },
        "tile": { "url": "https://admin.matev.eu/storage/media/512/conversions/sp-250-einsatz-tile.jpg", "width": 480, "height": 480, "fit": "crop" },
        "hero": { "url": "https://admin.matev.eu/storage/media/512/conversions/sp-250-einsatz-hero.jpg", "width": 1920, "height": 1080, "fit": "max" }
      },
      "srcset": "…thumb.jpg 300w, …tile.jpg 480w, …hero.jpg 1920w",
      "alt": "Schneepflug SP 250 räumt einen Hof",
      "title": "SP 250 im Einsatz",
      "caption": null,
      "description": null,
      "copyright": "matev GmbH",
      "license": null,
      "ki_status": "kein_ki",
      "ki_label": "Kein KI",
      "folder": { "id": 7, "name": "Winterdienst", "slug": "winterdienst" },
      "created_at": "2026-02-11T09:14:00+00:00"
    }
  ],
  "links": { "first": "…", "last": "…", "prev": null, "next": null },
  "meta": { "current_page": 1, "per_page": 48, "total": 1, "…": "…" }
}

Fehler

Status	`code`	Wann
405	`method_not_allowed`	andere Methode als `GET`
500	`server_error`	Fehler auf dem Server

Ein Medium abrufen

GET /media/{media}

Pfad-Parameter

Parameter	Typ	Bedeutung
`media`	Integer oder `ext:<ID>`	Interne ID (`512`) oder die ID aus dem Quellsystem Pimcore mit Präfix `ext:` (`ext:4711`)

Die ext:-Form bleibt über Neu-Importe und zwischen Umgebungen gleich. Inhalte, die auf mehreren Installationen funktionieren sollen (Kirby schreibt z. B. pim://ext:4970), sollten diese Form verwenden.

Beispiel

curlJavaScriptPHP

bash

curl -sS https://admin.matev.eu/api/v1/media/ext:4711 \
  -H 'Accept: application/json'

const res = await fetch('https://admin.matev.eu/api/v1/media/ext:4711', {
  headers: { Accept: 'application/json' },
})
if (res.status === 404) {
  // nicht vorhanden oder nicht öffentlich freigegeben
}
const { data: asset } = await res.json()

php

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()->get('https://admin.matev.eu/api/v1/media/ext:4711');
$asset = $response->successful() ? $response->json('data') : null;

Antwort `200`

Ein Objekt wie in der Liste, eingepackt in data:

json

{ "data": { "id": 512, "name": "SP 250 im Einsatz", "type": "image", "…": "…" } }

Fehler

Status	`code`	Wann
404	`not_found`	ID unbekannt, oder das Asset ist nicht öffentlich (Status, Ablauf, Ordner)
405	`method_not_allowed`	andere Methode als `GET`

Medienordner auflisten

GET /media-folders

Liefert den öffentlichen Ordnerbaum: aktive Ordner ohne Rollenbeschränkung, sortiert nach Position und Name. Nicht paginiert.

Die oberste Ebene sind die Wurzelordner. children ist zwei Ebenen tief gefüllt. Auf der dritten Ebene fehlt das Feld children ganz, auch wenn es dort weitere Ordner gibt.

Felder

Feld	Typ	Bedeutung
`id`	Integer	ID
`name`	String	Name
`path`	String	Pfad aus den Namen, z. B. `Produkte / Winterdienst`
`slug`	String	Kennung, für `GET /media?folder=…`
`description`	String \| null	Beschreibung
`parent_id`	Integer \| null	Übergeordneter Ordner
`position`	Integer	Sortierung
`children`	Ordner[]	Unterordner (siehe oben)

Beispiel

curlJavaScriptPHP

bash

curl -sS https://admin.matev.eu/api/v1/media-folders -H 'Accept: application/json'

const { data: folders } = await (await fetch('https://admin.matev.eu/api/v1/media-folders', {
  headers: { Accept: 'application/json' },
})).json()

php

use Illuminate\Support\Facades\Http;

$folders = Http::acceptJson()->get('https://admin.matev.eu/api/v1/media-folders')->throw()->json('data');

Antwort `200`

json

{
  "data": [
    {
      "id": 2,
      "name": "Produkte",
      "path": "Produkte",
      "slug": "produkte",
      "description": null,
      "parent_id": null,
      "position": 1,
      "children": [
        {
          "id": 7,
          "name": "Winterdienst",
          "path": "Produkte / Winterdienst",
          "slug": "winterdienst",
          "description": "Schneepflüge und Streuer",
          "parent_id": 2,
          "position": 3,
          "children": [
            { "id": 31, "name": "Schneepflüge", "path": "Produkte / Winterdienst / Schneepflüge", "slug": "schneepfluege", "description": null, "parent_id": 7, "position": 1 }
          ]
        }
      ]
    }
  ]
}

Fehler

Status	`code`	Wann
405	`method_not_allowed`	andere Methode als `GET`

Bildformate auflisten

GET /image-formats

Liefert die aktiven Bildformate (Renditions), sortiert nach Position. Nicht paginiert. Die Schlüssel (key) sind dieselben wie in conversions und im Parameter format der Vorschau für das CMS.

Fest eingebaut sind thumb (300 × 300, Zuschnitt), mini (120 × 120, Zuschnitt), tile (480 × 480, Zuschnitt), preview (800 × 800, max.) und hero (1920 × 1080, max.). Weitere Formate legt ein Admin in der Mediathek unter „Bildformate“ an.

Felder

Feld	Typ	Bedeutung
`key`	String	Name des Formats
`label`	String	Bezeichnung
`width`, `height`	Integer \| null	Zielmaße in Pixel
`fit`	String	Zuschnitt, z. B. `crop`, `max`, `contain`
`quality`	Integer \| null	JPEG/WebP-Qualität 1–100, `null` = Standard
`position`	Integer	Sortierung

Beispiel

curlJavaScriptPHP

bash

curl -sS https://admin.matev.eu/api/v1/image-formats -H 'Accept: application/json'

const { data: formats } = await (await fetch('https://admin.matev.eu/api/v1/image-formats')).json()

php

use Illuminate\Support\Facades\Http;

$formats = Http::acceptJson()->get('https://admin.matev.eu/api/v1/image-formats')->throw()->json('data');

Antwort `200`

json

{
  "data": [
    { "key": "thumb", "label": "Thumbnail", "width": 300, "height": 300, "fit": "crop", "quality": null, "position": 1 },
    { "key": "hero", "label": "Hero", "width": 1920, "height": 1080, "fit": "max", "quality": 82, "position": 5 }
  ]
}

Fehler

Status	`code`	Wann
405	`method_not_allowed`	andere Methode als `GET`

Medien (öffentlich) ​

Was ist öffentlich? ​

Felder eines Mediums ​

Medien auflisten ​

Query-Parameter ​

Beispiel ​

Antwort 200 ​

Fehler ​

Ein Medium abrufen ​

Pfad-Parameter ​

Beispiel ​

Antwort 200 ​

Fehler ​

Medienordner auflisten ​

Felder ​

Beispiel ​

Antwort 200 ​

Fehler ​

Bildformate auflisten ​

Felder ​

Beispiel ​

Antwort 200 ​

Fehler ​

Medien (öffentlich)

Was ist öffentlich?

Felder eines Mediums

Medien auflisten

Query-Parameter

Beispiel

Antwort `200`

Fehler

Ein Medium abrufen

Pfad-Parameter

Beispiel

Antwort `200`

Fehler

Medienordner auflisten

Felder

Beispiel

Antwort `200`

Fehler

Bildformate auflisten

Felder

Beispiel

Antwort `200`

Fehler