Informes: referencia de la API, endpoints y ejemplos

OpenAPI YAML OpenAPI JSON problemas YAML Resumen de la API

Este grupo tiene 8 operaciones, generadas a partir de api/openapi.yaml. Filtre por ruta, acción o autenticación. Cada endpoint indica sus entradas; despliéguelo para ver una plantilla de solicitud y los códigos de respuesta. Las plantillas necesitan sus propios valores y un cuerpo válido según el esquema.

Reemplace los marcadores en mayúsculas con sus valores. Para una solicitud JSON, guarde un cuerpo que coincida con el esquema en request.json. Los ejemplos de cookies usan un frasco de cookies local de una sesión autenticada.

Informes: resúmenes por carpeta y etiqueta, archivos CSV, XLSX y PDF y envíos programados por correo

GET/api/reports¶

Listar los tipos de informe

Lista los tipos de informe que construye GET /api/reports/{kind}, con los filtros de cada uno, y los formatos en que se escribe un informe. Requiere la capacidad de informes.

Autenticación: projectBearer O dashboardSession
Cuerpo de la solicitud: ninguno
ID de operación: listReportKinds

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/reports'

Respuestas

Estado	Significado	Cuerpo y encabezados
200	Los tipos de informe.	ReportCatalog (application/json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

GET/api/reports/{kind}¶

Obtener un informe

Genera un informe a partir de los agregados del proyecto (resúmenes de disponibilidad, filas de alertas, estado de las pantallas, entrega de campañas directas), nunca de eventos sin procesar. fleet_health, uptime, publishing y alerts agrupan por group_by folder (por defecto), screen o tag en los días UTC inclusivos de from a to (por defecto los últimos 30): una carpeta contiene cada pantalla que hay en ella y en sus carpetas hijas, y su primera fila es el proyecto completo; folder_id limita el informe a una carpeta y a lo que contiene, y con direct a la carpeta y sus carpetas hijas (o, agrupado por pantalla, a las pantallas que están directamente en ella). alert_log lista cada alerta iniciada en el periodo. proof_of_play suma las reproducciones de las campañas directas del proyecto por campaña, medio y pantalla, para una campaign_id o todas las campañas de un anunciante. format json (por defecto) devuelve la tabla; csv, xlsx y pdf devuelven la misma tabla como archivo adjunto. fleet_health como JSON está en todos los planes; cualquier otro tipo, y cualquier formato de archivo, necesita la función de plan informes (402 feature_not_in_plan).

Autenticación: projectBearer O dashboardSession
Cuerpo de la solicitud: ninguno
ID de operación: getReport

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.
kind	ruta	requerido	El tipo de informe (GET /api/reports).
formato	consulta	opcional	json (por defecto) devuelve el informe como JSON. csv, xlsx y pdf devuelven las mismas filas como archivo adjunto (cada página de un informe paginado, hasta 50000 filas).
desde	consulta	opcional	Primer día UTC, inclusivo. Por defecto 29 días antes de to. Como máximo 366 días con to.
a	consulta	opcional	Último día UTC, inclusive. Por defecto hoy (UTC).
group_by	consulta	opcional	Qué es una fila. No aplica a alert_log ni proof_of_play.
folder_id	consulta	opcional	Solo esta carpeta de pantallas y todo lo que contiene.
direct	consulta	opcional	Con folder_id: solo las pantallas directamente en la carpeta (group_by screen), o la carpeta y sus carpetas hijas (group_by folder).
etiqueta	consulta	opcional	Solo las pantallas con esta etiqueta.
campaign_id	consulta	opcional	proof_of_play: una campaña directa.
advertiser	consulta	opcional	proof_of_play: las campañas de este anunciante o patrocinador (nombre exacto, sin distinguir mayúsculas).

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/reports/KIND'

Respuestas

Estado	Significado	Cuerpo y encabezados
200	El informe como tabla, o como archivo para csv, xlsx y pdf.	Informe (application/json), cadena (text/csv), cadena (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet), cadena (application/pdf); encabezados: Cache-Control
400	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)
402	feature_not_in_plan — Los informes forman parte de Plus: todos los tipos salvo fleet_health como JSON, y csv, xlsx y pdf de cualquier tipo, los necesitan. fleet_health como JSON (el formato predeterminado) está abierto en todos los planes, al igual que los tipos de informe y las exportaciones de las rutas de informes existentes. El problema nombra la función, el plan del proyecto y required_plan.	Problema (application/problem+json)
403	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)
404	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

GET/api/report-subscriptions¶

Listar las suscripciones a informes

Lista los informes programados del proyecto, del más antiguo al más reciente (como máximo 50), cada uno con su próximo envío y el resultado del último. Requiere la capacidad del proyecto.

Autenticación: projectBearer O dashboardSession
Cuerpo de la solicitud: ninguno
ID de operación: listReportSubscriptions

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/report-subscriptions'

Respuestas

Estado	Significado	Cuerpo y encabezados
200	Las suscripciones a informes del proyecto.	ReportSubscriptionList (application/json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

POST/api/report-subscriptions¶

Crear suscripción a un informe

Programa el envío de un informe por correo, como adjunto PDF, XLSX o CSV, cada día, semana o mes a una hora en una zona horaria.

Cada envío cubre el periodo anterior, en días UTC: el día anterior, los siete días anteriores o el mes pasado. recipients son miembros del proyecto, indicados por user_id o por la dirección de correo del miembro; cualquier otra persona se rechaza, así que una suscripción nunca sirve para escribir a un extraño, y un miembro que se va deja de recibirla.

Una ejecución fallida se reintenta y aparece con last_status failed y last_error. Como máximo 50 por organización en todos sus proyectos (report_subscription_limit_reached).

Autenticación: projectBearer O dashboardSession
Cuerpo de la solicitud: ReportSubscriptionWrite
ID de operación: createReportSubscription

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.
Idempotency-Key	encabezado	opcional	Omitir para una operación nueva. Proporcione y reutilice una clave para deduplicar reintentos; el CLI gestiona las claves automáticamente.

Campos del cuerpo de la solicitud

Campo	Descripción
nombre (requerido, cadena)	minLength: 1 maxLength: 100
kind (requerido, cadena)	Valores permitidos: "fleet_health", "uptime", "publishing", "alerts", "alert_log", "proof_of_play"
filters (opcional, objeto)	Los filtros del informe distintos de los días (GET /api/reports los lista).
schedule (requerido, ReportSchedule)
format (requerido, cadena)	Valores permitidos: "pdf", "xlsx", "csv"
recipients (requerido, arreglo)	user_id o dirección de correo de miembros del proyecto.
habilitado (opcional, booleano)	predeterminado: true

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/report-subscriptions'

Respuestas

Estado	Significado	Cuerpo y encabezados
201	Creado.	ReportSubscription (application/json); encabezados: ETag
400	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)
402	feature_not_in_plan — Los informes forman parte de Plus. El problema nombra la función, el plan del proyecto y required_plan.	Problema (application/problem+json)
409	report_subscription_limit_reached.	Problema (application/problem+json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

GET/api/report-subscriptions/{id}¶

Obtener una suscripción a un informe

Requiere la capacidad del proyecto.

Autenticación: projectBearer O dashboardSession
Cuerpo de la solicitud: ninguno
ID de operación: getReportSubscription

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.
id	ruta	requerido

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/report-subscriptions/RESOURCE_ID'

Respuestas

Estado	Significado	Cuerpo y encabezados
200	Una suscripción a un informe.	ReportSubscription (application/json); encabezados: ETag
404	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

PATCH/api/report-subscriptions/{id}¶

Actualizar una suscripción a un informe

Cambia cualquiera de name, filters, schedule, format, recipients y enabled; el tipo de informe nunca cambia. Una programación modificada o una suscripción reactivada se reinicia en su siguiente ocurrencia. If-Match lleva la revisión leída (revision_conflict si está desactualizada).

Autenticación: projectBearer O dashboardSession
Cuerpo de la solicitud: ReportSubscriptionPatch
ID de operación: updateReportSubscription

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.
id	ruta	requerido
Idempotency-Key	encabezado	opcional	Omitir para una operación nueva. Proporcione y reutilice una clave para deduplicar reintentos; el CLI gestiona las claves automáticamente.
If-Match	encabezado	opcional	La revisión de la suscripción, entre comillas o sin ellas.

Campos del cuerpo de la solicitud

Campo	Descripción
nombre (opcional, cadena)	minLength: 1 maxLength: 100
filters (opcional, objeto)
schedule (opcional, ReportSchedule)
format (opcional, cadena)	Valores permitidos: "pdf", "xlsx", "csv"
recipients (opcional, arreglo)
habilitado (opcional, booleano)

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/report-subscriptions/RESOURCE_ID'

Respuestas

Estado	Significado	Cuerpo y encabezados
200	Actualizada.	ReportSubscription (application/json); encabezados: ETag
400	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)
402	feature_not_in_plan — Los informes forman parte de Plus; un cambio que solo desactiva la suscripción sigue abierto. El problema nombra la función, el plan del proyecto y required_plan.	Problema (application/problem+json)
404	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)
409	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

ELIMINAR/api/report-subscriptions/{id}¶

Eliminar suscripción a un informe

Elimina la suscripción; no se envía nada más.

Autenticación: projectBearer O dashboardSession
Cuerpo de la solicitud: ninguno
ID de operación: deleteReportSubscription

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.
id	ruta	requerido
Idempotency-Key	encabezado	opcional	Omitir para una operación nueva. Proporcione y reutilice una clave para deduplicar reintentos; el CLI gestiona las claves automáticamente.

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/report-subscriptions/RESOURCE_ID'

Respuestas

Estado	Significado	Cuerpo y encabezados
204	Eliminado.	sin cuerpo
404	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

POST/api/report-subscriptions/{id}/send¶

Enviar una suscripción a un informe

Envía el informe a los destinatarios de la suscripción ahora, para el periodo que cubriría un envío programado ahora, sin mover su programación. La respuesta es la suscripción con el resultado de este envío (last_status delivered o failed, last_error).

Autenticación: projectBearer O dashboardSession
Cuerpo de la solicitud: ninguno
ID de operación: sendReportSubscription

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.
id	ruta	requerido
Idempotency-Key	encabezado	opcional	Omitir para una operación nueva. Proporcione y reutilice una clave para deduplicar reintentos; el CLI gestiona las claves automáticamente.

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/report-subscriptions/RESOURCE_ID/send'

Respuestas

Estado	Significado	Cuerpo y encabezados
200	La suscripción con el resultado de este envío.	ReportSubscription (application/json)
404	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)