Endpoint

Tutti i percorsi iniziano con https://cloud.viewneo.com/api/public/v1. Parametri e risposte di ogni endpoint sono descritti nel riferimento interattivo.

Le aree

Area	Percorsi	Scope
File multimediali	/media, /media/{id}, /media/websites, /media/folders	media:*
Caricamento	/media/uploads, …/{id}/parts, …/{id}/complete	media:write
Modelli	/templates, /templates/{id}, /templates/{id}/contents, /template-contents/{id}	media:*
Playlist	/playlists, /playlists/{id}	playlists:*
Voci delle playlist	/playlists/{id}/entries, …/entries/order, …/entries/{entryId}	playlists:*
Dispositivi	/devices, /devices/{id}, /devices/activate	devices:*
Gruppi di dispositivi	/device-groups, /device-groups/{id}	devices:*
Report	/reports/device-log/{deviceId}, /reports/media/{id}/…	reports:read
OAuth	/oauth/token	–

Richieste e risposte

• Body JSON con Content-Type: application/json. I campi sconosciuti vengono rifiutati con 400 VALIDATION_ERROR – così gli errori di battitura emergono subito.
• Date e orari sono in ISO 8601 in UTC, ad es. 2026-10-05T14:30:00.000Z.
• Gli ID sono UUID; non interpretarli.
• PATCH modifica solo i campi che invii. null cancella un riferimento facoltativo – ad esempio la playlist propria di un dispositivo, che riproduce allora la playlist del suo gruppo.
• I dispositivi applicano le modifiche da soli; non devi pubblicare nulla.

Paginazione

Gli elenchi di file multimediali, playlist e dispositivi sono paginati: ?page=2&limit=50 (limit 1–100, predefinito 50). La risposta contiene pagination con page, limit, total e totalPages.

I report usano un cursore: passa il nextCursor restituito come ?cursor=. nextCursor: null significa che hai ricevuto tutto.

Errori

Gli errori hanno sempre la stessa forma:

{
  "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"
}

Valuta error.code, non il testo. I codici più importanti:

Stato	Codice	Significato
400	VALIDATION_ERROR, INVALID_INPUT	un parametro o un campo manca o non è valido
401	UNAUTHORIZED, TOKEN_INVALID	il token manca, è sconosciuto, revocato o scaduto
403	FORBIDDEN	manca lo scope – oppure, per i report sui file multimediali, il plugin Reports
403	SUBSCRIPTION_REQUIRED	il plugin API non è attivato
404	NOT_FOUND	non esiste nel tuo account
409	LICENSE_LIMIT_REACHED, PLAYER_LIMIT_REACHED	nessuna licenza libera per un altro player
429	QUOTA_EXCEEDED	limite raggiunto, vedi sotto
502 / 503	UPSTREAM_ERROR, SERVICE_UNAVAILABLE	temporaneo – riprova più tardi

Ogni risposta porta l’header X-Correlation-Id. Indicalo quando ti rivolgi al supporto.

Limiti

Ogni token può effettuare 60 richieste al minuto. Gli header X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset mostrano lo stato. Oltre questa soglia l’API risponde con 429 QUOTA_EXCEEDED e l’header Retry-After (secondi). Distribuisci i lavori grandi nel tempo, invece di inviarli in parallelo.

Report

I report contengono solo dati dei dispositivi su cui è attivo Report (di fabbrica disattivato). Il registro del dispositivo arriva fino a 7 giorni indietro; i report sui file multimediali richiedono il plugin Reports e arrivano fino a 90 giorni indietro, con l’opzione Extended 365 giorni. Senza from/to vale la giornata odierna (dalle 00:00 UTC).