Endpunkte

Alle Pfade beginnen mit https://cloud.viewneo.com/api/public/v1. Parameter und Antworten jedes Endpunkts beschreibt die interaktive Referenz.

Die Bereiche

Bereich	Pfade	Scope
Medien	/media, /media/{id}, /media/websites, /media/folders	media:*
Upload	/media/uploads, …/{id}/parts, …/{id}/complete	media:write
Templates	/templates, /templates/{id}, /templates/{id}/contents, /template-contents/{id}	media:*
Playlists	/playlists, /playlists/{id}	playlists:*
Playlist-Einträge	/playlists/{id}/entries, …/entries/order, …/entries/{entryId}	playlists:*
Geräte	/devices, /devices/{id}, /devices/activate	devices:*
Gerätegruppen	/device-groups, /device-groups/{id}	devices:*
Reports	/reports/device-log/{deviceId}, /reports/media/{id}/…	reports:read
OAuth	/oauth/token	–

Anfragen und Antworten

• JSON-Bodys mit Content-Type: application/json. Unbekannte Felder werden mit 400 VALIDATION_ERROR abgelehnt – so fallen Tippfehler sofort auf.
• Zeitangaben sind ISO 8601 in UTC, z. B. 2026-10-05T14:30:00.000Z.
• IDs sind UUIDs; werte sie nicht aus.
• PATCH ändert nur die Felder, die du schickst. null löscht einen optionalen Verweis – etwa die eigene Playlist eines Geräts, das dann die Playlist seiner Gruppe spielt.
• Geräte übernehmen Änderungen selbst; veröffentlichen musst du nichts.

Seitenaufteilung

Listen von Medien, Playlists und Geräten sind seitenweise: ?page=2&limit=50 (limit 1–100, Vorgabe 50). Die Antwort enthält pagination mit page, limit, total und totalPages.

Reports arbeiten mit einem Cursor: Gib das zurückgelieferte nextCursor als ?cursor= mit. nextCursor: null heißt, du hast alles.

Fehler

Fehler haben immer dieselbe Form:

{
  "success": false,
  "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed",
             "details": [{ "field": "limit", "errors": ["limit must not be greater than 100"] }] },
  "correlationId": "7986ab46-9ccb-43c1-86b3-1abefa3bab98"
}

Werte error.code aus, nicht den Text. Die wichtigsten Codes:

Status	Code	Bedeutung
400	VALIDATION_ERROR, INVALID_INPUT	Parameter oder Feld fehlt oder ist ungültig
401	UNAUTHORIZED, TOKEN_INVALID	Token fehlt, ist unbekannt, widerrufen oder abgelaufen
403	FORBIDDEN	Scope fehlt – oder bei Medien-Reports das Reports-Plugin
403	SUBSCRIPTION_REQUIRED	das API-Plugin ist nicht gebucht
404	NOT_FOUND	gibt es in deinem Konto nicht
409	LICENSE_LIMIT_REACHED, PLAYER_LIMIT_REACHED	keine freie Lizenz für einen weiteren Player
429	QUOTA_EXCEEDED	Limit erreicht, siehe unten
502 / 503	UPSTREAM_ERROR, SERVICE_UNAVAILABLE	vorübergehend – später erneut versuchen

Jede Antwort trägt den Header X-Correlation-Id. Gib ihn an, wenn du dich an den Support wendest.

Limits

Jedes Token darf 60 Anfragen pro Minute stellen. Die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset zeigen den Stand. Darüber antwortet die API mit 429 QUOTA_EXCEEDED und dem Header Retry-After (Sekunden). Verteile große Aufträge über die Zeit, statt sie parallel abzuschicken.

Reports

Reports enthalten nur Daten von Geräten, bei denen Reports eingeschaltet ist (ab Werk aus). Das Geräte-Log reicht 7 Tage zurück; Medien-Reports brauchen das Reports-Plugin und reichen 90 Tage zurück, mit der Option Extended 365 Tage. Ohne from/to gilt der heutige Tag (ab 00:00 UTC).