Schermi: riferimento API, endpoint ed esempi

OpenAPI YAML OpenAPI JSON problemi YAML Panoramica dell’API

Questo gruppo ha 84 operazioni, generate da api/openapi.yaml. Filtra per percorso, azione o autenticazione. Ogni endpoint elenca i suoi input; espandilo per vedere un modello di richiesta e i codici di risposta. I modelli richiedono i tuoi valori e un corpo valido secondo lo schema.

Sostituisci i segnaposto maiuscoli con i tuoi valori. Per una richiesta JSON, salva un corpo che corrisponde allo schema in request.json. Gli esempi di cookie usano un cookie jar locale da una sessione autenticata.

Schermi

GET/api/screens¶

Elenca gli schermi

La lista predefinita restituisce schermi pairing_pending e attivi. Passare state=archived per elencare solo gli schermi archiviati. Passare tag per elencare solo gli schermi i cui tag contengono esattamente quel tag; gli schermi senza tag sono omessi quando il filtro è presente.

Passa field, una volta per campo, come NAME:VALUE per elencare solo gli schermi i cui campi contengono ogni valore, e near come LAT,LON,KM per elencare solo gli schermi situati entro KM chilometri dal punto; gli schermi senza posizione vengono omessi e ogni filtro si combina con state e tag.

Passa folder come ID di una cartella schermi per elencare solo gli schermi direttamente dentro di essa (non quelli delle sue sottocartelle), oppure root per gli schermi fuori da ogni cartella.

Gli schermi sono dal più recente, al massimo 500 per pagina. next_cursor è la posizione dell’ultima riga restituita finché restano altre righe; passalo di nuovo come after, con gli stessi filtri, per la pagina successiva. next_cursor è null nell’ultima pagina. Un chiamante limitato agli schermi (docs/screen-scope.md) elenca solo gli schermi nel suo ambito.

Una richiesta che non nomina alcun progetto esclude ogni progetto in cui il chiamante è limitato agli schermi; nomina il progetto per elencarlo.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: listScreens

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
stato	query	opzionale	Ometti per pairing_pending e active. Passa archived per elencare solo gli schermi archiviati.
tag	query	opzionale	Tag schermo esatto. Gli schermi senza tag sono esclusi quando questo filtro è presente.
field	query	opzionale	NAME:VALUE, diviso al primo segno di due punti: solo gli schermi il cui campo NAME contiene esattamente VALUE. Ripeti il parametro per più campi; ognuno deve corrispondere e un nome può essere indicato una sola volta. Un valore malformato o un nome ripetuto restituisce invalid_request indicando field.
near	query	opzionale	LAT,LON,KM in gradi decimali e chilometri, ad esempio 47.6062,-122.3321,25: solo gli schermi la cui posizione si trova entro KM chilometri dal punto. La latitudine va da -90 a 90, la longitudine da -180 a 180 e KM è maggiore di 0 e al massimo 20038. Gli schermi senza posizione vengono omessi. Un valore malformato restituisce invalid_request indicando near.
cartella	query	opzionale	Un ID cartella schermi conserva solo gli schermi direttamente dentro quella cartella, non quelli delle sue sottocartelle; root conserva solo gli schermi fuori da ogni cartella. Omettere elenca ogni schermo.
dopo	query	opzionale	next_cursor della pagina precedente della stessa lista, con gli stessi filtri. Omettere inizia dalla riga più recente. Un valore che non è tale cursore è invalid_request.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Schermi	ScreenList (application/json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screen-folders¶

Elenca cartelle schermi

Elenca tutte le cartelle schermi nel progetto, massimo 1000, ordinate per nome.

Le cartelle organizzano gli schermi e permettono di sceglierli come destinazione: una foglia di audience di campagna {"folder": ID} corrisponde agli schermi in quella cartella e in ogni cartella al suo interno, un selettore di azione di flotta by:folder agisce sugli stessi schermi, e il default_playlist_id di una cartella è ciò che mostrano i suoi schermi senza una playlist propria. parent_id è null nella radice del progetto; costruisci l’albero da parent_id. screens conta gli schermi attivi direttamente dentro ogni cartella.

La cartella di uno schermo è Screen.folder_id. Un chiamante limitato agli schermi (docs/screen-scope.md) elenca le cartelle dentro il suo ambito e quelle sopra di esse, che sono di sola lettura così il suo albero ha una radice; le cartelle sopra non riportano il numero di schermi e le cartelle sorelle sono nascoste. Una richiesta che non nomina alcun progetto esclude ogni progetto in cui il chiamante è limitato agli schermi.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: listScreenFolders

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Cartelle schermi	ScreenFolderList (application/json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screen-folders¶

Crea cartella schermi

Crea una cartella schermi nella radice del progetto (parent_id nullo o assente) o dentro parent_id. I nomi sono privati di spazi, contengono da 1 a 100 caratteri Unicode senza controlli, non sono "." o ".." e sono univoci tra le cartelle dello stesso livello (resource_conflict).

Un’organizzazione contiene al massimo 1000 cartelle in tutti i suoi progetti (quota_exceeded) annidate al massimo 10 livelli (invalid_request). default_playlist_id, se impostato, deve indicare una playlist approvata (playlist_not_approved). Emette screen.folder_created.

Un chiamante limitato agli schermi (docs/screen-scope.md) crea una cartella solo dentro una cartella del suo ambito; la radice del progetto o qualsiasi altro genitore è outside_screen_scope. Creare una cartella dentro una cartella protetta è una revisione protected_change (202 pending_review) decisa da un secondo approvatore.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ScreenFolderCreate
ID operazione: createScreenFolder

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
nome (obbligatorio, stringa)	Senza spazi iniziali e finali; da 1 a 100 caratteri Unicode, senza controlli, non . o .., univoco tra le cartelle dello stesso livello. minLength: 1 maxLength: 100
parent_id (opzionale, inline)	La cartella in cui crearla; null o assente per la radice del progetto.
default_playlist_id (opzionale, stringa)	Una playlist approvata per gli schermi della cartella che non ne hanno una propria. minLength: 1

Modello richiesta e risposte

shell · modello richiesta

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/screen-folders'

Risposte

Stato	Significato	Corpo e intestazioni
201	Cartella creata.	ScreenFolder (application/json); intestazioni: ETag
202	La scrittura è diventata una revisione e attende l’approvazione di una persona (docs/reviews.md), con accesso Proponi, oppure a qualsiasi livello di accesso quando raggiunge uno schermo in una cartella di schermi protetta, dove la decide un secondo approvatore (docs/screen-scope.md). Una persona approva, rifiuta o richiede modifiche nel dashboard a review.url. Una ripetizione con Idempotency-Key risponde con lo stesso corpo.	ReviewPending (application/json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screen-folders/{id}¶

Ottieni cartella schermi

Un chiamante limitato agli schermi (docs/screen-scope.md) legge le cartelle del suo ambito e quelle sopra di esse; qualsiasi altra cartella, e un id sconosciuto, è outside_screen_scope.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getScreenFolder

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Una cartella schermi.	ScreenFolder (application/json); intestazioni: ETag
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PATCH/api/screen-folders/{id}¶

Aggiorna cartella schermi

Rinomina una cartella (name), la sposta con tutto il contenuto (parent_id, null per la radice del progetto) o imposta la playlist predefinita che mostrano i suoi schermi senza una propria (default_playlist_id, null la cancella). Una cartella non può spostarsi in se stessa o in una cartella al suo interno, e lo spostamento deve mantenere ogni cartella entro 10 livelli (invalid_request).

Uno spostamento o un cambio del valore predefinito rivaluta gli schermi al suo interno entro circa 15 secondi, e i levels della risposta indicano le campagne e i valori predefiniti di cartella che quegli schermi acquisiscono o perdono. Una modifica fa avanzare la revisione della cartella ed emette screen.folder_updated; gli stessi valori sono un’operazione nulla.

If-Match protegge facoltativamente la revisione. protected true protegge la cartella e ogni cartella al suo interno, e false la rimuove; invialo da solo (altrimenti invalid_request). Solo una persona che può approvare lo imposta: un agente, un client di servizio o un membro che non può approvare riceve approver_required.

Una modifica aggiunge screen.folder_protection_changed (details folder_id, protected). Rimuovere la protezione, e uno spostamento o un cambio di playlist predefinita su una cartella che contiene schermi protetti, sono revisioni protected_change (202 pending_review) decise da un secondo approvatore.

Un chiamante limitato agli schermi (docs/screen-scope.md) modifica solo cartelle dentro il suo ambito: anche parent_id deve indicarne una (la radice è outside_screen_scope), e protected non può cambiarlo su una cartella che il suo ambito nomina. protected true rientra nelle cartelle protette, che il piano Enterprise include; un progetto il cui piano ne è privo viene rifiutato con feature_not_in_plan (402).

Una protezione impostata continua a trattenere le modifiche per un secondo approvatore, e chiedere di rimuoverla è una revisione in ogni piano.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ScreenFolderPatch
ID operazione: updateScreenFolder

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
nome (opzionale, stringa)	Senza spazi iniziali e finali; da 1 a 100 caratteri Unicode, senza controlli, non . o .., univoco tra le cartelle dello stesso livello. minLength: 1 maxLength: 100
parent_id (opzionale, inline)	Sposta la cartella in questa; null per la radice del progetto.
default_playlist_id (opzionale, inline)	Una playlist approvata per gli schermi della cartella che non ne hanno una propria; null la cancella.
protected (opzionale, booleano)	Protegge la cartella e ogni cartella al suo interno (docs/screen-scope.md). Solo una persona che può approvare lo imposta. Invialo da solo: con qualsiasi altro membro la richiesta è invalid_request. Rimuoverlo da una cartella protetta è a sua volta una modifica protetta, una revisione decisa da un secondo approvatore (202 pending_review).

Modello richiesta e risposte

shell · modello richiesta

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/screen-folders/RESOURCE_ID'

Risposte

Stato	Significato	Corpo e intestazioni
200	Cartella aggiornata.	ScreenFolder (application/json); intestazioni: ETag
202	La scrittura è diventata una revisione e attende l’approvazione di una persona (docs/reviews.md), con accesso Proponi, oppure a qualsiasi livello di accesso quando raggiunge uno schermo in una cartella di schermi protetta, dove la decide un secondo approvatore (docs/screen-scope.md). Una persona approva, rifiuta o richiede modifiche nel dashboard a review.url. Una ripetizione con Idempotency-Key risponde con lo stesso corpo.	ReviewPending (application/json)
402	feature_not_in_plan — Le cartelle protette fanno parte del piano Enterprise; il problema indica la funzione, il piano dell’account e required_plan.	Problema (application/problem+json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

ELIMINA/api/screen-folders/{id}¶

Elimina cartella schermi

Elimina una cartella. Nulla al suo interno viene eliminato: i suoi schermi e le sue cartelle salgono nella cartella che conteneva quella eliminata (nella radice del progetto se non ne aveva una), ogni cartella spostata aggiorna la propria revisione e quegli schermi vengono risolti di nuovo.

Rifiutata con resource_conflict finché il pubblico di una campagna nomina la cartella, così nessuna programmazione perde i suoi schermi in silenzio: modifica o elimina prima quelle campagne. Risponde con i levels che i suoi schermi hanno ottenuto o perso. Emette screen.folder_deleted. If-Match protegge opzionalmente la revisione.

Un chiamante limitato agli schermi (docs/screen-scope.md) elimina solo una cartella dentro il suo ambito che il suo ambito non nomina direttamente (outside_screen_scope); gli schermi al suo interno salgono nella cartella genitore. Eliminare una cartella protetta, o una che contiene schermi protetti, è una revisione protected_change (202 pending_review) decisa da un secondo approvatore.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: deleteScreenFolder

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Eliminata; i suoi contenuti ora sono nella cartella superiore. levels nomina le playlist predefinite di cartella che i suoi schermi hanno ottenuto o perso.	ScreenFolderDeleteResult (application/json)
202	La scrittura è diventata una revisione e attende l’approvazione di una persona (docs/reviews.md), con accesso Proponi, oppure a qualsiasi livello di accesso quando raggiunge uno schermo in una cartella di schermi protetta, dove la decide un secondo approvatore (docs/screen-scope.md). Una persona approva, rifiuta o richiede modifiche nel dashboard a review.url. Una ripetizione con Idempotency-Key risponde con lo stesso corpo.	ReviewPending (application/json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/move¶

Sposta schermi

Sposta schermi (screen_ids) e cartelle (folder_ids) in una cartella (folder_id), o nella radice del progetto se folder_id è null, in una singola richiesta tutto o niente di massimo 1000 ID. Ogni ID deve esistere (not_found). Una cartella non può spostarsi in se stessa o in una cartella al suo interno, e lo spostamento deve mantenere ogni cartella entro 10 livelli (invalid_request).

Gli elementi già nella destinazione restano come sono; ogni schermo e cartella spostati avanza la propria revisione. Gli schermi spostati rivalutano la loro playlist entro circa 15 secondi: levels nomina le campagne di cui entrano o lasciano il pubblico di cartella e le playlist predefinite di cartella che ottengono o perdono.

Emette screen.moved, i cui dettagli riportano i conteggi (screens, folders) e dove si trovava ogni elemento spostato: moves [{screen_id, from}] (from è l’id della cartella, vuoto per la radice) e folder_moves [{folder_id, from_parent}], al massimo 1000 ciascuno, così una cronologia può riportarli indietro con questa route.

Un chiamante limitato agli schermi (docs/screen-scope.md) sposta schermi e cartelle dentro il suo ambito in una cartella del suo ambito; qualsiasi id o destinazione fuori dall’ambito, e la radice del progetto, fanno rifiutare l’intero spostamento (outside_screen_scope), anche quando uno schermo esce dall’ambito tra il controllo e la scrittura.

Uno spostamento dentro o fuori da una cartella protetta è una revisione protected_change (202 pending_review) decisa da un secondo approvatore.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ScreenMove
ID operazione: moveScreens

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
folder_id (obbligatorio, inline)	Cartella di destinazione; null per la radice del progetto.
screen_ids (opzionale, array)
folder_ids (opzionale, array)

Modello richiesta e risposte

shell · modello richiesta

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/screens/move'

Risposte

Stato	Significato	Corpo e intestazioni
200	Quanti schermi e cartelle sono stati spostati, e i levels che gli schermi spostati acquisiscono o perdono.	ScreenMoveResult (application/json)
202	La scrittura è diventata una revisione e attende l’approvazione di una persona (docs/reviews.md), con accesso Proponi, oppure a qualsiasi livello di accesso quando raggiunge uno schermo in una cartella di schermi protetta, dove la decide un secondo approvatore (docs/screen-scope.md). Una persona approva, rifiuta o richiede modifiche nel dashboard a review.url. Una ripetizione con Idempotency-Key risponde con lo stesso corpo.	ReviewPending (application/json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/schedule/calendar¶

Ottieni calendario programmazione

Risponde a cosa riproducono gli schermi di un soggetto in [from, to) e perché, per il calendario della Programmazione del dashboard: esattamente uno tra screen_id, folder_id (gli schermi nella cartella e in ogni cartella al suo interno), tag o campaign_id (gli schermi del suo pubblico).

Gli schermi i cui stack hanno input identici (stessi livelli, predefinito, fuso orario e numero di display) condividono un unico gruppo con un’unica timeline, quindi un soggetto grande costa decine di timeline; un gruppo elenca fino a 500 dei suoi schermi e una risposta al massimo 200 gruppi (truncated).

Ogni gruppo riporta il proprio stack, dal più alto (takeover, campagne che raggiungono gli schermi, le voci di programmazione proprie, poi la playlist predefinita o quella della cartella più vicina), gli spans di ogni livello (riproduce su ogni display di destinazione, parziale con i display su cui riproduce, superato, oppure condizionale finché attende un’interazione o una condizione sui dati che solo un Player osserva), ciò che ogni display mostra (on_screen; la regione principale di una pagina intera) e i conflitti (due campagne con la stessa priorità in vigore insieme; un livello che è in vigore ma non riproduce mai). from e to sono istanti RFC 3339, to successivo a from, distanti al massimo 93 giorni; vengono troncati al minuto.

Le regole vengono lette nel fuso orario di ciascun gruppo come le leggono la sweep e ogni Player; ogni livello è considerato riproducibile. Un chiamante limitato agli schermi (docs/screen-scope.md) deve inviare uno screen_id o un folder_id dentro il suo ambito; un tag, un campaign_id o nessun soggetto è outside_screen_scope.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getScheduleCalendar

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
da	query	obbligatorio
a	query	obbligatorio
screen_id	query	opzionale
folder_id	query	opzionale
tag	query	opzionale
campaign_id	query	opzionale

Modello richiesta e risposte

shell · modello richiesta

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/schedule/calendar?from=FROM&to=TO'

Risposte

Stato	Significato	Corpo e intestazioni
200	Il calendario del soggetto.	ScheduleCalendar (application/json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/pair¶

Associa schermo

Richiede una sessione di associazione Player globale a flotta di sei caratteri. I retry con Idempotency-Key esatti restituiscono il risultato originale duraturo senza consumare nuovamente la quota.

La sessione dashboard esegue il claim nel suo progetto corrente con lo stesso corpo, la stessa Idempotency-Key, gli stessi budget e gli stessi problemi, tranne che il suo not_found per un codice sconosciuto o già riscattato non nomina alcun comando CLI; è un cambio di stato, quindi segue le regole di mutazione del dashboard, una sessione shadow senza modalità di scrittura dello staff viene rifiutata, e gli eventi che il claim aggiunge nominano l’utente del dashboard. folder_id indica la cartella in cui finisce lo schermo.

Un chiamante limitato agli schermi (docs/screen-scope.md) deve inviare una cartella dentro il suo ambito e associa solo come persona che può approvare (outside_screen_scope, approver_required).

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: Schermo di associazione
ID operazione: pairScreen

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
Idempotency-Key	intestazione	obbligatorio

Campi del corpo della richiesta

Campo	Descrizione
codice (obbligatorio, stringa)	pattern: "^[23456789ABCDEFGHJKMNPQRSTUVWXYZ]{6}$"
label (opzionale, stringa)	minLength: 1 maxLength: 120
folder_id (opzionale, stringa)	La cartella di schermi in cui finisce lo schermo; se omessa, lo schermo finisce nella radice del progetto. Un chiamante limitato agli schermi deve inviare una cartella dentro il suo ambito (altrimenti outside_screen_scope). Una cartella che il progetto non contiene è invalid_request per un chiamante dell’intero progetto. Parte della richiesta idempotente: un altro folder_id con la stessa Idempotency-Key è idempotency_mismatch. minLength: 1

Campo

Descrizione

codice (obbligatorio, stringa)

pattern: "^[23456789ABCDEFGHJKMNPQRSTUVWXYZ]{6}$"

label (opzionale, stringa)

minLength: 1 maxLength: 120

folder_id (opzionale, stringa)

La cartella di schermi in cui finisce lo schermo; se omessa, lo schermo finisce nella radice del progetto. Un chiamante limitato agli schermi deve inviare una cartella dentro il suo ambito (altrimenti outside_screen_scope). Una cartella che il progetto non contiene è invalid_request per un chiamante dell’intero progetto.

Parte della richiesta idempotente: un altro folder_id con la stessa Idempotency-Key è idempotency_mismatch. minLength: 1

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
201	Richiesta durevole pairing_pending dello schermo.	PairingClaim (application/json); intestazioni: Cache-Control, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
413	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
500	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/provision¶

Provisiona schermo

Provisioning facoltativo di un nuovo schermo, solo da browser. Crea sempre un nuovo schermo pairing_pending; al massimo cinque attendono l’associazione contemporaneamente (quota_exceeded). I nuovi tentativi esatti ricevono di nuovo lo stesso token di frammento per dieci minuti. L’associazione a sei caratteri resta il flusso predefinito e l’unico flusso di recupero. folder_id indica la cartella in cui finisce lo schermo.

Un chiamante limitato agli schermi (docs/screen-scope.md) deve inviare una cartella dentro il suo ambito (altrimenti outside_screen_scope).

Autenticazione: projectBearer
Corpo della richiesta: ProvisionScreen
ID operazione: provisionScreen

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
Idempotency-Key	intestazione	obbligatorio

Campi del corpo della richiesta

Campo	Descrizione
label (opzionale, stringa)	minLength: 1 maxLength: 120
folder_id (opzionale, stringa)	La cartella di schermi in cui finisce lo schermo, come su PairScreen. minLength: 1

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/provision'

Risposte

Stato	Significato	Corpo e intestazioni
201	Nuovo link provisioning browser.	ScreenProvisioning (application/json); intestazioni: Cache-Control, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
410	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
413	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
500	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/actions¶

Applica azioni schermo

Applica un’azione a una flotta selezionata senza limite di schermi. Seleziona un screen_ids unico o un tag corrispondente agli schermi attivi in ordine di creazione. La selezione risolta è fissata prima di qualsiasi mutazione, archiviata in blocchi limitati e conservata per ventiquattro ore sotto Idempotency-Key.

Ogni passaggio usa il proprio percorso di modifica a schermo singolo, mantenendo revisioni, eventi, segnali runtime e limiti per schermo. Una risposta contiene una pagina limitata di risultati; matched, succeeded e failed descrivono quella pagina. HTTP 202 include total, offset e next_cursor. Continua con lo stesso selettore, azione e Idempotency-Key, passando next_cursor come after.

Rispetta Retry-After se presente, inclusa una pagina con zero risultati. La risposta ripete Idempotency-Key, inclusa una chiave generata se il chiamante l’ha omessa; conserva questa chiave per le continuazioni. HTTP 200 termina la selezione. Le pagine risposte si riproducono esattamente, inclusi i fallimenti per schermo; i passaggi interrotti si riproducono senza ripetere i loro effetti.

Le azioni grandi sono limitate dai budget organizzazione esistenti di 600 al minuto per ricarica, toast, takeover, programmazioni playlist, riavvio, monitor e programmazioni monitor; l’esaurimento del budget dell’organizzazione mette in pausa l’azione invece di rifiutare la flotta. L’esaurimento per schermo fallisce solo quello schermo.

Un passo assign, takeover o set_playlist_schedule che associa una playlist con un formato a uno schermo il cui muro ha un'altra forma fa fallire solo quello schermo con 409 playlist_format_mismatch. Le modifiche di assegnazione e tag non hanno budget di messaggi.

Un'assegnazione la cui playlist ha un src iframe o parametri dell'applicazione che leggono un token dello schermo che manca a qualche schermo della pagina aggiunge un'avvertenza screen_fact_missing a quella pagina (warnings, PlaylistWarning). Il fallimento parziale è un risultato normale. Tutte le pagine e i tentativi con una stessa chiave sono un'unica azione conteggiata.

Le richieste usano un payload byte limitato; usa un tag per una selezione più grande del payload di trasporto. Un selettore o azione malformati sono rifiutati prima di toccare qualsiasi schermo.

Un chiamante limitato agli schermi (docs/screen-scope.md) seleziona per screen_ids o per cartella, ogni schermo dentro il suo ambito; un selettore tag, uno schermo fuori dall’ambito o uno sconosciuto fa rifiutare l’intera azione (outside_screen_scope) prima che qualcosa venga fissato o proposto.

Assign, takeover, takeover_clear, set_playlist_schedule e clear_playlist_schedule che raggiungono uno schermo protetto diventano una revisione decisa da un secondo approvatore (202 pending_review) a ogni livello di accesso; set_tags, add_tags, remove_tags, toast, display, display_clear, set_display_schedule e clear_display_schedule su uno schermo protetto sono protected_target (409).

Un’azione set_playlist_schedule con una voce in pausa (una bozza) rientra nel controllo delle modifiche alla programmazione, che il piano Enterprise include; un progetto il cui piano ne è privo viene rifiutato con feature_not_in_plan (402).

Autenticazione: projectBearer
Corpo della richiesta: ScreenActionRequest
ID operazione: applyScreenActions

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
Screenrig-Review-Note	intestazione	opzionale	Nota opzionale del proponente su scrittura di classe review, inviata come UTF-8 percent-encoded (come scrive encodeURIComponent di JavaScript). Il server la percent-decodifica (un escape non valido è 400 invalid_request); la nota decodificata è testo semplice, massimo 280 caratteri dopo il trim, senza caratteri di controllo (altrimenti 400 invalid_request). Archiviato alla revisione quando la scrittura diventa una; ignorato se applicato in tempo reale.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.
dopo	query	opzionale	next_cursor dalla pagina di risultati precedente. Riutilizza l’Idempotency-Key originale e il corpo della richiesta.

Campi del corpo della richiesta

Campo	Descrizione
selettore (obbligatorio, ScreenActionSelector)
azione (obbligatoria, ScreenAction)	Una azione di flotta, discriminata per tipo. Ogni membro porta solo i propri parametri; un membro di altro tipo è un campo sconosciuto e invalid_request.

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/actions'

Risposte

Stato	Significato	Corpo e intestazioni
200	Risultati per schermo. Il successo parziale è una risposta normale.	ScreenActionResult (application/json); intestazioni: Idempotency-Key, Cache-Control, RateLimit-Policy, RateLimit
202	Restano altri schermi (continua con next_cursor e la stessa Idempotency-Key e lo stesso corpo, rispettando Retry-After), oppure, con stato pending_review, l’azione è diventata una revisione con accesso Proponi (docs/reviews.md), o a qualsiasi livello di accesso perché raggiunge uno schermo in una cartella di schermi protetta (docs/screen-scope.md). Solo assign, takeover, takeover_clear, set_playlist_schedule e clear_playlist_schedule diventano revisioni; ogni altra azione è insufficient_access per Propose.	inline (application/json); intestazioni: Idempotency-Key, Retry-After, Cache-Control, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
402	feature_not_in_plan — set_reboot_schedule con enabled true (riavvii programmati) e set_playlist_schedule con un blocco displays (video wall) fanno parte di Plus; le azioni di cancellazione e i comandi una tantum sono disponibili. payment_required — il progetto non ha più credito. Il problema indica la funzione, il piano del progetto e required_plan.	Problema (application/problem+json)
403	insufficient_access, outside_screen_scope quando un chiamante limitato agli schermi seleziona fuori dal suo ambito, oppure approver_required per un membro limitato agli schermi che non può approvare.	Problema (application/problem+json)
409	playlist_format_mismatch e gli altri conflitti dell’azione, oppure protected_target quando set_tags, add_tags, remove_tags, toast, display, display_clear, set_display_schedule o clear_display_schedule raggiunge uno schermo in una cartella di schermi protetta.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}¶

Ottieni schermo

Restituisce gli schermi pairing_pending, attivi e archiviati. Gli schermi eliminati non sono trovati.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getScreen

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Schermo	Schermo (application/json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PATCH/api/screens/{id}¶

Aggiorna schermo

Aggiorna name, playlist_id, timezone, wall, tags, fields, location, log_level, toast_level, display o kiosk dello schermo. Una modifica dei tag risponde levels: le campagne in cui lo schermo entra o da cui esce, con la portata di ciascuna campagna prima e dopo. wall imposta il video wall dello schermo (un oggetto) o lo cancella (null).

Impostarne uno richiede un Player che abbia dichiarato la host capability display.wall, altrimenti 409 wall_unsupported.

Modificarlo rigenera la revisione del manifest e aggiunge l'evento screen.updated con details.wall (l'oggetto wall, o null dopo la cancellazione). fields viene unito ai valori propri dello schermo (una stringa imposta un campo, null lo rimuove, un fields null cancella ogni campo) e location imposta dove si trova lo schermo (null la cancella).

Modificare l'uno o l'altro rigenera la revisione del manifest di uno schermo che mostra una playlist, quindi i posizionamenti delle sue card espandono di nuovo i token {screen.…}, e aggiunge l'evento screen.updated con details.fields (il nuovo oggetto completo, {} dopo la cancellazione) o details.location (il nuovo oggetto, o null dopo la cancellazione).

Un nome o un valore che la grammatica rifiuta, o un trentatreesimo campo, dà invalid_request che lo indica. log_level (debug, info, warn, error) e toast_level (info, alert, error) impostano il livello più basso che il Player genera o mostra, e null cancella ciascuno; qualsiasi altro valore dà invalid_request.

Cambiare l’uno o l’altro rigenera la revisione del manifest, che li porta come membro radice verbosity. display imposta o cancella le impostazioni di oscuramento per inattività e di luminosità del display: display.idle {after_s, wake} oscura il display dopo after_s secondi (da 30 a 86400) senza un tocco o un tasto oppure, quando wake elenca presence, senza nessuno davanti allo schermo, e un evento di riattivazione (touch, presence o entrambi, ciascuno una sola volta) lo riaccende subito; display.brightness {mode} è auto (il sensore di luce del dispositivo imposta la luminosità) o fixed (il valore predefinito, la luminosità dell’operatore).

Un membro che invii lo sostituisce, null lo cancella, un membro omesso resta com’è, e un display null cancella entrambi. kiosk {lock} true blocca il Player sullo schermo (blocco su schermo di Android) e false o null lo rilascia. La programmazione del display e l’override mantengono le proprie route; un membro display che nomina schedule o override dà invalid_request.

Un valore fuori intervallo o del tipo sbagliato dà invalid_request che nomina il percorso (display.idle.after_s).

Cambiare uno qualsiasi di essi rigenera la revisione del manifest di uno schermo che mostra una playlist e cambia l’ETag del manifest di ogni schermo; il manifest porta display.idle e display.brightness nel membro radice display e il blocco come membro radice kiosk, e viene aggiunto screen.manifest_changed; lo schermo li rilegge come Screen.display.idle, Screen.display.brightness e Screen.kiosk.

Il backend memorizza ciò che invii qualunque sia il Player: un Player applica un’impostazione solo quando le sue capacità dell’host dichiarano display_power.idle, brightness.auto o kiosk_lock, e i Player più vecchi le ignorano. Assegnare una playlist il cui formato non corrisponde al video wall dello schermo dà 409 playlist_format_mismatch.

Con accesso Propose, una patch di playlist_id da sola diventa una revisione (202 pending_review); qualsiasi altro campo, compresi wall, fields, location, display e kiosk, dà insufficient_access. Una playlist senza versione approvata è playlist_not_approved.

Quando la playlist che lo schermo mostra poi ha un src iframe o parametri dell’applicazione che leggono un token dello schermo che lo schermo non ha, la risposta include un’avvertenza screen_fact_missing (warnings, PlaylistWarning) e il manifest dello schermo omette quella primitiva.

Su uno schermo protetto, playlist_id è una revisione decisa da un secondo approvatore (202 pending_review) a qualsiasi livello di accesso e viene inviato da solo (invalid_request con name); tags, fields, location, timezone, wall e display restituiscono protected_target (409), anche insieme a playlist_id. La modifica del nome resta immediata. Svuotare playlist_id (null) su uno schermo archiviato restituisce 409 screen_archived.

Autenticazione: projectBearer
Corpo della richiesta: ScreenPatch
ID operazione: updateScreen

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
Screenrig-Review-Note	intestazione	opzionale	Nota opzionale del proponente su scrittura di classe review, inviata come UTF-8 percent-encoded (come scrive encodeURIComponent di JavaScript). Il server la percent-decodifica (un escape non valido è 400 invalid_request); la nota decodificata è testo semplice, massimo 280 caratteri dopo il trim, senza caratteri di controllo (altrimenti 400 invalid_request). Archiviato alla revisione quando la scrittura diventa una; ignorato se applicato in tempo reale.
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
nome (opzionale, stringa)	minLength: 1 maxLength: 120
playlist_id (facoltativo, inline)	Il predefinito dello schermo: un id di playlist lo assegna; null lo rimuove; l'omissione lo conserva. Takeover, campagne, programmazioni e predefiniti ereditati dalle cartelle mantengono la precedenza. Senza contenuto effettivo il Player abbinato mostra la schermata di attesa.
fuso orario (opzionale, stringa)	Identificatore fuso orario IANA, per esempio America/Los_Angeles. È la zona in cui viene valutata ogni regola di visibilità pagina su questo schermo. Cambiarla rigenera la revisione del manifesto. Uno schermo assegnato a una playlist che usa la visibilità pagina deve averla. minLength: 1 maxLength: 64
wall (opzionale, inline)	Il video wall dello schermo; null lo cancella. Impostarne uno richiede un lettore che dichiari la capacità host display.wall, altrimenti 409 wall_unsupported. Cambiarlo rinnova la revisione del manifesto.
tag (opzionale, ScreenTags)	Tag selettore flotta, da 0 a 16 tag unici esatti, ciascuno conforme alla grammatica dei tag media. Su ScreenPatch l’array sostituisce l’intero set e un array vuoto lo cancella; un tag duplicato o malformato è invalid_request. Cambiare i tag aggiorna la revisione dello schermo (protetta da If-Match) e aggiunge screen.updated con details.tags; non modifica mai la revisione del manifesto. I tag non sono mai nel manifesto di runtime e mai nell’autorizzazione.
fields (facoltativo, inline)	Viene unito ai valori propri dello schermo, come il numero di negozio o la regione: una stringa imposta un campo, null lo rimuove e un fields null cancella ogni campo. I nomi sono da 1 a 32 lettere minuscole, cifre o trattini bassi; i valori da 1 a 200 caratteri dopo la rimozione degli spazi iniziali e finali; uno schermo può avere al massimo 32 campi. Modificare i campi rigenera la revisione del manifest di uno schermo che mostra una playlist. I posizionamenti delle card li leggono tramite i token {screen.field.NAME}.
location (facoltativo, inline)	La posizione dello schermo; null la cancella. Modificarla rigenera la revisione del manifest di uno schermo che mostra una playlist. I posizionamenti delle card la leggono tramite il token {screen.location}.
log_level (opzionale, in linea)	Il livello di log più basso che il Player dello schermo genera: non scrive nessuna riga al di sotto, e le righe di errore vengono sempre generate; null lo cancella (il valore predefinito del Player). Cambiarlo rigenera la revisione del manifest, che lo porta come verbosity.logLevel.
toast_level (opzionale, in linea)	Il livello di toast più basso che il Player dello schermo mostra: sotto di esso non mostra alcun toast, e i toast di errore sono sempre mostrati; null lo cancella (ogni toast viene mostrato). Cambiarlo rigenera la revisione del manifest, che lo porta come verbosity.toastLevel.
display (opzionale, inline)	Le impostazioni di oscuramento per inattività e di luminosità del display (display.idle, display.brightness). Un membro che invii lo sostituisce, null lo cancella, un membro omesso resta com’è; un display null cancella entrambi. Cambiare l’uno o l’altro rigenera la revisione del manifest di uno schermo che mostra una playlist, e il manifest li porta nel membro radice display. Su uno schermo protetto dà protected_target.
kiosk (opzionale, inline)	Il blocco kiosk (kiosk.lock). lock true blocca il Player sullo schermo; false o null lo rilascia. Cambiarlo rigenera la revisione del manifest di uno schermo che mostra una playlist, e il manifest lo porta come membro radice kiosk.

Modello richiesta e risposte

shell · modello richiesta

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID'

Risposte

Stato	Significato	Corpo e intestazioni
202	La scrittura è diventata una revisione e attende l’approvazione di una persona (docs/reviews.md), con accesso Proponi, oppure a qualsiasi livello di accesso quando raggiunge uno schermo in una cartella di schermi protetta, dove la decide un secondo approvatore (docs/screen-scope.md). Una persona approva, rifiuta o richiede modifiche nel dashboard a review.url. Una ripetizione con Idempotency-Key risponde con lo stesso corpo.	ReviewPending (application/json)
200	Schermo	Schermo (application/json)
402	feature_not_in_plan — I video wall fanno parte di Plus: impostare un wall diverso da quello proprio dello schermo li richiede, null lo cancella in ogni piano. Il problema indica la funzione, il piano del progetto e required_plan.	Problema (application/problem+json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
409	protected_target - la modifica raggiunge uno schermo in una cartella di schermi protetta e non ha una forma di revisione (docs/screen-scope.md). Rimuovi la protezione della cartella tramite una revisione, fai la modifica e proteggi di nuovo la cartella.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

ELIMINA/api/screens/{id}¶

Elimina schermo

Elimina in soft uno schermo idoneo e revoca immediatamente le sue credenziali cookie e i permessi di runtime. Le letture ordinarie restituiscono not_found; la riga tombstone viene mantenuta per almeno 90 giorni prima della pulizia. If-Match protegge la revisione e Idempotency-Key riproduce il risultato.

Uno schermo con identità nativa restituisce screen_archive_required: usa archive per mantenere quel vincolo; uno schermo con identità nativa già archiviato resta archiviato (lo stesso problema, che lo dichiara). Questa rotta non concede il permesso amministrativo break-glass per rilasciare l’iscrizione nativa. Uno schermo in una cartella di schermi protetta è protected_target (409).

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: deleteScreen

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
204	Schermo eliminato soft; la sua lapide è conservata per almeno 90 giorni.	nessun corpo
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	screen_archive_required per uno schermo con identità nativa, oppure protected_target quando lo schermo è in una cartella di schermi protetta (docs/screen-scope.md).	Problema (application/problem+json)
412	revision_conflict — If-Match è obsoleto; current_revision dell’errore riporta la revisione corrente.	Problema (application/problem+json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PATCH/api/screens/{id}/tags¶

Patch tag schermo

Una persona connessa imposta i tag di uno schermo. tags è il nuovo set completo: un array vuoto lo cancella, e un tag malformato o ripetuto è invalid_request in tags[i].

È la modifica tag che updateScreen fa, nella sessione dashboard: la revisione schermo avanza di uno, screen.updated riporta details.tags e la persona come attore, e la revisione manifest non cambia mai. Uno schermo pairing_pending, attivo o archiviato lo accetta.

Il corpo non ha altri membri: una sessione rinomina uno schermo con patchScreenName e ne assegna la playlist con patchScreenPlaylist, e non può cambiarne il fuso orario. If-Match contiene la revisione dello schermo ed è obbligatorio (invalid_request se assente, revision_conflict se obsoleto).

Solo la sessione dashboard; gli agenti cambiano i tag con updateScreen o con un’azione di flotta set_tags, add_tags o remove_tags. listScreens con tag trova lo schermo per i suoi nuovi tag. Su uno schermo protetto la modifica è protected_target (409).

Autenticazione: dashboardSession
Corpo della richiesta: ScreenTagsPatch
ID operazione: patchScreenTags

Parametri

Nome	Invia	Obbligatorio?	Descrizione
id	path	obbligatorio
If-Match	intestazione	obbligatorio	La revisione corrente dello schermo, quotata o semplice (l’ETag dell’ultima lettura). Una revisione obsoleta è revision_conflict con current_revision.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
tag (obbligatorio, ScreenTags)	Tag selettore flotta, da 0 a 16 tag unici esatti, ciascuno conforme alla grammatica dei tag media. Su ScreenPatch l’array sostituisce l’intero set e un array vuoto lo cancella; un tag duplicato o malformato è invalid_request. Cambiare i tag aggiorna la revisione dello schermo (protetta da If-Match) e aggiunge screen.updated con details.tags; non modifica mai la revisione del manifesto. I tag non sono mai nel manifesto di runtime e mai nell’autorizzazione.

Campo

Descrizione

tag (obbligatorio, ScreenTags)

Tag selettore flotta, da 0 a 16 tag unici esatti, ciascuno conforme alla grammatica dei tag media. Su ScreenPatch l’array sostituisce l’intero set e un array vuoto lo cancella; un tag duplicato o malformato è invalid_request. Cambiare i tag aggiorna la revisione dello schermo (protetta da If-Match) e aggiunge screen.updated con details.tags; non modifica mai la revisione del manifesto.

I tag non sono mai nel manifesto di runtime e mai nell’autorizzazione.

Modello richiesta e risposte

shell · modello richiesta

curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/tags'

Risposte

Stato	Significato	Corpo e intestazioni
200	Lo schermo così come è memorizzato ora; ETag riporta la sua revisione.	Schermo (application/json); intestazioni: ETag
412	revision_conflict — If-Match è obsoleto; current_revision dell’errore riporta la revisione corrente.	Problema (application/problem+json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PATCH/api/screens/{id}/fields¶

Patch campi schermo

Una persona che ha effettuato l’accesso modifica i campi di uno schermo con il merge patch di updateScreen: una stringa imposta un campo, null lo rimuove e fields impostato a null cancella ogni campo. Un nome o un valore rifiutato, o un trentatreesimo campo, è invalid_request in fields o fields.NAME.

La revisione dello schermo avanza di uno, uno schermo che mostra una playlist riceve una nuova revisione del manifest, e l’evento riporta details.fields e la persona come attore. Il corpo non ha altri membri. If-Match contiene la revisione dello schermo ed è obbligatorio (invalid_request se assente, revision_conflict se obsoleta).

Solo la sessione dashboard; gli agenti usano PATCH /api/screens/{id} (updateScreen). Su uno schermo protetto la modifica è protected_target (409).

Autenticazione: dashboardSession
Corpo della richiesta: ScreenFieldsPatch
ID operazione: patchScreenFields

Parametri

Nome	Invia	Obbligatorio?	Descrizione
id	path	obbligatorio
If-Match	intestazione	obbligatorio	La revisione corrente dello schermo, quotata o semplice (l’ETag dell’ultima lettura). Una revisione obsoleta è revision_conflict con current_revision.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
fields (obbligatorio, inline)	Viene unito ai valori propri dello schermo, come il numero di negozio o la regione: una stringa imposta un campo, null lo rimuove e un fields null cancella ogni campo. I nomi sono da 1 a 32 lettere minuscole, cifre o trattini bassi; i valori da 1 a 200 caratteri dopo la rimozione degli spazi iniziali e finali; uno schermo può avere al massimo 32 campi.

Modello richiesta e risposte

shell · modello richiesta

curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/fields'

Risposte

Stato	Significato	Corpo e intestazioni
200	Lo schermo così come è memorizzato ora; ETag riporta la sua revisione.	Schermo (application/json); intestazioni: ETag
412	revision_conflict — If-Match è obsoleto; current_revision dell’errore riporta la revisione corrente.	Problema (application/problem+json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PATCH/api/screens/{id}/location¶

Patch posizione schermo

Una persona che ha effettuato l’accesso imposta o cancella la posizione di uno schermo con il membro location di updateScreen: un oggetto con latitude, longitude e, facoltativi, name e address sostituisce la posizione per intero, e null la cancella. Un membro mancante o di tipo errato, una coordinata fuori intervallo, un nome di oltre 40 caratteri o un indirizzo di oltre 200 è invalid_request in location.MEMBER.

La revisione dello schermo avanza di uno, uno schermo che mostra una playlist riceve una nuova revisione del manifest, e l’evento riporta details.location e la persona come attore. Il corpo non ha altri membri. If-Match contiene la revisione dello schermo ed è obbligatorio (invalid_request se assente, revision_conflict se obsoleta).

Solo la sessione dashboard; gli agenti usano PATCH /api/screens/{id} (updateScreen). Su uno schermo protetto la modifica è protected_target (409).

Autenticazione: dashboardSession
Corpo della richiesta: ScreenLocationPatch
ID operazione: patchScreenLocation

Parametri

Nome	Invia	Obbligatorio?	Descrizione
id	path	obbligatorio
If-Match	intestazione	obbligatorio	La revisione corrente dello schermo, quotata o semplice (l’ETag dell’ultima lettura). Una revisione obsoleta è revision_conflict con current_revision.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
location (obbligatorio, inline)	Dove si trova lo schermo: l’oggetto sostituisce l’intera posizione e null la cancella.

Modello richiesta e risposte

shell · modello richiesta

curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/location'

Risposte

Stato	Significato	Corpo e intestazioni
200	Lo schermo così come è memorizzato ora; ETag riporta la sua revisione.	Schermo (application/json); intestazioni: ETag
412	revision_conflict — If-Match è obsoleto; current_revision dell’errore riporta la revisione corrente.	Problema (application/problem+json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PATCH/api/screens/{id}/verbosity¶

Modificare la verbosità di uno schermo

Una persona connessa imposta o cancella il livello di log e il livello di toast di uno schermo con log_level (debug, info, warn, error) e toast_level (info, alert, error) di updateScreen: una stringa imposta il livello, null lo cancella, e un membro omesso resta com’è. Qualsiasi altro valore dà invalid_request su log_level o toast_level.

La revisione dello schermo avanza di uno, uno schermo che mostra una playlist riceve una nuova revisione del manifest, e il Player legge i livelli dal membro verbosity del manifest. Il corpo indica almeno uno dei due membri e nessun altro. If-Match porta la revisione dello schermo ed è obbligatorio (invalid_request se manca, revision_conflict se è obsoleto).

Solo la sessione della dashboard; gli agenti usano PATCH /api/screens/{id} (updateScreen).

Autenticazione: dashboardSession
Corpo della richiesta: ScreenVerbosityPatch
ID operazione: patchScreenVerbosity

Parametri

Nome	Invia	Obbligatorio?	Descrizione
id	path	obbligatorio
If-Match	intestazione	obbligatorio	La revisione corrente dello schermo, quotata o semplice (l’ETag dell’ultima lettura). Una revisione obsoleta è revision_conflict con current_revision.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
log_level (opzionale, in linea)	Il livello di log più basso che il Player dello schermo genera; le righe di errore vengono sempre generate. null lo cancella (il valore predefinito del Player). Cambiarlo rigenera la revisione del manifest.
toast_level (opzionale, in linea)	Il livello di toast più basso che il Player dello schermo mostra; i toast di errore sono sempre mostrati. null lo cancella (ogni toast viene mostrato). Cambiarlo rigenera la revisione del manifest.

Modello richiesta e risposte

shell · modello richiesta

curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/verbosity'

Risposte

Stato	Significato	Corpo e intestazioni
200	Lo schermo così come è memorizzato ora; ETag riporta la sua revisione.	Schermo (application/json); intestazioni: ETag
412	revision_conflict — If-Match è obsoleto; current_revision dell’errore riporta la revisione corrente.	Problema (application/problem+json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PATCH/api/screens/{id}/device-settings¶

Patch impostazioni dispositivo schermo

Una persona autenticata imposta o cancella le impostazioni di oscuramento per inattività e di luminosità di uno schermo e il suo blocco kiosk con i membri display e kiosk di updateScreen: display.idle {after_s da 30 a 86400, wake touch, presence o entrambi}, display.brightness {mode auto o fixed} e kiosk.lock.

Un membro che invii lo sostituisce, null lo cancella e un membro omesso resta com’è; un display null cancella entrambi. Un valore fuori intervallo o del tipo sbagliato dà invalid_request che nomina il percorso (display.idle.after_s).

La revisione dello schermo avanza di uno, uno schermo che mostra una playlist ottiene una nuova revisione del manifest, e il Player legge le impostazioni dai membri del manifest display (idle, brightness) e kiosk. Il corpo nomina almeno uno tra display e kiosk e nessun altro membro.

If-Match porta la revisione dello schermo ed è obbligatorio (invalid_request se assente, revision_conflict se obsoleta). Su uno schermo protetto una modifica del display dà protected_target (409). Solo per la sessione del dashboard; gli agenti usano PATCH /api/screens/{id} (updateScreen).

Autenticazione: dashboardSession
Corpo della richiesta: ScreenDeviceSettingsPatch
ID operazione: patchScreenDeviceSettings

Parametri

Nome	Invia	Obbligatorio?	Descrizione
id	path	obbligatorio
If-Match	intestazione	obbligatorio	La revisione corrente dello schermo, quotata o semplice (l’ETag dell’ultima lettura). Una revisione obsoleta è revision_conflict con current_revision.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
display (opzionale, inline)	display.idle e display.brightness, come il display di updateScreen: un membro che invii lo sostituisce, null lo cancella, un membro omesso resta com’è; un display null cancella entrambi. Cambiare l’uno o l’altro rigenera la revisione del manifest di uno schermo che mostra una playlist. Su uno schermo protetto dà protected_target.
kiosk (opzionale, inline)	kiosk.lock, come il kiosk di updateScreen: lock true blocca il Player sullo schermo, false o null lo rilascia.

Modello richiesta e risposte

shell · modello richiesta

curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/device-settings'

Risposte

Stato	Significato	Corpo e intestazioni
200	Lo schermo così come è memorizzato ora; ETag riporta la sua revisione.	Schermo (application/json); intestazioni: ETag
412	revision_conflict — If-Match è obsoleto; current_revision dell’errore riporta la revisione corrente.	Problema (application/problem+json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PATCH/api/screens/{id}/name¶

Modifica nome schermo

Una persona autenticata rinomina uno schermo con il name di updateScreen. Il nome viene ripulito e deve avere da 1 a 120 caratteri senza caratteri di controllo, altrimenti invalid_request su name (così anche per un nome mancante o null).

La revisione dello schermo avanza di uno e l’evento è screen.manifest_changed, indirizzato allo schermo, con la persona come attore; la revisione del manifest resta, quindi la riproduzione non è toccata e i Player aggiornano il nome dall’ETag modificato. Una ridenominazione allo stesso nome fa comunque avanzare la revisione e aggiunge screen.updated. Il corpo non ha altri membri.

If-Match contiene la revisione dello schermo ed è obbligatorio (invalid_request se assente, revision_conflict se obsoleto). Solo la sessione dashboard; gli agenti usano PATCH /api/screens/{id} (updateScreen).

Autenticazione: dashboardSession
Corpo della richiesta: ScreenNamePatch
ID operazione: patchScreenName

Parametri

Nome	Invia	Obbligatorio?	Descrizione
id	path	obbligatorio
If-Match	intestazione	obbligatorio	La revisione corrente dello schermo, quotata o semplice (l’ETag dell’ultima lettura). Una revisione obsoleta è revision_conflict con current_revision.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
nome (obbligatorio, stringa)	Il nome dello schermo, ripulito; da 1 a 120 caratteri dopo la pulizia, senza caratteri di controllo. minLength: 1 maxLength: 120

Modello richiesta e risposte

shell · modello richiesta

curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/name'

Risposte

Stato	Significato	Corpo e intestazioni
200	Lo schermo così come è memorizzato ora; ETag riporta la sua revisione.	Schermo (application/json); intestazioni: ETag
412	revision_conflict — If-Match è obsoleto; current_revision dell’errore riporta la revisione corrente.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PATCH/api/screens/{id}/playlist¶

Modificare la playlist dello schermo

Una persona autenticata assegna la playlist dello schermo con l’assegnazione di updateScreen: la playlist deve appartenere al progetto e avere una versione approvata (playlist_not_approved), e una playlist con formato richiede uno schermo il cui muro abbia la stessa forma (409 playlist_format_mismatch).

The screen revision moves by one and the manifest is reissued from the new playlist; while a takeover, a campaign or a schedule entry is effective the playlist becomes the default behind it. Events carry the person as their actor.

The write is live, so only the project owner or a member who can approve makes it (approver_required); a staff session needs its write lease. The body has no other member. If-Match carries the screen revision and is required (invalid_request when absent, revision_conflict when stale).

Solo la sessione dashboard; gli agenti usano PATCH /api/screens/{id} (updateScreen). Su uno schermo protetto l’assegnazione di un approvatore è una revisione decisa da un secondo approvatore (202 pending_review).

Autenticazione: dashboardSession
Corpo della richiesta: ScreenPlaylistPatch
ID operazione: patchScreenPlaylist

Parametri

Nome	Invia	Obbligatorio?	Descrizione
id	path	obbligatorio
If-Match	intestazione	obbligatorio	La revisione corrente dello schermo, quotata o semplice (l’ETag dell’ultima lettura). Una revisione obsoleta è revision_conflict con current_revision.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
playlist_id (obbligatorio, inline)	La playlist predefinita dello schermo; null rimuove la sua assegnazione. Un takeover, una campagna, una voce di programmazione o un predefinito ereditato da una cartella può ancora mostrare contenuto; altrimenti il Player abbinato mostra la schermata di attesa.

Modello richiesta e risposte

shell · modello richiesta

curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/playlist'

Risposte

Stato	Significato	Corpo e intestazioni
200	Lo schermo così come è memorizzato ora; ETag riporta la sua revisione.	Schermo (application/json); intestazioni: ETag
412	revision_conflict — If-Match è obsoleto; current_revision dell’errore riporta la revisione corrente.	Problema (application/problem+json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
202	La scrittura è diventata una revisione e attende l’approvazione di una persona (docs/reviews.md), con accesso Proponi, oppure a qualsiasi livello di accesso quando raggiunge uno schermo in una cartella di schermi protetta, dove la decide un secondo approvatore (docs/screen-scope.md). Una persona approva, rifiuta o richiede modifiche nel dashboard a review.url. Una ripetizione con Idempotency-Key risponde con lo stesso corpo.	ReviewPending (application/json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/public-id/rotate¶

Ruota Screen Public Id

Autenticazione: projectBearer
Corpo della richiesta: nessuno
ID operazione: rotateScreenPublicId

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/public-id/rotate'

Risposte

Stato	Significato	Corpo e intestazioni
200	La credenziale URL pubblica è stata ruotata; l'iscrizione della chiave pubblica del lettore è preservata. Ogni sessione runtime viene invalidata dalla nuova content_access_generation e le concessioni live desiderate e attive vengono riemesse a quella generazione per la loro revisione del manifesto invariata, quindi un lettore associato che rinnova la sua sessione continua ad autorizzare il contenuto che sta già mostrando.	Schermo (application/json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}/link¶

Ottieni link dello schermo

Il link dello schermo, l’URL Player che apre questo schermo in un browser che non conserva dati, come una sorgente browser di vMix o OBS. L’url è una credenziale: sotto Manage effettivo è vuoto e url_redacted è true. Richiede la capacità screens stessa. screen_link_not_found quando lo schermo non ne ha.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getScreenLink

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Il link dello schermo.	ScreenLink (application/json); intestazioni: Cache-Control
404	not_found per uno schermo fuori dal progetto; screen_link_not_found per uno schermo senza link.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/link¶

Crea link dello schermo

Emette il link dello schermo e restituisce il suo url, sostituendo qualsiasi link lo schermo abbia (replaced indica quale caso). Lo schermo deve essere attivo e associato una volta con il suo codice (resource_conflict finché non ha un Player associato, screen_archived se archiviato).

Una sostituzione incrementa il content_access_generation dello schermo e riemette le sue concessioni attive, come la rotazione di un ID pubblico, così ogni sessione aperta dal vecchio link termina subito; i Player dello schermo legati a una chiave emettono da soli una nuova sessione. Il primo link non incrementa nulla. Un link non è un legame di dispositivo: le chiavi dello schermo restano intatte.

Aggiunge screen.link_changed (details.action created o replaced). If-Match è facoltativo. L’url è una credenziale: aprila in un solo posto.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: createScreenLink

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Il nuovo link dello schermo.	ScreenLink (application/json); intestazioni: ETag, Cache-Control
409	resource_conflict (nessun Player associato ancora) o screen_archived.	Problema (application/problem+json)
412	revision_conflict — If-Match è obsoleto; current_revision dell’errore riporta la revisione corrente.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

ELIMINA/api/screens/{id}/link¶

Elimina link dello schermo

Disattiva il link dello schermo. Il vecchio url smette subito di funzionare e ogni sessione che ha aperto termina, come in una sostituzione. Riesce, senza cambiare nulla, quando lo schermo non ha un link. Aggiunge screen.link_changed (details.action deleted) quando esisteva un link. If-Match è facoltativo.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: deleteScreenLink

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
204	Eliminato, o non ce n’era nessuno.	nessun corpo
412	revision_conflict.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/recovery/confirm¶

Conferma recupero schermo

Conferma un recupero schermo in sospeso. Un avvio di associazione nativa che ha presentato un duid host o seriale corrispondente esattamente a uno schermo in un solo progetto, sotto una chiave pubblica vincolata diversa, registra un’offerta su quello schermo (Screen.recovery_pending, evento progetto screen.recovery_offered).

L’host è un suggerimento, mai una credenziale: nulla viene ricollegato finché il progetto proprietario non chiama questa rotta. Un DUID è leggibile da qualsiasi app sul pannello, quindi un’offerta è una superficie di phishing.

È mitigato dalla vitalità (nessuna offerta mentre la chiave associata ha mostrato attività negli ultimi dieci minuti), un limite di tre offerte per schermo per ora mobile, e questa stessa conferma di progetto; recovery_pending.host e l’evento riportano piattaforma, modello, firmware e produttore del dispositivo offerente così che l’operatore possa confrontarli con il display davanti a sé prima di confermare.

La conferma completa l’associazione nativa in corso sullo schermo ESISTENTE: il dispositivo di associazione riceve pairing.claimed come di consueto e prova il possesso con pairing.complete, la nuova chiave diventa l’identità dello schermo e la chiave precedente va in pensione con una finestra di grazia di quindici minuti in cui le sessioni runtime restano attive e può ancora emettere, dopo di che è rifiutata.

Playlist, etichetta, fuso orario, programmazioni e cronologia sono preservati. Solo per lo stesso progetto; lo schermo di un altro progetto è not_found. If-Match è opzionale. Emette screen.recovered. recovery_not_offered quando non c’è nulla in sospeso, recovery_expired quando la sessione di associazione è scaduta, recovery_ambiguous quando l’identificatore è associato in più di un luogo.

Le risposte problema non riportano mai identificatori dispositivo.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: confirmScreenRecovery

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per creare o sovrascrivere una chiave; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/recovery/confirm'

Risposte

Stato	Significato	Corpo e intestazioni
200	Schermo recuperato sulla chiave del dispositivo di associazione; la risposta riporta l’ETag corrente.	Schermo (application/json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
410	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/replace¶

Sostituisci schermo

Sposta su questo schermo il dispositivo associato come altro schermo del progetto e archivia quello schermo, così questo schermo mantiene nome, tag, fuso orario, playlist, programmazioni, takeover, programmazione display e override, video wall, commenti e cronologia su un nuovo hardware.

La chiave pubblica del dispositivo (o la credenziale del browser) ora apre questo schermo, che assume l’host e il Player del sostituto; salute, stato, spazio di archiviazione, osservazione e comandi in coda ricominciano da zero. La chiave che questo schermo possedeva viene ritirata con la finestra di grazia del recupero: può ancora eseguire il mint per quindici minuti, poi viene rifiutata (key_retired). Nulla viene dissociato.

Lo schermo sostituito viene archiviato con archive_reason replaced e non mantiene alcun vincolo né host. Entrambi gli schermi fanno avanzare content_access_generation, quindi ogni sessione che uno dei due aveva termina; il dispositivo riceve un player.reload indirizzato allo schermo che ha lasciato (details.reason replaced, valido per 24 ore) ed esegue di nuovo il mint come questo schermo.

Entrambi gli schermi devono essere attivi e avere un Player associato (uno schermo pairing_pending o un sostituto non associato è resource_conflict, uno archiviato è screen_archived); with deve indicare un altro schermo del progetto (invalid_request; lo schermo di un altro progetto è not_found); uno schermo con un video wall richiede un Player sostitutivo che abbia dichiarato display.wall (wall_unsupported).

If-Match è opzionale e verifica la revisione di questo schermo. Emette l’evento di progetto screen.replaced (details.from_screen_id) e nessun screen.archived. Un retry esatto con la stessa Idempotency-Key restituisce questa stessa risposta per ventiquattro ore.

Un chiamante limitato agli schermi (docs/screen-scope.md) richiede che lo schermo e with siano dentro il suo ambito (outside_screen_scope; non viene archiviato nulla). Una sostituzione in cui uno dei due schermi è protetto è protected_target.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ScreenReplaceWrite
ID operazione: replaceScreen

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per creare o sovrascrivere una chiave; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
with (obbligatorio, stringa)	L’id dello schermo, nello stesso progetto, il cui dispositivo associato subentra allo schermo nel percorso. Deve essere un altro schermo attivo con un Player associato; viene archiviato con archive_reason replaced. minLength: 1 maxLength: 256

Modello richiesta e risposte

shell · modello richiesta

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/screens/RESOURCE_ID/replace'

Risposte

Stato	Significato	Corpo e intestazioni
200	Il dispositivo ora apre questo schermo; la risposta è questo schermo con la sua nuova revisione e l’ETag corrente.	Schermo (application/json)
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	resource_conflict, screen_archived, wall_unsupported, oppure protected_target quando uno dei due schermi è in una cartella di schermi protetta.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/archive¶

Archivia schermo

Nasconde lo schermo dall’elenco predefinito e mostra sullo schermo fisico lo stato «Schermo archiviato». Non scollega la chiave pubblica del lettore. Libera quota screen_count. Annulla i comandi in coda reboot, clear_cache, restart_app e update dello schermo; un reload in coda viene comunque consegnato. Uno schermo in una cartella di schermi protetta restituisce protected_target (409).

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: archiveScreen

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Schermo archiviato.	Schermo (application/json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	protected_target quando lo schermo è in una cartella di schermi protetta (docs/screen-scope.md; rimuovi la protezione della cartella tramite una revisione, fai la modifica, proteggila di nuovo), oppure gli altri conflitti dell’operazione.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/unarchive¶

Ripristina schermo

Ripristina uno schermo archiviato nella lista predefinita e rigenera un manifest normale. Deve superare l’ammissione dello schermo. Non cambia la chiave pubblica associata.

Il manifesto viene emesso di nuovo, quindi la playlist dello schermo viene controllata come un’assegnazione; una playlist che fa riferimento a contenuti mancanti o non pronti risponde con resource_conflict nominando la playlist, e lo schermo resta archiviato finché la playlist non è corretta.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: unarchiveScreen

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Schermo ripristinato dall’archivio.	Schermo (application/json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
413	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/reload¶

Ricarica schermo

Chiede al Player dello schermo indicato, attivo o archiviato, di ricaricarsi (docs/player-compatibility.md §6.3). Il corpo opzionale imposta expires_in_s, per quanto tempo la ricarica resta eseguibile (da 60 a 86400 secondi, predefinito 86400, 24 ore); un valore fuori intervallo è invalid_request che nomina expires_in_s.

A uno schermo online viene inviato subito l’evento durevole per schermo player.reload (details.reason project, un nuovo reload_id, spread_s 0, expires_at) e la ricarica viene registrata in Screen.commands come sent.

Uno schermo offline tiene la ricarica in stato queued senza alcun evento; quando il backend applica la successiva transizione online dello schermo prima di expires_at, l’evento viene aggiunto, con lo stesso reload_id e lo stesso expires_at, e il comando diventa sent. Una ricarica più recente sostituisce una più vecchia ancora in coda.

Una ricarica in coda oltre expires_at risulta expired, e POST /api/screens/{id}/commands/{command_id}/cancel ne annulla una ancora in coda. Lo stream SSE del runtime trasmette l’evento a ogni sessione runtime. Un Player ignora una ricarica che arriva entro dieci minuti dall’ultima che ha eseguito.

Un Player web si ricarica al prossimo cambio pagina; un Player nativo esegue di nuovo il mint, recupera di nuovo il manifesto e verifica la presenza di aggiornamenti. La revisione dello schermo non cambia. If-Match e Idempotency-Key sono opzionali, come su archive; un retry esatto con Idempotency-Key restituisce il corpo originale per ventiquattro ore.

Uno schermo pairing_pending non ha ancora un Player e risponde resource_conflict. I messaggi dello schermo sono esenti dal contatore API da 1 credito.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ScreenCommandWrite
ID operazione: reloadScreen

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
expires_in_s (opzionale, intero)	Per quanto tempo il comando resta eseguibile, in secondi dalla richiesta. Un comando in coda viene inviato solo prima della scadenza; un Player ne ignora uno dopo expires_at. predefinito: 86400 minimo: 60 massimo: 86400

Modello richiesta e risposte

shell · modello richiesta

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/screens/RESOURCE_ID/reload'

Risposte

Stato	Significato	Corpo e intestazioni
202	Accettato. state è sent quando la ricarica è andata al Player dello schermo online, queued quando attende che lo schermo torni online. La ricarica è eseguibile fino a expires_at. L’ETag è la revisione dello schermo invariata.	ScreenReloadAccepted (application/json); intestazioni: Cache-Control, ETag, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}/playlist-schedule¶

Ottieni programmazione playlist schermo

Restituisce la programmazione della playlist valutata dal server dello schermo: voci in ordine di priorità (vuoto se lo schermo non ne ha), updated_at e la effective_playlist che producono attualmente. L’ETag è la revisione dello schermo. Gli schermi pairing_pending, attivi e archiviati sono leggibili; uno schermo di un altro progetto è not_found.

Autenticazione: projectBearer
Corpo della richiesta: nessuno
ID operazione: getScreenPlaylistSchedule

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/playlist-schedule'

Risposte

Stato	Significato	Corpo e intestazioni
200	Programmazione playlist.	ScreenPlaylistScheduleView (application/json); intestazioni: ETag
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PUT/api/screens/{id}/playlist-schedule¶

Imposta la programmazione della playlist dello schermo

Sostituisce la programmazione playlist dello schermo. Il server la valuta, mai il Player: la prima voce la cui regola corrisponde all’ora civile dello schermo (finestre screenrig.schedule/v1 e da/fino, nel fuso orario dello schermo, incluse transizioni ora legale e finestre che attraversano la mezzanotte) è la playlist effettiva; quando nessuna corrisponde, lo è playlist_id assegnato.

Un takeover vince sempre su ogni voce. Lo schermo deve avere un fuso orario e una playlist_id predefinita assegnata (invalid_request altrimenti), così c’è sempre qualcosa a cui tornare.

Ogni playlist referenziata è validata contro lo schermo esattamente come un’assegnazione (proprietaria, riferimenti pronti, la visibilità pagina richiede un fuso orario, e una playlist con formato richiede uno schermo la cui parete ha la stessa forma, altrimenti 409 playlist_format_mismatch), quindi una playlist che lo schermo rifiuterebbe è rifiutata qui; il controllo scrive il documento playlist, quindi una cancellazione concorrente della playlist confligge invece di competere.

Se una playlist programmata non può più essere mostrata (per esempio il suo contenuto non si risolve più), le sue voci sono saltate durante la valutazione e screen.playlist_unavailable (avviso, dettagli playlist_id, entry_ids, codice) è aggiunto.

Quando la playlist effettiva cambia, il manifesto viene rigenerato da essa e il lettore riceve il segnale screen.manifest_changed, come per un’assegnazione, e viene aggiunto screen.playlist_switched. La revisione dello schermo viene incrementata (If-Match la protegge) e viene aggiunto screen.updated con details.playlist_schedule_entries.

Uno schermo archiviato risponde screen_archived; il suo schedule, takeover e default restano referenziati (bloccano l’eliminazione playlist) e sono risolti di nuovo quando viene ripristinato. Limiti rate: screen-control-org 600, screen-control-screen 20 e screen-control-ip 60 al minuto, condivisi con DELETE e le rotte takeover.

Su uno schermo protetto la programmazione è una revisione decisa da un secondo approvatore (202 pending_review) a ogni livello di accesso. Una nuova voce con paused true (una bozza) rientra nel controllo delle modifiche alla programmazione, che il piano Enterprise include; un progetto il cui piano ne è privo viene rifiutato con feature_not_in_plan (402).

Le voci già memorizzate possono restare in pausa, e mettere in pausa una voce memorizzata è disponibile in ogni piano.

Autenticazione: projectBearer
Corpo della richiesta: ScreenPlaylistScheduleWrite
ID operazione: setScreenPlaylistSchedule

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
Screenrig-Review-Note	intestazione	opzionale	Nota opzionale del proponente su scrittura di classe review, inviata come UTF-8 percent-encoded (come scrive encodeURIComponent di JavaScript). Il server la percent-decodifica (un escape non valido è 400 invalid_request); la nota decodificata è testo semplice, massimo 280 caratteri dopo il trim, senza caratteri di controllo (altrimenti 400 invalid_request). Archiviato alla revisione quando la scrittura diventa una; ignorato se applicato in tempo reale.
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
voci (obbligatorio, array)	Ordine di priorità: vince la prima voce corrispondente. DELETE cancella la programmazione.

Modello richiesta e risposte

shell · modello richiesta

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/playlist-schedule'

Risposte

Stato	Significato	Corpo e intestazioni
202	La scrittura è diventata una revisione sotto Proponi accesso e attende l’approvazione di una persona (docs/reviews.md). Una ripetizione con Idempotency-Key risponde con lo stesso corpo.	ReviewPending (application/json); headers: RateLimit-Policy, RateLimit
200	Schermo con la programmazione memorizzata e la sua effective_playlist. L’ETag è la nuova revisione.	Schermo (application/json); intestazioni: ETag, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
402	feature_not_in_plan — Il controllo delle modifiche alla programmazione fa parte del piano Enterprise; il problema indica la funzione, il piano dell’account e required_plan. Una voce che blocca una playlist sul display 2 o oltre di un video wall (displays), diversa dalla voce memorizzata dello schermo, fa parte di Plus. Il problema indica la funzione, il piano del progetto e required_plan.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

ELIMINA/api/screens/{id}/playlist-schedule¶

Cancella programmazione playlist schermo

Rimuove la programmazione delle playlist dello schermo; ha effetto il takeover, altrimenti una campagna in vigore, altrimenti la playlist assegnata, con la stessa segnalazione del manifest di PUT. Uno schermo senza programmazione risponde 200 senza modifiche (nessun incremento della revisione, nessun evento).

Su uno schermo protetto rimuovere la programmazione è una revisione decisa da un secondo approvatore (202 pending_review) a ogni livello di accesso.

Autenticazione: projectBearer
Corpo della richiesta: nessuno
ID operazione: clearScreenPlaylistSchedule

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
Screenrig-Review-Note	intestazione	opzionale	Nota opzionale del proponente su scrittura di classe review, inviata come UTF-8 percent-encoded (come scrive encodeURIComponent di JavaScript). Il server la percent-decodifica (un escape non valido è 400 invalid_request); la nota decodificata è testo semplice, massimo 280 caratteri dopo il trim, senza caratteri di controllo (altrimenti 400 invalid_request). Archiviato alla revisione quando la scrittura diventa una; ignorato se applicato in tempo reale.
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/playlist-schedule'

Risposte

Stato	Significato	Corpo e intestazioni
202	La scrittura è diventata una revisione sotto Proponi accesso e attende l’approvazione di una persona (docs/reviews.md). Una ripetizione con Idempotency-Key risponde con lo stesso corpo.	ReviewPending (application/json); headers: RateLimit-Policy, RateLimit
200	Schermo senza programmazione di playlist.	Schermo (application/json); intestazioni: ETag, RateLimit-Policy, RateLimit
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/playlist-schedule/preview¶

Anteprima programmazione playlist schermo

Che cosa cambierebbe sostituire la programmazione playlist dello schermo con entries, senza eseguirlo.

Le voci vengono verificate come le verifica il PUT (grammatica, fuso orario e display dello schermo, una playlist predefinita e ogni playlist come assegnazione: esiste, ha una versione approvata, si adatta al wall dello schermo e alla regione che copre, e i suoi riferimenti si risolvono), quindi un’anteprima rifiuta ciò che rifiuta il PUT.

La risposta dice se lo schermo otterrebbe o perderebbe livelli della sua programmazione nel suo stack (una voce in pausa non è su nessuno stack, quindi pubblicarne una la fa ottenere), e il calendario di programmazione dello schermo così com’è (before) e come sarebbe (after) da from a to (predefinito: una settimana da adesso; al massimo 93 giorni). Accesso in lettura: non viene scritto nulla.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ScreenSchedulePreviewRequest
ID operazione: previewScreenPlaylistSchedule

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Campi del corpo della richiesta

Campo	Descrizione
voci (obbligatorio, array)
from (opzionale, string)	Inizio dei calendari; predefinito: adesso. format: "date-time"
to (opzionale, stringa)	Fine dei calendari; predefinito: una settimana dopo from, al massimo 93 giorni dopo di esso. format: "date-time"

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	L’anteprima.	SchedulePreview (application/json)
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}/playlist-schedule/revisions¶

Elenca revisioni programmazione playlist schermo

Le revisioni della programmazione playlist dello schermo, dalla più recente: l’intero elenco entries come memorizzato dopo ogni scrittura (un PUT, un DELETE, un ripristino, un’importazione di programmazione), con il tipo di modifica e chi l’ha fatta. Una revisione è numerata dalla revisione dello schermo al momento della scrittura, quindi i numeri hanno dei vuoti dove lo schermo è cambiato in altro modo.

Uno schermo la cui cronologia non ha ancora alcuna riga elenca la sua programmazione così com’è, con change baseline. Le revisioni vanno via con l’eliminazione definitiva dello schermo. Al massimo 50 per pagina; next_cursor finché ne restano altre, null nell’ultima pagina.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: listScreenPlaylistScheduleRevisions

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
dopo	query	opzionale	next_cursor della pagina precedente della stessa lista, con gli stessi filtri. Omettere inizia dalla riga più recente. Un valore che non è tale cursore è invalid_request.

Modello richiesta e risposte

shell · modello richiesta

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/screens/RESOURCE_ID/playlist-schedule/revisions'

Risposte

Stato	Significato	Corpo e intestazioni
200	Le revisioni della programmazione dello schermo, dalla più recente.	ScreenScheduleRevisionList (application/json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/playlist-schedule/revisions/{revision}/restore¶

Ripristina revisione programmazione playlist schermo

Rimette le voci di una revisione precedente come programmazione dello schermo: la stessa scrittura di PUT /api/screens/{id}/playlist-schedule con quelle voci (o DELETE quando quella revisione non ne aveva), verificate come lo sono ora (una playlist eliminata nel frattempo la rifiuta), così con accesso Proposta il ripristino diventa la stessa revisione screen_change in cui si trasforma il PUT.

If-Match è obbligatorio e indica la revisione corrente dello schermo. Le revisioni precedenti restano com’erano.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: restoreScreenPlaylistScheduleRevision

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
revisione	path	obbligatorio	Una revisione del record, come la numera il suo elenco di revisioni.
Screenrig-Review-Note	intestazione	opzionale	Nota opzionale del proponente su scrittura di classe review, inviata come UTF-8 percent-encoded (come scrive encodeURIComponent di JavaScript). Il server la percent-decodifica (un escape non valido è 400 invalid_request); la nota decodificata è testo semplice, massimo 280 caratteri dopo il trim, senza caratteri di controllo (altrimenti 400 invalid_request). Archiviato alla revisione quando la scrittura diventa una; ignorato se applicato in tempo reale.
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/screens/RESOURCE_ID/playlist-schedule/revisions/REVISION/restore'

Risposte

Stato	Significato	Corpo e intestazioni
202	La scrittura è diventata una revisione sotto Proponi accesso e attende l’approvazione di una persona (docs/reviews.md). Una ripetizione con Idempotency-Key risponde con lo stesso corpo.	ReviewPending (application/json); headers: RateLimit-Policy, RateLimit
200	Schermo con la programmazione ripristinata e la sua effective_playlist. L’ETag è la nuova revisione.	Schermo (application/json); intestazioni: ETag, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/takeover¶

Imposta il takeover dello schermo

Prende il controllo dello schermo con una playlist che ha la precedenza su campagne, programmazione delle playlist e playlist assegnata, fino a until (RFC 3339, strettamente nel futuro e al massimo 7 giorni da adesso) oppure, quando until è null o omesso, finché il takeover non viene rimosso. reason è facoltativo, al massimo 120 caratteri.

Lo schermo deve avere un playlist_id predefinito assegnato (altrimenti invalid_request). Un takeover ne sostituisce uno precedente (screen.takeover_ended con reason replaced, oppure expired se quello precedente era già terminato).

La playlist viene convalidata come un'assegnazione, compreso il suo formato (una playlist con un formato richiede uno schermo il cui wall ha la stessa forma, altrimenti 409 playlist_format_mismatch). Un takeover la cui playlist in seguito non può più essere mostrata termina (screen.takeover_ended con reason playlist_deleted o playlist_unavailable).

Aggiunge l'evento screen.takeover_started e, quando cambia la playlist effettiva, screen.playlist_switched più l'evento screen.manifest_changed del Player. Quando until è trascorso, il worker dei confini temporali termina il takeover entro 60 secondi (screen.takeover_ended con reason expired). La revisione dello schermo viene incrementata (If-Match la protegge).

Uno schermo archiviato risponde con screen_archived; il ripristino dall’archivio rivaluta prima, quindi un takeover terminato mentre lo schermo era archiviato termina in quel momento. Si applicano gli stessi limiti di frequenza del controllo schermi delle route di programmazione. Su uno schermo protetto un takeover è una revisione decisa da un secondo approvatore (202 pending_review) a ogni livello di accesso.

Autenticazione: projectBearer
Corpo della richiesta: ScreenTakeoverWrite
ID operazione: setScreenTakeover

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
Screenrig-Review-Note	intestazione	opzionale	Nota opzionale del proponente su scrittura di classe review, inviata come UTF-8 percent-encoded (come scrive encodeURIComponent di JavaScript). Il server la percent-decodifica (un escape non valido è 400 invalid_request); la nota decodificata è testo semplice, massimo 280 caratteri dopo il trim, senza caratteri di controllo (altrimenti 400 invalid_request). Archiviato alla revisione quando la scrittura diventa una; ignorato se applicato in tempo reale.
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
playlist_id (obbligatorio, stringa)	minLength: 1
fino a (opzionale, inline)	Solo futuro e massimo 7 giorni avanti. null o omissione mantiene il takeover finché non viene cancellato.
motivo (opzionale, stringa)	Nota dell’operatore trasportata durante il takeover e i suoi eventi. Nessun carattere di controllo. maxLength: 120

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/takeover'

Risposte

Stato	Significato	Corpo e intestazioni
202	La scrittura è diventata una revisione sotto Proponi accesso e attende l’approvazione di una persona (docs/reviews.md). Una ripetizione con Idempotency-Key risponde con lo stesso corpo.	ReviewPending (application/json); headers: RateLimit-Policy, RateLimit
200	Schermo con il takeover e la sua effective_playlist. L’ETag è la nuova revisione.	Schermo (application/json); intestazioni: ETag, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

ELIMINA/api/screens/{id}/takeover¶

Cancella takeover schermo

Termina il takeover (screen.takeover_ended con motivo cleared); la programmazione o la playlist assegnata diventano effettive con la stessa segnalazione del manifesto. Uno schermo senza takeover risponde 200 invariato (nessun incremento revisione, nessun evento).

Viene rimosso anche il contenuto prioritario di uno schermo archiviato: lo schermo resta archiviato, il suo Player non riceve segnali e, quando viene ripristinato, viene determinata la playlist effettiva. Su uno schermo protetto, la rimozione di un contenuto prioritario richiede una revisione da parte di una seconda persona autorizzata ad approvare (202 pending_review), a qualsiasi livello di accesso.

Autenticazione: projectBearer
Corpo della richiesta: nessuno
ID operazione: clearScreenTakeover

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
Screenrig-Review-Note	intestazione	opzionale	Nota opzionale del proponente su scrittura di classe review, inviata come UTF-8 percent-encoded (come scrive encodeURIComponent di JavaScript). Il server la percent-decodifica (un escape non valido è 400 invalid_request); la nota decodificata è testo semplice, massimo 280 caratteri dopo il trim, senza caratteri di controllo (altrimenti 400 invalid_request). Archiviato alla revisione quando la scrittura diventa una; ignorato se applicato in tempo reale.
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/takeover'

Risposte

Stato	Significato	Corpo e intestazioni
202	La scrittura è diventata una revisione sotto Proponi accesso e attende l’approvazione di una persona (docs/reviews.md). Una ripetizione con Idempotency-Key risponde con lo stesso corpo.	ReviewPending (application/json); headers: RateLimit-Policy, RateLimit
200	Schermo senza takeover.	Schermo (application/json); intestazioni: ETag, RateLimit-Policy, RateLimit
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/tab-shares¶

Avvia condivisione schede

Mostra schede del browser sugli schermi. Crea una playlist temporanea con una pagina iframe a piena area di 1920x1080 per scheda e prende il controllo di ogni schermo destinatario (motivo «Shared browser tab») fino a until, al massimo tra 24 ore (valore predefinito).

Le destinazioni sono l’unione di screen_ids, ogni schermo attivo in folder_ids e relative sottocartelle e ogni schermo attivo con almeno uno dei tags; gli schermi offline sono inclusi e mostrano la condivisione al ritorno.

Un chiamante limitato agli schermi (docs/screen-scope.md) raggiunge solo quelli nel suo ambito: uno schermo esterno viene ignorato (outside_screen_scope); il resto della richiesta segue le stesse regole.

Una sola scheda resta fino alla fine della condivisione; più schede avanzano dopo il duration_s di ciascuna. reload_s ricarica ogni pagina. qr aggiunge un codice QR dell’indirizzo in basso a destra, alto circa il 14% dell’area di composizione. cookies contiene l’accesso del mittente alle pagine: i cookie sono sigillati a riposo, mai restituiti da letture, eventi, voci di audit o revisioni e serviti solo nel manifesto di esecuzione di uno schermo che mostra la condivisione (il membro cookies dell’iframe); un Player che non può impostarli li ignora, come il Player web e gli involucri che gli delegano la riproduzione.

Una destinazione non controllabile (cartella protetta, nessuna playlist predefinita, archiviata, non trovata, formato incompatibile, fuori ambito o limitata) appare in skipped senza far fallire la richiesta. Questa condivisione sostituisce quella precedente sullo schermo; la vecchia playlist viene eliminata quando nessuno schermo la mostra più.

Se nessuna destinazione è controllata, la playlist temporanea viene eliminata e la risposta è il problema della destinazione singola o 409 resource_conflict con i motivi. warnings elenca gli indirizzi delle schede che il backend non ha potuto incorporare (embedding_blocked: X-Frame-Options o frame-ancestors rifiuta l’app web Player), verificati una volta per indirizzo con un limite di 3 secondi; non blocca mai la condivisione.

I limiti di controllo degli schermi si applicano per schermo destinatario (organizzazione e schermo) e il limite IP una volta per richiesta. Ogni chiamata crea una condivisione; un Idempotency-Key non riproduce nulla. La modifica è immediata: rifiutata con insufficient_access con accesso Propose e, nel canale del pannello, con approver_required per un membro che non può approvare revisioni.

Nel canale del pannello si usa il progetto corrente della sessione (no_project se assente). La richiesta può provenire dal pannello o da un’estensione Chrome o Firefox (chrome-extension://ID, moz-extension://UUID), con Sec-Fetch-Site assente, same-origin o none; un’intestazione X-ScreenRig-CSRF presente deve corrispondere a csrf_token di GET /api/session.

Solo questa rotta, DELETE /api/tab-shares/{id}, POST /api/playlists/{id}/pages e POST /api/screens/{id}/screenshot accettano un’origine di estensione.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: TabShareWrite
ID operazione: startTabShare

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.

Campi del corpo della richiesta

Campo	Descrizione
screen_ids (opzionale, array)	Schermi per id. I duplicati vengono unificati.
folder_ids (opzionale, array)	Cartelle di schermi; ognuna include tutte le sottocartelle.
tags (opzionale, array)	Uno schermo con almeno uno dei tag.
tabs (obbligatorio, array)
cookies (opzionale, array)	Cookie del mittente per le pagine, al massimo 64 KiB codificati. Segreti; vedi POST /api/tab-shares.
reload_s (opzionale, integer)	0 (mai, il valore predefinito) oppure da 60 a 86400: frequenza di ricaricamento dell’iframe di ogni pagina.
until (opzionale, string)	Strettamente nel futuro e al massimo tra 24 ore; 24 ore da ora se omesso. Termine del controllo di ogni destinazione e scadenza della playlist temporanea. format: "date-time"
qr (opzionale, boolean)	Con true ogni pagina mostra un codice QR del suo indirizzo in basso a destra. Valore predefinito false.

Modello richiesta e risposte

shell · modello richiesta

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/tab-shares'

Risposte

Stato	Significato	Corpo e intestazioni
200	La condivisione. Almeno uno schermo è stato preso in controllo.	TabShare (application/json); intestazioni: RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/tab-shares/{id}¶

Ottieni condivisione schede

Legge una condivisione: termine e schermi la cui playlist di controllo è ancora la sua (sono esclusi gli schermi controllati nel frattempo da altri o archiviati). 404 not_found se è terminata, scaduta o mai esistita. Un chiamante limitato agli schermi vede solo quelli nel suo ambito. Alle letture non si applicano regole sull’origine delle estensioni.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getTabShare

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	La condivisione e gli schermi che la mostrano ancora.	TabShareState (application/json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

ELIMINA/api/tab-shares/{id}¶

Interrompi condivisione schede

Termina una condivisione: rimuove il controllo di ogni schermo la cui playlist è ancora quella condivisa (screen.takeover_ended con motivo cleared; la programmazione o, in sua assenza, la playlist assegnata diventa effettiva con la stessa segnalazione del manifesto) ed elimina la playlist. Consentito sugli schermi in cartelle protette.

Uno schermo preso in controllo nel frattempo da altri resta invariato. 404 not_found se la condivisione è già terminata; il client la considera terminata. Ogni richiesta consuma un’unità di ciascun limite di controllo degli schermi. Un chiamante limitato agli schermi libera solo quelli nel proprio ambito. Canali, regole di accesso e regole sull’origine delle estensioni sono quelli di POST /api/tab-shares.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: stopTabShare

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Gli schermi il cui controllo è stato rimosso.	TabShareStopped (application/json); intestazioni: RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/play-page¶

Riproduci Screen Page

Chiede al lettore dello schermo di avviare una pagina della playlist in riproduzione, così lo screenshot successivo mostra quella pagina senza attendere la rotazione (docs/player-compatibility.md §6.3.1).

La pagina deve appartenere alla playlist effettiva dello schermo, quella da cui è costruito il suo manifest: un takeover attivo, altrimenti una campagna in vigore, altrimenti la voce corrente della programmazione delle playlist, altrimenti la playlist assegnata. In caso contrario 409 page_not_on_screen, il cui detail indica quella playlist.

L’host hint dello schermo deve dichiarare la capacità play_page, altrimenti 409 play_page_unsupported e nulla viene inviato; aggiornare il lettore. Lo schermo deve essere attivo; uno schermo archiviato risponde screen_archived e uno pairing_pending resource_conflict.

Aggiunge il comando runtime per schermo player.play_page (dettagli page_id, playlist_id, manifest_revision, expires_at sessanta secondi dopo; mai consegnato dopo expires_at). Il Player avvia la pagina dall’inizio come se la rotazione l’avesse raggiunta e continua la rotazione da lì. La revisione dello schermo non cambia.

L’Idempotency-Key è obbligatoria, come per toast; un retry esatto restituisce il corpo originale per ventiquattro ore. Una richiesta rifiutata, una fallita e una ripetizione esatta non consumano budget del limite di frequenza. I messaggi dello schermo sono esenti dal contatore API da 1 credito. Uno schermo in una cartella di schermi protetta è protected_target (409).

Autenticazione: projectBearer
Corpo della richiesta: ScreenPlayPageWrite
ID operazione: playScreenPage

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
Idempotency-Key	intestazione	obbligatorio

Campi del corpo della richiesta

Campo	Descrizione
page_id (obbligatorio, stringa)	L’id di una pagina della playlist che lo schermo sta riproducendo ora (un id nelle pagine di quella playlist). minLength: 1 maxLength: 128

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/play-page'

Risposte

Stato	Significato	Corpo e intestazioni
202	Accettato. Il comando è eseguibile fino a expires_at. Un retry idempotente esatto restituisce lo stesso corpo.	ScreenPlayPageAccepted (application/json); intestazioni: Cache-Control, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	protected_target quando lo schermo è in una cartella di schermi protetta (docs/screen-scope.md; rimuovi la protezione della cartella tramite una revisione, fai la modifica, proteggila di nuovo), oppure gli altri conflitti dell’operazione.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/identify¶

Identifica schermo

Chiede al Player dello schermo di mostrare il nome dello schermo sopra i suoi contenuti per duration_ms (da 2000 a 600000, predefinito 60000), così una persona davanti a più display può capire a quale corrisponde un record (docs/player-compatibility.md §6.3.2).

Aggiunge il comando runtime per schermo player.identify (details identify_id, label, screen_id, duration_ms, at, expires_at sessanta secondi dopo at; mai consegnato dopo expires_at).

Il Player disegna una sovrapposizione a schermo intero sopra i suoi contenuti, con il nome molto grande e l’id dello schermo in piccolo sotto, per duration_ms dalla ricezione; la riproduzione continua sotto e un’identificazione più recente sostituisce la sovrapposizione.

L’host hint dello schermo deve dichiarare la capacità identify, altrimenti 409 identify_unsupported e non viene inviato nulla; aggiorna il Player, oppure mostra il nome con un toast. Lo schermo deve essere attivo; uno schermo archiviato risponde screen_archived e uno pairing_pending resource_conflict. La revisione dello schermo non cambia.

Il corpo e l’Idempotency-Key sono opzionali; un retry esatto restituisce il corpo originale per ventiquattro ore. Una richiesta rifiutata, una richiesta fallita e una ripetizione esatta non consumano budget del limite di frequenza. I messaggi dello schermo sono esenti dal contatore API da 1 credito.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ScreenIdentifyWrite
ID operazione: identifyScreen

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
duration_ms (opzionale, intero)	Per quanto tempo la sovrapposizione resta visibile, in millisecondi dalla ricezione da parte del Player. I valori omessi assumono 60000. predefinito: 60000 minimo: 2000 massimo: 600000

Modello richiesta e risposte

shell · modello richiesta

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/screens/RESOURCE_ID/identify'

Risposte

Stato	Significato	Corpo e intestazioni
202	Accettato. Il comando è eseguibile fino a expires_at. Un retry idempotente esatto restituisce lo stesso corpo.	ScreenIdentifyAccepted (application/json); intestazioni: Cache-Control, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/suspend¶

Sospendi schermo

Sospende lo schermo: il suo Player mostra message al posto dei suoi contenuti (docs/player-compatibility.md §6.9). Il messaggio è lungo da 1 a 280 caratteri dopo il trim; il ritorno a capo è l’unico carattere di controllo accettato.

Non cambia nient’altro: la playlist, la programmazione, il takeover, il controllo del display e ogni altra impostazione restano al loro posto e continuano a evolversi, e la ripresa mostra ciò che lo schermo starebbe mostrando ora. Screen.suspension contiene il messaggio e since. Sospendere uno schermo già sospeso sostituisce il messaggio e mantiene since.

Il manifesto runtime di uno schermo sospeso ha pages [] e un membro suspension, e una revisione del manifesto propria, con o senza una playlist assegnata; al Player viene indicato di recuperarlo di nuovo subito. Aggiunge l’evento solo di progetto screen.suspended (details message). Uno schermo archiviato risponde screen_archived. If-Match e Idempotency-Key sono opzionali, come su archive.

Uno schermo in una cartella di schermi protetta è protected_target (409).

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ScreenSuspendWrite
ID operazione: suspendScreen

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
message (obbligatorio, stringa)	L’avviso che lo schermo mostra, da 1 a 280 caratteri dopo il trim. Il ritorno a capo è l’unico carattere di controllo accettato; un Player manda a capo il testo e mantiene i ritorni a capo. minLength: 1 maxLength: 280

Modello richiesta e risposte

shell · modello richiesta

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/screens/RESOURCE_ID/suspend'

Risposte

Stato	Significato	Corpo e intestazioni
200	Schermo sospeso. L’ETag è la nuova revisione dello schermo.	Schermo (application/json); intestazioni: ETag
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	protected_target quando lo schermo è in una cartella di schermi protetta (docs/screen-scope.md; rimuovi la protezione della cartella tramite una revisione, fai la modifica, proteggila di nuovo), oppure gli altri conflitti dell’operazione.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/resume¶

Riprendi schermo

Termina la sospensione dello schermo: il suo Player torna a mostrare i contenuti propri dello schermo, dal manifesto che lo schermo riceverebbe ora (docs/player-compatibility.md §6.9). Al Player viene indicato di recuperare subito di nuovo i dati. Aggiunge l’evento solo di progetto screen.resumed. Riprendere uno schermo che non è sospeso risponde 200 con lo schermo invariato: nessun incremento della revisione e nessun evento.

Uno schermo archiviato risponde screen_archived. Nessun corpo. If-Match e Idempotency-Key sono opzionali, come su archive.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: resumeScreen

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Schermo ripreso, oppure non sospeso. L’ETag è la revisione dello schermo.	Schermo (application/json); intestazioni: ETag
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/reboot¶

Riavvia schermo

Chiede al Player dello schermo di riavviare il dispositivo (docs/player-compatibility.md §6.5). Il corpo opzionale imposta expires_in_s, per quanto tempo il riavvio resta eseguibile (da 60 a 86400 secondi, predefinito 86400, 24 ore); un valore fuori intervallo è invalid_request che nomina expires_in_s. Aggiunge sempre l’evento solo di progetto screen.reboot_requested.

A uno schermo online viene inviato subito il comando runtime per schermo player.reboot (details reboot_id, reason project, at, expires_at; mai consegnato dopo expires_at) e il riavvio viene registrato in Screen.commands come sent.

Uno schermo offline tiene il riavvio in stato queued senza alcun evento; quando il backend applica la successiva transizione online dello schermo prima di expires_at, l’evento viene aggiunto, con lo stesso reboot_id e lo stesso expires_at, e il comando diventa sent. Un riavvio inviato diventa done quando un rapporto di salute con uptime_s colloca l’avvio dopo il suo invio.

Un riavvio più recente sostituisce uno più vecchio ancora in coda. Un riavvio in coda oltre expires_at risulta expired, e POST /api/screens/{id}/commands/{command_id}/cancel ne annulla uno ancora in coda. Lo schermo deve essere attivo; uno schermo archiviato risponde screen_archived e uno pairing_pending resource_conflict.

L’host hint dello schermo deve dichiarare la capacità reboot, altrimenti 409 reboot_unsupported e non viene registrato nulla. La revisione dello schermo non cambia. If-Match e Idempotency-Key sono opzionali; un retry esatto restituisce lo stesso corpo per ventiquattro ore.

Al massimo 2 per schermo ogni 10 minuti; una richiesta rifiutata (reboot_unsupported, not_found, un conflitto), una richiesta fallita e una ripetizione esatta con Idempotency-Key non consumano nulla.

Dal momento in cui il riavvio viene inviato finché un report di salute non lo dà per completato o passano dieci minuti, lo schermo non genera alcun avviso o alert screen_offline, display_disconnected o crashing; una condizione che persiste allora si apre normalmente. La programmazione dei riavvii (PUT /api/screens/{id}/reboot-schedule) emette lo stesso riavvio con source schedule.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ScreenCommandWrite
ID operazione: rebootScreen

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
expires_in_s (opzionale, intero)	Per quanto tempo il comando resta eseguibile, in secondi dalla richiesta. Un comando in coda viene inviato solo prima della scadenza; un Player ne ignora uno dopo expires_at. predefinito: 86400 minimo: 60 massimo: 86400

Modello richiesta e risposte

shell · modello richiesta

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/screens/RESOURCE_ID/reboot'

Risposte

Stato	Significato	Corpo e intestazioni
202	Accettato. state è sent quando il riavvio è andato al Player dello schermo online, queued quando attende che lo schermo torni online. Il riavvio è eseguibile fino a expires_at. L’ETag è la revisione dello schermo invariata.	ScreenRebootAccepted (application/json); intestazioni: Cache-Control, ETag, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/clear-cache¶

Svuota cache schermo

Chiede al Player dello schermo di svuotare le sue cache (docs/player-compatibility.md §6.5.1). Il Player elimina i media scaricati, i pacchetti applicativi e le cache dei dati, mantiene associazione, identità e impostazioni, poi recupera di nuovo il manifest e i contenuti.

Il corpo opzionale imposta expires_in_s, per quanto tempo il comando resta utilizzabile (da 60 a 86400 secondi, predefinito 86400, 24 ore); un valore fuori intervallo è invalid_request che nomina expires_in_s. Aggiunge sempre screen.command_requested, riservato al progetto.

Uno schermo online riceve subito il comando runtime per schermo player.clear_cache (dettagli command_id, command, reason project, at, expires_at; mai consegnato dopo expires_at) e il comando è registrato in Screen.commands come sent.

Uno schermo offline mantiene il comando come queued senza evento; quando il backend applica la successiva transizione online dello schermo prima di expires_at l’evento viene aggiunto, con lo stesso command_id e lo stesso expires_at, e il comando diventa sent.

Il Player riporta come è terminato: il comando diventa done o failed in Screen.commands con la causa riportata dal Player (cause, detail), e viene aggiunto screen.command_result, riservato al progetto. Un comando sent senza report resta sent.

Un comando più recente dello stesso tipo sostituisce uno ancora in coda, e POST /api/screens/{id}/commands/{command_id}/cancel ne annulla uno ancora in coda. Lo schermo deve essere attivo; uno schermo archiviato risponde screen_archived e uno pairing_pending risponde resource_conflict.

Il suggerimento host dello schermo deve dichiarare la capacità clear_cache, altrimenti 409 command_unsupported e nulla viene registrato. La revisione dello schermo non cambia. If-Match e Idempotency-Key sono opzionali; un nuovo tentativo esatto restituisce lo stesso corpo per ventiquattro ore.

Al massimo 2 per schermo ogni 10 minuti tra clear-cache, restart-app e update; una richiesta rifiutata (command_unsupported, not_found, un conflitto), una fallita e una ripetizione esatta di Idempotency-Key non consumano nulla.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ScreenCommandWrite
ID operazione: clearScreenCache

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
expires_in_s (opzionale, intero)	Per quanto tempo il comando resta eseguibile, in secondi dalla richiesta. Un comando in coda viene inviato solo prima della scadenza; un Player ne ignora uno dopo expires_at. predefinito: 86400 minimo: 60 massimo: 86400

Modello richiesta e risposte

shell · modello richiesta

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/screens/RESOURCE_ID/clear-cache'

Risposte

Stato	Significato	Corpo e intestazioni
202	Accettato. state è sent quando il comando è andato al Player dello schermo online, queued quando attende che lo schermo torni online. Il comando è utilizzabile fino a expires_at. L’ETag è la revisione dello schermo invariata.	ScreenMaintenanceAccepted (application/json); intestazioni: Cache-Control, ETag, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/restart-app¶

Riavvia app schermo

Chiede al Player dello schermo di riavviare la sua applicazione, non il dispositivo (docs/player-compatibility.md §6.5.1). Il processo del Player si riavvia e riporta dal nuovo processo. Il corpo opzionale imposta expires_in_s, per quanto tempo il comando resta utilizzabile (da 60 a 86400 secondi, predefinito 86400, 24 ore); un valore fuori intervallo è invalid_request che nomina expires_in_s.

Aggiunge sempre screen.command_requested, riservato al progetto. Uno schermo online riceve subito il comando runtime per schermo player.restart_app (dettagli command_id, command, reason project, at, expires_at; mai consegnato dopo expires_at) e il comando è registrato in Screen.commands come sent.

Il suggerimento host dello schermo deve dichiarare la capacità restart_app, altrimenti 409 command_unsupported e nulla viene registrato. La revisione dello schermo non cambia. If-Match e Idempotency-Key sono opzionali; un nuovo tentativo esatto restituisce lo stesso corpo per ventiquattro ore.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ScreenCommandWrite
ID operazione: restartScreenApp

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
expires_in_s (opzionale, intero)	Per quanto tempo il comando resta eseguibile, in secondi dalla richiesta. Un comando in coda viene inviato solo prima della scadenza; un Player ne ignora uno dopo expires_at. predefinito: 86400 minimo: 60 massimo: 86400

Modello richiesta e risposte

shell · modello richiesta

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/screens/RESOURCE_ID/restart-app'

Risposte

Stato	Significato	Corpo e intestazioni
202	Accettato. state è sent quando il comando è andato al Player dello schermo online, queued quando attende che lo schermo torni online. Il comando è utilizzabile fino a expires_at. L’ETag è la revisione dello schermo invariata.	ScreenMaintenanceAccepted (application/json); intestazioni: Cache-Control, ETag, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/update¶

Aggiorna Player dello schermo

Chiede al Player dello schermo di controllare subito l’ultima release del Player e di installarla (docs/player- compatibility.md §6.5.1). La causa del risultato è up_to_date quando l’ultima release è già in esecuzione e updated quando è stata installata una release; un’installazione gestita da uno store o dal dispositivo non dichiara la capacità di aggiornamento.

Uno schermo online riceve subito il comando runtime per schermo player.update (dettagli command_id, command, reason project, at, expires_at; mai consegnato dopo expires_at) e il comando è registrato in Screen.commands come sent.

Il suggerimento host dello schermo deve dichiarare la capacità update, altrimenti 409 command_unsupported e nulla viene registrato. La revisione dello schermo non cambia. If-Match e Idempotency-Key sono opzionali; un nuovo tentativo esatto restituisce lo stesso corpo per ventiquattro ore.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ScreenCommandWrite
ID operazione: updateScreenPlayer

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
expires_in_s (opzionale, intero)	Per quanto tempo il comando resta eseguibile, in secondi dalla richiesta. Un comando in coda viene inviato solo prima della scadenza; un Player ne ignora uno dopo expires_at. predefinito: 86400 minimo: 60 massimo: 86400

Modello richiesta e risposte

shell · modello richiesta

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/screens/RESOURCE_ID/update'

Risposte

Stato	Significato	Corpo e intestazioni
202	Accettato. state è sent quando il comando è andato al Player dello schermo online, queued quando attende che lo schermo torni online. Il comando è utilizzabile fino a expires_at. L’ETag è la revisione dello schermo invariata.	ScreenMaintenanceAccepted (application/json); intestazioni: Cache-Control, ETag, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}/commands¶

Elenca comandi schermo

Elenca ogni riavvio e ricaricamento richiesto a uno schermo attivo o archiviato, dal più recente: i comandi contenuti in Screen.commands (i 10 più recenti) e tutti quelli più vecchi, con lo stato raggiunto. Un comando ancora in coda dopo expires_at risulta expired. Un comando ancora in coda quando il dispositivo dello schermo è stato sostituito risulta cancelled.

Annulla un comando ancora in coda con POST /api/screens/{id}/commands/{command_id}/cancel.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: listScreenCommands

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
cursore	query	opzionale	Il next_cursor della pagina precedente.
limite	query	opzionale

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Una pagina dei comandi dello schermo.	ScreenCommandPage (application/json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/commands/{command_id}/cancel¶

Annulla comando schermo

Annulla un riavvio o una ricarica ancora in coda per lo schermo, così che il comando non venga mai inviato (docs/player-compatibility.md §6.3, §6.5). command_id è un id in Screen.commands, oppure il reboot_id o il reload_id della risposta 202. Solo un comando il cui state è queued può essere annullato; diventa cancelled.

Un comando già inviato (sent, done) risponde 409 resource_conflict "The command was already sent."; uno non più in coda (expired, cancelled, superseded) risponde 409 resource_conflict "The command is no longer queued."; un id che lo schermo non elenca risponde 404 not_found. L’elenco dello schermo conserva i suoi 10 comandi più recenti.

La revisione dello schermo non cambia. If-Match e Idempotency-Key sono opzionali; un retry esatto restituisce lo stesso schermo per ventiquattro ore.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: cancelScreenCommand

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
command_id	path	obbligatorio	L’id di uno dei comandi dello schermo: l’id in Screen.commands, il reboot_id o il reload_id della risposta 202.
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/commands/COMMAND_ID/cancel'

Risposte

Stato	Significato	Corpo e intestazioni
200	Lo schermo, con il comando annullato. L’ETag è la revisione dello schermo invariata.	Schermo (application/json); intestazioni: ETag
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/display¶

Imposta il display dello schermo

Richiede ora l’accensione o lo spegnimento del display: una sovrascrittura manuale del programma display (docs/player-compatibility.md §6.5). power è acceso o spento. until (RFC 3339, futuro rigoroso, massimo 7 giorni avanti) termina l’effetto; senza until termina al prossimo confine del programma display se abilitato, altrimenti resta attivo finché non sostituito.

Memorizza l’override (Screen.display.override), rigenera il manifesto (il suo membro display contiene l’override così un Player offline lo mantiene), aggiunge il comando runtime player.display (dettagli override_id, power, until, at, expires_at) e lo screen.display_changed solo progetto, e incrementa la revisione dello schermo (If-Match lo protegge). Lo schermo deve essere attivo.

Ciò che il lettore ha realizzato viene riportato nel suo stato di salute display.power (Screen.display.reported). Il successo salva l’intenzione senza attendere un report; Screen.display.override_status confronta le osservazioni successive e Screen.display.control indica il metodo di controllo dichiarato.

Un Player con solo velo rimuove la sua sovrapposizione a una richiesta di accensione, senza un comando hardware di riattivazione.

Senza until e senza un confine di programmazione entro gli otto giorni successivi (nessuna programmazione abilitata o nessuna che cambi), l’override dura fino a DELETE /api/screens/{id}/display o una sostituzione; un successivo PUT o DELETE display-schedule, o un cambio di fuso orario, riporta un override senza until al nuovo confine successivo.

Una richiesta rifiutata o fallita, e una ripetizione esatta di Idempotency-Key, non consumano budget. Uno schermo in una cartella di schermi protetta è protected_target (409).

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: ScreenDisplayWrite
ID operazione: setScreenDisplay

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
power (obbligatorio, stringa)	Consentito: "on", "off"
fino a (opzionale, inline)	Solo futuro, massimo 7 giorni avanti. Omissione o null: fino al prossimo confine del programma display, altrimenti fino a sostituzione.

Modello richiesta e risposte

shell · modello richiesta

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/screens/RESOURCE_ID/display'

Risposte

Stato	Significato	Corpo e intestazioni
200	Schermo con il suo stato display.	Schermo (application/json); intestazioni: ETag, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	protected_target quando lo schermo è in una cartella di schermi protetta (docs/screen-scope.md; rimuovi la protezione della cartella tramite una revisione, fai la modifica, proteggila di nuovo), oppure gli altri conflitti dell’operazione.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

ELIMINA/api/screens/{id}/display¶

Cancella visualizzazione schermo

Termina l’override manuale del display così si applica di nuovo la programmazione del display (altrimenti acceso). Rigenera il manifesto (il membro display rimuove l’override; il Player segue screen.manifest_changed), aggiunge screen.display_changed con cambio override_cleared e incrementa la revisione. Uno schermo senza override attivo risponde 200 invariato.

Uno schermo in una cartella di schermi protetta è protected_target (409).

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: clearScreenDisplay

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Schermo con il suo stato display.	Schermo (application/json); intestazioni: ETag, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	protected_target quando lo schermo è in una cartella di schermi protetta (docs/screen-scope.md; rimuovi la protezione della cartella tramite una revisione, fai la modifica, proteggila di nuovo), oppure gli altri conflitti dell’operazione.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}/display-schedule¶

Ottieni programmazione display schermo

Restituisce display_schedule (null se assente) e lo stato di visualizzazione dello schermo. L’ETag è la revisione dello schermo.

Autenticazione: projectBearer
Corpo della richiesta: nessuno
ID operazione: getScreenDisplaySchedule

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/display-schedule'

Risposte

Stato	Significato	Corpo e intestazioni
200	Programmazione display.	ScreenDisplayScheduleView (application/json); intestazioni: ETag
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PUT/api/screens/{id}/display-schedule¶

Imposta la programmazione del display dello schermo

Sostituisce la programmazione display: abilitata e da 1 a 16 finestre screenrig.schedule/v1 (giorni, inizio/fine HH:MM, fine <= inizio attraversa la mezzanotte di proprietà del giorno di inizio, giorno intero senza bordi) quando il display è acceso; fuori da ogni finestra il Player mette il display in standby.

Valutato sul dispositivo nel fuso orario dello schermo (obbligatorio, altrimenti invalid_request), così funziona offline: il membro display del manifesto lo porta. enabled false mantiene le finestre e lascia acceso il display. Rigenera il manifesto, aggiunge screen.display_changed, incrementa la revisione (If-Match lo protegge). Lo schermo deve essere pairing_pending o attivo.

Uno schermo senza ancora un manifest (mai generato, o senza playlist) memorizza la programmazione e il suo primo manifest la porta con sé; uno schermo senza playlist la applica una volta assegnata una playlist. Un override senza until viene riportato entro il confine successivo della nuova programmazione. Uno schermo in una cartella di schermi protetta è protected_target (409).

Autenticazione: projectBearer
Corpo della richiesta: ScreenDisplayScheduleWrite
ID operazione: setScreenDisplaySchedule

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
abilitato (obbligatorio, booleano)
windows (obbligatorio, array)	Su Windows.

Modello richiesta e risposte

shell · modello richiesta

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/display-schedule'

Risposte

Stato	Significato	Corpo e intestazioni
200	Schermo con il suo stato display.	Schermo (application/json); intestazioni: ETag, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	protected_target quando lo schermo è in una cartella di schermi protetta (docs/screen-scope.md; rimuovi la protezione della cartella tramite una revisione, fai la modifica, proteggila di nuovo), oppure gli altri conflitti dell’operazione.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

ELIMINA/api/screens/{id}/display-schedule¶

Cancella programmazione visualizzazione schermo

Rimuove la programmazione del display (il display resta acceso salvo override). Rimuoverne una che non c’è risponde 200 invariato. Uno schermo in una cartella di schermi protetta è protected_target (409).

Autenticazione: projectBearer
Corpo della richiesta: nessuno
ID operazione: clearScreenDisplaySchedule

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/display-schedule'

Risposte

Stato	Significato	Corpo e intestazioni
200	Schermo con il suo stato display.	Schermo (application/json); intestazioni: ETag, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	protected_target quando lo schermo è in una cartella di schermi protetta (docs/screen-scope.md; rimuovi la protezione della cartella tramite una revisione, fai la modifica, proteggila di nuovo), oppure gli altri conflitti dell’operazione.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope come su OutsideScreenScope, oppure approver_required - un membro limitato agli schermi che non può approvare le revisioni non cambia ciò che uno schermo riproduce né quando (docs/screen-scope.md).	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}/reboot-schedule¶

Ottieni la programmazione dei riavvii dello schermo

Restituisce reboot_schedule (null se assente) e next_reboot_at, l'inizio della prossima finestra in cui il backend riavvia lo schermo (null se non c'è). L'ETag è la revisione dello schermo.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getScreenRebootSchedule

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Programmazione dei riavvii.	ScreenRebootScheduleView (application/json); headers: ETag
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PUT/api/screens/{id}/reboot-schedule¶

Imposta la programmazione dei riavvii dello schermo

Sostituisce la programmazione dei riavvii: enabled e da 1 a 16 finestre screenrig.schedule/v1 (days, start/end HH:MM, end <= start attraversa la mezzanotte appartenente al giorno di inizio, giornata intera senza estremi), ciascuna lunga da 5 minuti a 24 ore.

All'inizio di ogni finestra nel fuso orario dello schermo (obbligatorio, altrimenti invalid_request) il backend emette lo stesso riavvio che emette POST /api/screens/{id}/reboot, con source schedule in Screen.commands, screen.reboot_requested e i dettagli di player.reboot.

Un inizio dentro un salto in avanti dell'ora legale scatta al primo minuto valido della finestra; una finestra senza minuti validi quel giorno, perché cade interamente nel salto, viene saltata con screen.reboot_skipped reason window_missed (next_reboot_at mostra il minuto in cui finisce il salto). Una ripetizione per il ritorno all'ora solare scatta una volta per finestra per data locale.

Uno schermo online riceve subito il riavvio; uno offline lo tiene in coda solo fino alla fine della sua finestra (expires_at), così un riavvio in ritardo non cade mai fuori da essa. Un'occorrenza non sostituisce mai un riavvio richiesto da una persona che attende ancora lo schermo: viene saltata con screen.reboot_skipped reason reboot_pending.

Un cambio di fuso orario annulla i riavvii programmati ancora in attesa e sposta next_reboot_at nel nuovo fuso.

Un riavvio, pianificato o richiesto, non genera alert screen_offline, display_disconnected o crashing per dieci minuti dopo l'invio, e un avviso per uno di essi in scadenza in quel lasso attende la fine del periodo più la sua attesa (un avviso crashing viene saltato come planned_reboot). enabled false mantiene le finestre e non riavvia nulla.

Le finestre temporali che non lasciano alcun intervallo, così che nessun inizio segue, sono invalid_request. L'hint host dello schermo deve dichiarare la capability reboot, altrimenti 409 reboot_unsupported e nulla viene memorizzato; uno schermo che la perde in seguito salta ogni finestra con screen.reboot_skipped e mantiene la sua programmazione.

Aggiunge screen.reboot_schedule_changed, incrementa la revisione (If-Match la protegge) e non rigenera mai il manifest. Lo schermo deve essere attivo.

Autenticazione: projectBearer
Corpo della richiesta: ScreenRebootScheduleWrite
ID operazione: setScreenRebootSchedule

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
abilitato (obbligatorio, booleano)
windows (obbligatorio, array)	Finestre di riavvio: il backend riavvia lo schermo all'inizio di ciascuna, nel fuso orario dello schermo. Ciascuna dura da 5 minuti a 24 ore.

Modello richiesta e risposte

shell · modello richiesta

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/reboot-schedule'

Risposte

Stato	Significato	Corpo e intestazioni
200	Schermo con la sua programmazione dei riavvii e next_reboot_at.	Schermo (application/json); intestazioni: ETag, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
402	feature_not_in_plan — I riavvii programmati fanno parte di Plus; enabled true li richiede, enabled false e DELETE no. Il problema indica la funzione, il piano del progetto e required_plan.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

ELIMINA/api/screens/{id}/reboot-schedule¶

Cancella la programmazione dei riavvii dello schermo

Rimuove la programmazione dei riavvii e next_reboot_at; un riavvio già emesso non viene annullato (POST /api/screens/{id}/commands/{command_id}/cancel ne annulla uno ancora in coda). Cancellare none risponde 200 unchanged.

Autenticazione: projectBearer
Corpo della richiesta: nessuno
ID operazione: clearScreenRebootSchedule

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://screenrig.ai/api/screens/RESOURCE_ID/reboot-schedule'

Risposte

Stato	Significato	Corpo e intestazioni
200	Schermo senza programmazione dei riavvii.	Schermo (application/json); intestazioni: ETag, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/toast¶

Toast post-schermo

Invia un toast transitorio stage-chrome allo schermo nominato. Un toast non è un primitivo: non occupa uno slot tela, non ha layer e non partecipa mai a readiness o crossfade. Il tipo evento duraturo è screen.toast sul flusso SSE runtime esistente. La scansione runtime non consegna mai un toast dopo expires_at, quindi un cursore persistente non può riprodurlo in seguito.

I colori del livello sono parte del chrome del lettore e non sono campi API. Il testo va da 1 a 120 caratteri, il ritorno a capo è l’unica interruzione di linea accettata, e al massimo sono accettate tre linee; un Player mostra un toast su una riga, un ritorno a capo come spazio.

Materiale riconoscibile delle credenziali ScreenRig e altri caratteri di controllo sono rifiutati. duration_ms predefinito è 60000 e deve essere compreso tra 2000 e 60000 inclusi. Un retry con Idempotency-Key esatto restituisce l’originale expires_at per ventiquattro ore. Latest-wins: non c’è coda né verbo cancel. I messaggi schermo sono esenti dal contatore API da 1 credito.

Uno schermo in una cartella di schermi protetta è protected_target (409).

Autenticazione: projectBearer
Corpo della richiesta: ScreenToastWrite
ID operazione: postScreenToast

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
Idempotency-Key	intestazione	obbligatorio

Campi del corpo della richiesta

Campo	Descrizione
livello (obbligatorio, stringa)	Token gravità chiuso. Il chrome Player sceglie il riempimento; l’API non porta mai un colore. Consentiti: "error", "alert", "info"
testo (obbligatorio, stringa)	Da 1 a 120 caratteri. L’unico a capo accettato è il ritorno a capo. Al massimo tre righe; un Player mostra il toast su una riga, un ritorno a capo come spazio. Altri caratteri di controllo e materiale riconoscibile di credenziali ScreenRig sono rifiutati. minLength: 1 maxLength: 120
duration_ms (opzionale, intero)	Durata visibile in millisecondi. I valori omessi assumono 60000. default: 60000 minimo: 2000 massimo: 60000

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/toast'

Risposte

Stato	Significato	Corpo e intestazioni
202	Accettato. Il toast è durevole fino a expires_at. Un retry idempotente esatto restituisce la stessa scadenza.	ScreenToastAccepted (application/json); intestazioni: Cache-Control, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	protected_target quando lo schermo è in una cartella di schermi protetta (docs/screen-scope.md; rimuovi la protezione della cartella tramite una revisione, fai la modifica, proteggila di nuovo), oppure gli altri conflitti dell’operazione.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/storage-forecast¶

Previsione spazio di archiviazione schermo

Simulazione di adattamento pre-assegnazione: risponde se una playlist si adatterebbe allo schermo nominato prima di essere assegnata, con la stessa selezione target di Screen.storage_forecast (l’ultima capacità segnalata dello schermo, solo piano A.3, nessuna previsione di transizione, nulla trattato come locale).

Non scrive nulla: nessuna assegnazione, nessuna revisione schermo, nessun evento, e il modello di lettura storage_forecast dello schermo resta intatto. Il bearer progetto è autorevole; uno schermo o playlist di altro progetto è not_found. fit è sconosciuto quando lo schermo non ha report storage, o quando i riferimenti contenuto della playlist non sono pronti, e allora entrambi i conteggi byte sono null.

Una playlist_revision opzionale rifiuta una playlist che è cambiata da quando il chiamante l’ha letta con revision_conflict. Un report più vecchio di 24 ore è obsoleto ma ancora usato per previsioni, esattamente come Screen.storage_forecast.

Autenticazione: projectBearer
Corpo della richiesta: ScreenStorageForecastRequest
ID operazione: forecastScreenStorage

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Campi del corpo della richiesta

Campo	Descrizione
playlist_id (obbligatorio, stringa)	minLength: 1
playlist_revision (opzionale, intero)	Revisione opzionale prevista della playlist. Una revisione memorizzata diversa è revision_conflict e non viene restituita alcuna previsione. minimo: 1

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/storage-forecast'

Risposte

Stato	Significato	Corpo e intestazioni
200	Previsione dry-run. fit unknown significa che non c’è nulla da prevedere; i conteggi byte e received_at sono nulli.	ScreenStorageForecastDryRun (application/json); intestazioni: Cache-Control, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
412	revision_conflict — playlist_revision non è la revisione corrente della playlist; nessuna previsione viene restituita.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}/campaigns¶

Spiega campagne dello schermo

Perché ogni campagna del progetto viene riprodotta o meno su questo schermo, in ordine di precedenza, con la playlist effettiva dello schermo. items e effective_playlist sono lo stato attuale dello schermo.

Con at (e facoltativamente to), at è lo stesso risolutore eseguito dalla scansione dei limiti, interrogato su quell’istante, con un verdetto per il takeover, ogni campagna e ogni voce del programma (won, outranked, not_started, ended, outside_hours, off), la playlist in quell’istante e ciò che la risposta non giudica.

Con anche to, at.timeline elenca gli intervalli tra at e to in cui la playlist non cambia. Il programma, il takeover e le campagne sono letti come sono ora.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: explainScreenCampaigns

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
alle	query	opzionale	L’istante da spiegare, in RFC 3339 con fuso (2026-03-08T09:30:00Z o 2026-03-08T01:30:00-08:00) oppure un orario sull’orologio dello schermo (2026-03-08T09:30, con secondi facoltativi). Un orario che l’ora legale salta o ripete viene rifiutato con invalid_request che nomina at, e uno ripetuto nomina i due istanti tra cui scegliere. Predefinito: ora, quando è indicato solo to.
a	query	opzionale	Fine della cronologia dei cambi che inizia a at, nelle stesse due forme di at. Successiva ad at, senza limite di distanza; una risposta elenca al massimo 500 intervalli, e otto giorni senza cambi contano come uno; timeline_truncated indica che si è fermata prima di raggiungere to.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Lo stato di ogni campagna sullo schermo.	ScreenCampaigns (application/json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}/screenshot¶

Ottieni screenshot schermo

Restituisce il WebP pronto corrente per lo schermo nominato. L’optional capture_id deve corrispondere a quello slot pronto. Un capture_id nominato scaduto senza upload è screenshot_unavailable. Un capture_id nominato sostituito da una richiesta successiva è resource_conflict. I byte dell’immagine non sono mai un URL firmato o una chiave oggetto. Range non è accettato.

I messaggi dello schermo sono esenti dal contatore API da 1 credito. L’ETag è il forte SHA-256 del WebP memorizzato. Una risposta di sessione dashboard è privata, no-cache, e un If-None-Match dashboard che corrisponde all’immagine corrente, verificato dopo che schermo e cattura si risolvono nel progetto della sessione, restituisce 304 senza aprire i byte memorizzati.

Una risposta bearer progetto resta privata, no-store.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getScreenScreenshot

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
capture_id	query	opzionale
If-None-Match	intestazione	opzionale	ETag forte di uno screenshot restituito da questa rotta. Rispettato per sessione dashboard.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Immagine corrente pronta ancora in WebP.	stringa (image/webp); intestazioni: Content-Type, Content-Length, ETag, X-ScreenRig-Capture-ID, X-ScreenRig-Captured-At, Cache-Control, Content-Disposition
304	Solo sessione dashboard. L’ETag dell’immagine corrente corrisponde a If-None-Match. Nessun corpo è prodotto e l’archivio oggetti non viene letto. Le intestazioni di cattura nominano la cattura corrente, che può differire dalla risposta archiviata quando una cattura successiva è codificata negli stessi byte.	nessun corpo; intestazioni: ETag, Cache-Control, X-ScreenRig-Capture-ID, X-ScreenRig-Captured-At
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/screenshot¶

Richiedi screenshot dello schermo

Richiede uno screenshot fisso dello schermo attivo nominato. Latest-wins: una nuova richiesta sostituisce qualsiasi capture_id in corso e non genera 409. Lo slot pronto corrente è mantenuto finché un upload successivo non riesce. capture_id è un prefisso ambiente opzionale, poi shot_ e un suffisso casuale. expires_at è trenta secondi dopo l’accettazione.

Il tipo di evento duraturo è screen.screenshot_requested sul flusso SSE runtime esistente; la scansione runtime non lo consegna mai dopo expires_at. I dettagli dell’evento sono nome capture_id, expires_at, max_width_divisor 2, max_height_divisor 2, formato image/webp, qualità 80 e max_bytes 2097152. I byte dell’immagine non appaiono mai su SSE.

Il credito prepagato residuo non è un blocco, e questo percorso messaggio-schermo è esente dal contatore API da 1 credito. Un retry con Idempotency-Key esatto restituisce capture_id e expires_at originali per ventiquattro ore.

Nel canale del pannello la richiesta può provenire da un’estensione Chrome o Firefox come POST /api/tab-shares, per confermare una scheda condivisa (GET /api/screens/{id}/screenshot/status e GET /api/screens/{id}/screenshot non richiedono regole sull’origine).

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: requestScreenScreenshot

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
Idempotency-Key	intestazione	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' 'https://screenrig.ai/api/screens/RESOURCE_ID/screenshot'

Risposte

Stato	Significato	Corpo e intestazioni
202	Accettato. La richiesta è durevole fino a expires_at. Un retry idempotente esatto restituisce lo stesso capture_id e scadenza.	ScreenScreenshotAccepted (application/json); intestazioni: Cache-Control, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}/screenshot/status¶

Ottieni stato screenshot schermo

Restituisce la macchina a stati dello screenshot per lo schermo nominato quando esiste per questo progetto. idle non ha richiesta né slot pronto. pending è l’attuale capture_id prima di expires_at senza upload. ready significa che l’ultimo upload riuscito corrisponde all’attuale capture_id. timed_out significa che l’id corrente ha raggiunto expires_at senza upload.

Il timeout è pigro: il primo GET di stato o il successivo POST dopo la scadenza lo registra e aggiunge screen.screenshot_failed una volta con motivo expired. Una richiesta scaduta non elimina uno slot pronto più vecchio. I messaggi dello schermo sono esenti dal contatore API da 1 credito.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getScreenScreenshotStatus

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Stato dello screenshot per lo schermo di questo progetto.	ScreenScreenshotStatus (application/json); intestazioni: Cache-Control
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}/live¶

Ottenere la sessione live dello schermo

Returns the screen's live session after lazy expiry: idle when it has none, requested while the Player has been asked to publish, publishing once the media relay holds its video, ended with ended_reason (stopped, expired, consent_denied, consent_timeout, capture_failed, connection_failed or player_stopped; an open enum) for ten minutes after it ended. publisher.connected is true only while the Player's last report, at most 45 seconds old, said it is connected; it is the Player's own word, not proof of picture. 404 feature_unavailable when the server has no media relay configured.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getScreenLive

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	La sessione live dello schermo.	LiveSession (application/json); intestazioni: Cache-Control
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/live¶

Avviare la sessione live dello schermo

Starts live view of the named screen, or renews the one it has (docs/player-compatibility.md §6.10): sub-second video of what the screen plays, from the Player through a media relay to the dashboard. A screen has one live session, shared by every viewer.

Its lease runs duration_s from now (30 to 300, default 300) and a start or renewal sets lease_until to the later of its current end and that instant, never past max_until, five minutes after the session began. The session ends by itself at the latest then: nothing renews or restarts it, and a new session needs a new start.

Termina prima quando il lease scade senza rinnovo, con DELETE o quando il Player la termina; il Player smette di pubblicare entro circa 20 secondi dalla fine del lease.

With live_id the request only renews that session: when it is not the screen's live session (it ended, or the screen started another) the answer is 409 live_unavailable naming ended_reason, and no session starts or is extended.

Una nuova sessione aggiunge il comando di runtime per schermo player.live_publish (dettagli live_id, at, expires_at sessanta secondi dopo, max_until; mai consegnato dopo expires_at); un rinnovo lo invia di nuovo solo se il Player non si è mai unito e l’ultimo comando è scaduto.

The screen must be active and online and its host hint must declare the live_view capability: 409 live_unsupported (update the Player, or use a screenshot), 409 live_unavailable (offline), screen_archived. 404 feature_unavailable when the server has no media relay configured. 201 is a new session, 200 a renewed one; both return the LiveSession with a viewer_url that opens the dashboard viewer.

Lo stato requested dura finché il Player non pubblica: interroga GET fino a publisher.connected. La vista live è gratuita ed esente dal contatore API da 1 credito, come uno screenshot.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: LiveStartRequest
ID operazione: startScreenLive

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Campi del corpo della richiesta

Campo	Descrizione
duration_s (opzionale, intero)	Quanto dura il lease da ora, in secondi. Una sessione dura al massimo cinque minuti, qualunque sia il lease. default: 300 minimum: 30 maximum: 300
live_id (opzionale, stringa)	Renew this session only. When it is not the screen's live session, the answer is live_unavailable (the detail names ended_reason) and nothing starts or is extended. Without it, a start begins a session when the screen has none. pattern: "^lv_[a-z2-7]{26}$"

Modello richiesta e risposte

shell · modello richiesta

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/screens/RESOURCE_ID/live'

Risposte

Stato	Significato	Corpo e intestazioni
201	Una nuova sessione live; al Player è stato chiesto di pubblicare.	LiveSession (application/json); intestazioni: Cache-Control, RateLimit-Policy, RateLimit
200	La sessione live dello schermo, rinnovata.	LiveSession (application/json); intestazioni: Cache-Control, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

ELIMINA/api/screens/{id}/live¶

Interrompere la sessione live dello schermo

Ends the screen's live session (ended_reason stopped), appends player.live_stop (details live_id, at, expires_at sixty seconds later), and closes its tracks on the media relay. 204 also when the screen has no live session. A Player that misses the command stops at its next heartbeat. 404 feature_unavailable when the server has no media relay configured.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: stopScreenLive

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
204	Interrotta, oppure non c’era nulla da interrompere.	nessun corpo; intestazioni: Cache-Control
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/live/viewers¶

Creare uno spettatore live dello schermo

Apre uno spettatore della sessione live dello schermo: una nuova sessione del relay media che si sottoscrive al video del Player, e l’offerta WebRTC del relay.

Apply offer with setRemoteDescription on an RTCPeerConnection built with ice_servers (short-lived credentials), create the answer, wait for ICE gathering to complete or two seconds, then PUT the answer to /api/screens/{id}/live/viewers/{viewer_id} within two minutes.

Candidates travel inside the SDP; there is no separate candidate call. 409 live_not_ready while the session is requested, 409 live_unavailable when the screen has no live session or it ended (the detail names ended_reason). 404 feature_unavailable when the server has no media relay configured.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: object
ID operazione: createScreenLiveViewer

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

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/screens/RESOURCE_ID/live/viewers'

Risposte

Stato	Significato	Corpo e intestazioni
201	Uno spettatore e l’offerta del relay.	LiveViewer (application/json); intestazioni: Cache-Control, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PUT/api/screens/{id}/live/viewers/{viewer_id}¶

Rispondere a uno spettatore live dello schermo

Applies the viewer's WebRTC answer to the relay's offer. A viewer answers once, within two minutes of its offer; an unknown, expired, already answered or another screen's viewer_id is 404 not_found. 204 once the relay accepts the answer; media then flows from the relay to the viewer. 404 feature_unavailable when the server has no media relay configured.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: LiveViewerAnswer
ID operazione: answerScreenLiveViewer

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
viewer_id	path	obbligatorio

Campi del corpo della richiesta

Campo	Descrizione
answer (obbligatorio, SessionDescription)

Modello richiesta e risposte

shell · modello richiesta

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/live/viewers/VIEWER_ID'

Risposte

Stato	Significato	Corpo e intestazioni
204	Il relay ha accettato la risposta.	nessun corpo; intestazioni: Cache-Control
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/screens/{id}/live/frames¶

Avviare i frame live dello schermo

Starts JPEG frames of the screen's live session, for an agent that has HTTPS and no WebRTC: the media relay decodes the Player's published video and delivers one JPEG about every second, and GET /api/screens/{id}/live/frame returns the latest.

La sessione deve essere in pubblicazione (409 live_not_ready fino ad allora, 409 live_unavailable quando non ce n’è nessuna o è terminata; avviane una con POST /api/screens/{id}/live).

Frames are started once per session: asking again answers the same adapter's progress, and a Player that reconnects ends its frames, so ask again. state is starting until the first frame arrives, streaming while frames arrive, and silent when the adapter is older than fifteen seconds and none has arrived in that time (last_frame_at, when present, says when frames last came).

The frames end with the session. 404 feature_unavailable when the server has no media relay or no frames origin configured. Live frames are free and exempt from the 1-credit API meter, like a screenshot. They are what the Player's encoder sent, scaled and lossy; they do not replace a screenshot as proof of layout.

Autenticazione: projectBearer
Corpo della richiesta: object
ID operazione: startScreenLiveFrames

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/live/frames'

Risposte

Stato	Significato	Corpo e intestazioni
202	L’adattatore di frame e a che punto è.	LiveFrames (application/json); intestazioni: Cache-Control, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}/live/frame¶

Ottenere il frame live dello schermo

Restituisce l’ultimo frame JPEG della sessione live dello schermo.

Without after it returns the latest frame there is; with after (the ScreenRig-Captured-At of the frame you already have) it returns the first frame captured later, waiting up to five seconds for one, so a loop that passes each answer's ScreenRig-Captured-At back as after receives every new frame once.

ScreenRig-Captured-At indica quando il backend ha ricevuto il frame.

When no new frame comes in time the answer is 409 live_not_ready with Retry-After: 1; 409 resource_conflict answers a session whose frames were not started (POST /api/screens/{id}/live/frames first, and again after the Player reconnects); 409 live_unavailable answers a session that has ended or whose adapter is silent.

Frames are relay-decoded JPEGs of the live stream, at most 1280 by 720: they show what the Player encoded and sent, not a screenshot. They end with the session (max_until at the latest). 404 feature_unavailable when the server has no media relay or no frames origin configured. Free and exempt from the 1-credit API meter.

Autenticazione: projectBearer
Corpo della richiesta: nessuno
ID operazione: getScreenLiveFrame

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
dopo	query	opzionale	Restituisce un frame catturato dopo questo istante (RFC 3339, come in ScreenRig-Captured-At).

Modello richiesta e risposte

shell · modello richiesta

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/live/frame'

Risposte

Stato	Significato	Corpo e intestazioni
200	Il frame.	string (image/jpeg); intestazioni: Content-Type, Content-Length, ETag, Cache-Control, ScreenRig-Live-Id, ScreenRig-Captured-At, ScreenRig-Frame-Width, ScreenRig-Frame-Height, RateLimit-Policy, RateLimit
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
409	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/live/frames¶

Collegare i frame live

The media relay's frame adapter connects here with a WebSocket upgrade; no client, agent or Player calls it. The token is the credential: POST /api/screens/{id}/live/frames hands it to the relay inside the adapter's endpoint and stores only its SHA-256.

Each binary message the relay sends is one protobuf Packet (field 1 sequenceNumber, field 2 timestamp, field 5 payload) whose payload is one whole JPEG of at most 2 MiB; anything else is skipped. The backend keeps the latest frame for fifteen seconds. One connection per token: a newer one replaces the older.

The connection is closed with 1000 when the live session ends, and a token of an ended session is refused with 401 before the upgrade. 404 feature_unavailable when the server has no frames origin configured.

Autenticazione: nessuno
Corpo della richiesta: nessuno
ID operazione: connectLiveFrames

Parametri

Nome	Invia	Obbligatorio?	Descrizione
token	query	obbligatorio	Il token dell’adattatore, 43 caratteri.

Modello richiesta e risposte

shell · modello richiesta

curl --request GET 'https://api.screenrig.ai/live/frames?token=TOKEN'

Risposte

Stato	Significato	Corpo e intestazioni
101	Passaggio del protocollo a WebSocket.	nessun corpo
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}/health/history¶

Ottieni cronologia salute schermo

La salute di uno schermo segnalata nel tempo. resolution=raw (predefinito) restituisce ogni rapporto accettato in ordine temporale, modellato come Screen.health senza stale; resolution=hour restituisce un riepilogo per ogni ora UTC (rapporti, temperatura massima e media, carico massimo e rapporto memoria, segnale Wi-Fi più debole, se il monitor è stato disconnesso, conteggi massimi di crash e riavvii del renderer). from (inclusivo) e to (esclusivo) predefiniti alle ultime 24 ore; l’intervallo massimo è di 31 giorni per raw e 93 giorni per hour.

Una pagina contiene al massimo limit righe (default 100, massimo 500) con next_cursor, null alla fine. La cronologia si conserva per la retention eventi del piano. I report grezzi arrivano a questa vista in pochi secondi, i riepiloghi orari in circa 5 minuti. Uno schermo di un altro progetto è not_found. Screen.health, l’ultimo report, resta invariato.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getScreenHealthHistory

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
formato	query	opzionale	json (predefinito) restituisce il report come JSON. csv, xlsx e pdf restituiscono le stesse righe come allegato (ogni pagina di un report a pagine, fino a 50000 righe).
da	query	opzionale	Limite inferiore inclusivo sull’ora del report. Predefinito a 24 ore prima di to.
a	query	opzionale	Limite superiore esclusivo sull’ora del report. Predefinito ora.
risoluzione	query	opzionale	raw restituisce ogni report; hour restituisce un riepilogo per ogni ora UTC.
limite	query	opzionale	Dimensione pagina.
cursore	query	opzionale	next_cursor della pagina precedente, con gli stessi filtri. Opaco.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Una pagina di report o riepiloghi orari.	ScreenHealthHistory (application/json); intestazioni: Cache-Control
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}/uptime¶

Ottieni uptime schermo

Disponibilità giornaliera di uno schermo su giorni UTC inclusivi (day_to predefinito a oggi e day_from a 29 giorni prima, massimo 366 giorni). Ogni riga contiene i secondi online e offline registrati quel giorno, disponibilità (online sul tempo registrato, null se nulla registrato) e copertura (quota del giorno con stato registrato).

Il tempo senza stato registrato non è mai contato come inattività: abbassa solo la copertura. L’intervallo aperto corrente dello schermo è incluso fino ad ora e segna i suoi giorni come attivi. I giorni senza registrazioni non hanno riga. Offline è registrato dopo che lo schermo è stato irraggiungibile per 60 secondi. Uno schermo di un altro progetto è not_found.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getScreenUptime

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
formato	query	opzionale	json (predefinito) restituisce il report come JSON. csv, xlsx e pdf restituiscono le stesse righe come allegato (ogni pagina di un report a pagine, fino a 50000 righe).
day_from	query	opzionale	Primo giorno UTC, incluso. Predefinito a 29 giorni prima di day_to. Con day_to copre al massimo 366 giorni.
day_to	query	opzionale	Ultimo giorno UTC, incluso. Predefinito a oggi (UTC).

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Righe di uptime giornaliere, le più vecchie per prime.	ScreenUptime (application/json); intestazioni: Cache-Control
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/screens/{id}/presence¶

Ottieni presenza schermo

Le transizioni online e offline dello schermo, dalla più recente, dai suoi eventi screen.online e screen.offline qualunque sia la corsia di log. since (inclusivo) e until (esclusivo) delimitano il tempo dell’evento; until predefinito a ora e since a 30 giorni prima, massimo 366 giorni. Le transizioni sono conservate per la retention eventi del piano.

Una pagina contiene al massimo limit transizioni (default 100, massimo 500) con next_cursor, null alla fine; restituirlo come prima. Una transizione offline rilevata solo al ricollegamento dello schermo porta detected_on_reconnect, e il suo at è quando è scaduto il lease di presenza. Offline si registra dopo 60 secondi di irreperibilità dello schermo.

Uno schermo di un altro progetto è not_found.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getScreenPresence

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
da	query	opzionale	Limite inferiore inclusivo sull’ora dell’evento di transizione. Predefinito a 30 giorni prima di until.
fino a	query	opzionale	Limite superiore esclusivo sull’ora evento transizione. Predefinito ora. until - since è al massimo 366 giorni.
limite	query	opzionale	Dimensione pagina. Un valore fuori da 1-500 è rifiutato con invalid_request che nomina limit.
before	query	opzionale	next_cursor della pagina precedente, con lo stesso since e until.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Transizioni di presenza, le più recenti per prime.	ScreenPresenceHistory (application/json); intestazioni: Cache-Control
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/health/trend¶

Ottieni Health Trend

La salute della flotta del progetto per ora UTC: quanti schermi hanno segnalato, e quanti di essi erano caldi (a 80 °C o più), avevano un display disconnesso o andavano in crash (3 o più crash in 24 ore). from (inclusivo) e to (esclusivo) di default sono le ultime 24 ore, massimo 93 giorni; una pagina contiene al massimo limit righe (default 100, massimo 500) con next_cursor, nullo alla fine.

Le ore seguono i report con un ritardo fino a circa 5 minuti. Rifiutato a un chiamante limitato agli schermi (outside_screen_scope); GET /api/screens/{id}/health/history è la forma per singolo schermo.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getHealthTrend

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
formato	query	opzionale	json (predefinito) restituisce il report come JSON. csv, xlsx e pdf restituiscono le stesse righe come allegato (ogni pagina di un report a pagine, fino a 50000 righe).
da	query	opzionale	Limite inferiore inclusivo sull’ora del report. Predefinito a 24 ore prima di to.
a	query	opzionale	Limite superiore esclusivo sull’ora del report. Predefinito ora.
limite	query	opzionale	Dimensione pagina.
cursore	query	opzionale	next_cursor della pagina precedente, con gli stessi filtri. Opaco.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Una pagina della salute oraria della flotta.	HealthTrend (application/json); intestazioni: Cache-Control
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/uptime/daily¶

Ottieni uptime progetto

Disponibilità giornaliera degli schermi del progetto su giorni UTC inclusivi (predefiniti e intervallo come GET /api/screens/{id}/uptime). Ogni riga somma i secondi online e offline degli schermi con stato registrato quel giorno; la copertura è la quota del giorno di quegli schermi con stato registrato.

Gli intervalli vengono contati quando terminano, quindi la riga di oggi copre gli intervalli terminati finora; il conteggio online live è nel riepilogo del dashboard. Rifiutato a un chiamante limitato agli schermi (outside_screen_scope); GET /api/screens/{id}/uptime è la forma per singolo schermo.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getProjectUptime

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
formato	query	opzionale	json (predefinito) restituisce il report come JSON. csv, xlsx e pdf restituiscono le stesse righe come allegato (ogni pagina di un report a pagine, fino a 50000 righe).
day_from	query	opzionale	Primo giorno UTC, incluso. Predefinito a 29 giorni prima di day_to. Con day_to copre al massimo 366 giorni.
day_to	query	opzionale	Ultimo giorno UTC, incluso. Predefinito a oggi (UTC).

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Righe di uptime giornaliere, le più vecchie per prime.	ProjectUptime (application/json); intestazioni: Cache-Control
400	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
401	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
403	outside_screen_scope - il chiamante è limitato agli schermi e lo schermo, la cartella di schermi, il selettore o il pubblico che la richiesta nomina o raggiunge è fuori da essi (docs/screen-scope.md). Un id fuori dall’ambito e un id che non esiste ricevono la stessa risposta; errors[0].screen_scope riporta l’ambito del chiamante, e la scrittura viene rifiutata per intero, mai ridotta.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/fleet-links¶

Elenca link flotta

Elenca i link della flotta del progetto, dal più vecchio al più recente (al massimo 50). Sotto Gestisci effettivo ogni URL è vuoto e url_redacted è true, poiché l’URL crea schermi.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: listFleetLinks

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	I fleet link del progetto.	FleetLinkList (application/json); intestazioni: Cache-Control
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/fleet-links¶

Crea collegamento flotta

Crea un link fleet: un URL Player (https://play.<domain>/player/#fleet=<secret>) che trasforma ogni dispositivo che lo apre nel proprio schermo in questo progetto, senza codice di associazione. Inseriscilo in un gestore dispositivi, come un’app kiosk Google Admin console.

Ogni nuovo schermo riceve i tag, i campi e la playlist del link, e un’etichetta dal dispositivo (prima l’ID asset dell’amministratore, poi la posizione), altrimenti la prossima etichetta predefinita. Un lettore che già possiede uno schermo non ne crea un altro: la sua chiave resta l’identità dello schermo tra ricariche e riavvii.

Dopo un powerwash o una reinstallazione, un dispositivo che segnala il numero di serie o il DUID di uno schermo creato da un link flotta di questo progetto recupera quello schermo (screen.recovered) invece di crearne uno nuovo, una volta che la vecchia chiave è stata silente per dieci minuti.

Il segreto viaggia nel frammento URL, che i browser non inviano mai al server. max_screens limita gli schermi che il link crea ed expires_at termina il link in quel momento, come fa la sua disattivazione. Un’organizzazione ha al massimo 50 link di flotta in tutti i suoi progetti (fleet_link_limit_reached). Aggiunge fleet_link.created.

Un retry esatto con la stessa Idempotency-Key restituisce questa stessa risposta per ventiquattro ore.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: FleetLinkWrite
ID operazione: createFleetLink

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
label (obbligatorio, stringa)	minLength: 1 maxLength: 80
abilitato (opzionale, booleano)	Predefinito a true.
tag (opzionale, ScreenTags)	Tag selettore flotta, da 0 a 16 tag unici esatti, ciascuno conforme alla grammatica dei tag media. Su ScreenPatch l’array sostituisce l’intero set e un array vuoto lo cancella; un tag duplicato o malformato è invalid_request. Cambiare i tag aggiorna la revisione dello schermo (protetta da If-Match) e aggiunge screen.updated con details.tags; non modifica mai la revisione del manifesto. I tag non sono mai nel manifesto di runtime e mai nell’autorizzazione.
fields (opzionale, oggetto)	Campi con cui parte ogni schermo creato dal link; i posizionamenti delle card li leggono tramite {screen.field.NAME}.
playlist_id (opzionale, stringa)
max_screens (opzionale, intero)	minimo: 1 massimo: 10000
expires_at (opzionale, stringa)	Quando il link scade (RFC 3339); un link oltre tale momento non crea né recupera schermi. Se assente, non scade mai. Un orario già trascorso viene accettato e fa scadere subito il link. format: "date-time"

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
201	Creato, con il suo URL.	FleetLink (application/json); intestazioni: Cache-Control
400	invalid_request, incluso un playlist_id sconosciuto o un tag o campo malformato.	Problema (application/problem+json)
409	fleet_link_limit_reached o idempotency_mismatch.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/fleet-links/{id}¶

Ottieni Fleet Link

Un link di flotta. Sotto, l’url Manage effettivo è vuoto e url_redacted è true.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getFleetLink

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Un link di flotta.	FleetLink (application/json); intestazioni: ETag, Cache-Control
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PATCH/api/fleet-links/{id}¶

Aggiorna collegamento flotta

Modifica uno qualsiasi di label, enabled, tags, fields, playlist_id, max_screens e expires_at; null cancella fields, playlist_id, max_screens o expires_at. Un link disabilitato o scaduto non crea né recupera schermi; un dispositivo che lo apre mostra invece il codice di associazione. Le modifiche si applicano agli schermi che il link crea da ora in poi, mai a quelli già creati.

Aggiunge fleet_link.updated. If-Match protegge la revisione.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: FleetLinkPatch
ID operazione: updateFleetLink

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
label (opzionale, stringa)	minLength: 1 maxLength: 80
abilitato (opzionale, booleano)
tag (opzionale, ScreenTags)	Tag selettore flotta, da 0 a 16 tag unici esatti, ciascuno conforme alla grammatica dei tag media. Su ScreenPatch l’array sostituisce l’intero set e un array vuoto lo cancella; un tag duplicato o malformato è invalid_request. Cambiare i tag aggiorna la revisione dello schermo (protetta da If-Match) e aggiunge screen.updated con details.tags; non modifica mai la revisione del manifesto. I tag non sono mai nel manifesto di runtime e mai nell’autorizzazione.
fields (opzionale, oggetto)	sostituisce l’intero preset; {} o null lo cancella.
playlist_id (opzionale, stringa)	null cancella la playlist.
max_screens (opzionale, intero)	null rimuove il limite. minimo: 1 massimo: 10000
expires_at (opzionale, stringa)	null rimuove la scadenza. format: "date-time"

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
200	Collegamento flotta aggiornato.	FleetLink (application/json); intestazioni: ETag
400	invalid_request.	Problema (application/problem+json)
412	revision_conflict — If-Match è obsoleto; current_revision dell’errore riporta la revisione corrente.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

ELIMINA/api/fleet-links/{id}¶

Elimina link flotta

Elimina il link flotta. Il suo URL smette di funzionare immediatamente; gli schermi creati restano, con le loro playlist, tag e campi. Aggiunge fleet_link.deleted. If-Match protegge la revisione.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: deleteFleetLink

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

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

Risposte

Stato	Significato	Corpo e intestazioni
204	Eliminato.	nessun corpo
412	revision_conflict.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/fleet-links/{id}/rotate¶

Ruota Fleet Link

Sostituisce il segreto del link e restituisce la nuova URL. La vecchia URL smette di funzionare subito; gli schermi già creati continuano a riprodurre, poiché un Player associato non presenta mai più il link. Aggiunge fleet_link.updated con details.rotated true. If-Match protegge la revisione.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: rotateFleetLink

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/fleet-links/RESOURCE_ID/rotate'

Risposte

Stato	Significato	Corpo e intestazioni
200	Il link della flotta con il suo nuovo url.	FleetLink (application/json); intestazioni: ETag, Cache-Control
412	revision_conflict.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)