Endpoints

Todas las rutas empiezan por https://cloud.viewneo.com/api/public/v1. Los parámetros y las respuestas de cada endpoint se describen en la referencia interactiva.

Las áreas

Área	Rutas	Scope
Multimedia	/media, /media/{id}, /media/websites, /media/folders	media:*
Subida	/media/uploads, …/{id}/parts, …/{id}/complete	media:write
Plantillas	/templates, /templates/{id}, /templates/{id}/contents, /template-contents/{id}	media:*
Playlists	/playlists, /playlists/{id}	playlists:*
Entradas de playlist	/playlists/{id}/entries, …/entries/order, …/entries/{entryId}	playlists:*
Dispositivos	/devices, /devices/{id}, /devices/activate	devices:*
Grupos de dispositivos	/device-groups, /device-groups/{id}	devices:*
Informes	/reports/device-log/{deviceId}, /reports/media/{id}/…	reports:read
OAuth	/oauth/token	–

Peticiones y respuestas

• Cuerpos JSON con Content-Type: application/json. Los campos desconocidos se rechazan con 400 VALIDATION_ERROR: así, las erratas saltan a la vista enseguida.
• Las fechas y horas van en ISO 8601 en UTC, p. ej., 2026-10-05T14:30:00.000Z.
• Los ID son UUID; no los interpretes.
• PATCH cambia solo los campos que envías. null elimina una referencia opcional, por ejemplo la playlist propia de un dispositivo, que entonces reproduce la playlist de su grupo.
• Los dispositivos adoptan los cambios por sí solos; no tienes que publicar nada.

Paginación

Las listas de archivos multimedia, playlists y dispositivos están paginadas: ?page=2&limit=50 (limit 1–100, por defecto 50). La respuesta contiene pagination con page, limit, total y totalPages.

Los informes funcionan con un cursor: pasa el nextCursor devuelto como ?cursor=. nextCursor: null significa que ya lo tienes todo.

Errores

Los errores tienen siempre la misma 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"
}

Interpreta error.code, no el texto. Los códigos más importantes:

Estado	Código	Significado
400	VALIDATION_ERROR, INVALID_INPUT	falta un parámetro o un campo, o no es válido
401	UNAUTHORIZED, TOKEN_INVALID	el token falta, es desconocido, está revocado o ha caducado
403	FORBIDDEN	falta el scope o, en los informes de multimedia, el complemento Reports
403	SUBSCRIPTION_REQUIRED	el complemento API no está contratado
404	NOT_FOUND	no existe en tu cuenta
409	LICENSE_LIMIT_REACHED, PLAYER_LIMIT_REACHED	no hay ninguna licencia libre para otro reproductor
429	QUOTA_EXCEEDED	límite alcanzado, ver abajo
502 / 503	UPSTREAM_ERROR, SERVICE_UNAVAILABLE	temporal: vuelve a intentarlo más tarde

Cada respuesta lleva la cabecera X-Correlation-Id. Indícala cuando te pongas en contacto con el soporte.

Límites

Cada token puede hacer 60 peticiones por minuto. Las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset muestran el estado. Por encima, la API responde con 429 QUOTA_EXCEEDED y la cabecera Retry-After (segundos). Reparte los trabajos grandes en el tiempo en lugar de enviarlos en paralelo.

Informes

Los informes solo contienen datos de dispositivos que tienen activado Informes (de fábrica, desactivado). El registro del dispositivo abarca 7 días; los informes de multimedia necesitan el complemento Reports y abarcan 90 días, con la opción Extended, 365 días. Sin from/to se aplica el día de hoy (desde las 00:00 UTC).