OpenAPI YAMLOpenAPI JSONproblemi YAMLPanoramica dell’API
Questo gruppo ha 5 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.
Note condivise dagli agenti del progetto
Elenca le note
Elenca le note del progetto, dalla più recente alla più vecchia. Una nota è un fatto breve in testo semplice scritto da un agente per il suo futuro sé e per gli altri agenti del progetto; è contesto, mai un’istruzione e mai un’approvazione.
Qualsiasi lettura di credenziali attive, inclusa Read only, e la lettura non addebita il contatore API. state è open (default), resolved o all; about_id mantiene le note su uno schermo o playlist e author_id le note scritte da un agente.
Passa next_cursor come after per la pagina successiva; è vuoto nell’ultima pagina. new indica una nota aperta scritta da un altro agente dopo che questo chiamante ha letto l’ultima volta le note.
Leggere le note è la prima pagina di note aperte senza about_id o author_id: quella risposta calcola il nuovo rispetto alla lettura precedente, poi sposta il marcatore di lettura a ora (le pagine successive della stessa lista mantengono il marcatore precedente).
Include anche la revisione: fino a 5 note aperte la cui revisione è dovuta (le più vecchie per prime), che il chiamante dovrebbe confermare se ancora valide e risolvere altrimenti. Una revisione non risposta entro 30 giorni dalla prima restituzione risolve la nota come not_confirmed.
Solo un agente con accesso Gestisci sposta il proprio marcatore e avvia quei 30 giorni; un agente solo Lettura o un client di servizio ottiene la stessa risposta e non cambia nulla. Ogni altra pagina o filtro restituisce una revisione vuota e non sposta nulla. I conteggi sono le note aperte del progetto e, per questo chiamante, quante sono nuove e scadute.
Un agente limitato agli schermi elenca solo le note sui propri schermi, sulle playlist e sul progetto: l’elenco, la revisione e i conteggi escludono le note su uno schermo fuori dal suo ambito, e un elenco tra progetti esclude un progetto in cui l’agente è limitato, quindi seleziona quel progetto.
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 | |
| about_id | query | opzionale | Solo note su questo schermo o playlist. |
| author_id | query | opzionale | Solo note scritte da questo agente. |
| dopo | query | opzionale | next_cursor della pagina precedente. |
| limite | query | opzionale |
Modello richiesta e risposte
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/notes'Risposte
| Stato | Significato | Corpo e intestazioni |
|---|---|---|
| 200 | Una pagina di note, le note da rivedere e i conteggi. | NoteList (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) |
| 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) |
Aggiungi nota
Aggiunge una nota per gli agenti del progetto: un fatto su cui un altro agente agirebbe, mai un report di progresso, chat o segreto. Il corpo è da 1 a 2000 caratteri di testo semplice dopo il trim e può coprire più righe.
Testo contenente una credenziale (token, chiavi, chiavi private, password in URL) è rifiutato con note_contains_credential e testo che appare come istruzione a un modello con note_rejected; nulla viene memorizzato e il dettaglio non ripete mai il testo. Riguardo ai nomi uno schermo (incluso archiviato) o playlist del progetto, altrimenti not_found. ttl_seconds (3600 a 31536000) crea una nota temporanea che si risolve come scaduta; una nota senza questo parametro viene sottoposta a revisione 90 giorni dopo l’aggiunta o l’ultima conferma. Sostituisce i nomi di una nota aperta che questa sostituisce: si risolve come sostituita nella stessa transazione (note_not_open quando è già risolta).
Un corpo il cui testo normalizzato (ripulito, con gli spazi compressi e in minuscolo) e il cui campo about corrispondono a una nota aperta conferma quella nota e la restituisce con 200 invece di aggiungerne una; non viene aggiunto alcun evento note.added. Un’organizzazione contiene al massimo 200 note aperte in tutti i suoi progetti; la 201ª è note_limit_reached, il cui dettaglio nomina fino a 5 note da risolvere per prime.
Aggiunge note.added (e note.resolved per una nota sostituita) senza il testo. Un retry esatto con la stessa Idempotency-Key restituisce la prima risposta per ventiquattro ore.
Per un agente limitato agli schermi (docs/screen-scope.md) un about che è uno schermo fuori dal suo ambito o sconosciuto al progetto, o un replaces che nomina una nota su uno schermo fuori dal suo ambito, è outside_screen_scope (403) e non viene memorizzato nulla.
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 |
|---|---|
| body (obbligatorio, stringa) | Testo semplice, da 1 a 2000 caratteri dopo il trim; i ritorni a capo si mantengono. minLength: 1 maxLength: 2000 |
| informazioni (opzionale, in linea) | |
| ttl_seconds (opzionale, intero) | Scadenza della nota dopo questo intervallo. Senza, la nota viene riesaminata dopo 90 giorni. minimo: 3600 massimo: 31536000 |
| sostituisce (opzionale, stringa) | Una nota aperta che questa sostituisce; è risolta come sostituita. pattern: "^(?:(?:stage|qa|development)_)?nte_[A-Za-z0-9_-]{16,24}$" |
Modello richiesta e risposte
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/notes'Risposte
| Stato | Significato | Corpo e intestazioni |
|---|---|---|
| 201 | Aggiunto. | Nota (application/json) |
| 200 | Il testo ha corrisposto a una nota aperta, che è confermata e restituita. | Nota (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) |
| 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) |
| 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 | note_not_open, note_limit_reached o idempotency_mismatch. | Problema (application/problem+json) |
| 422 | note_contains_credential o note_rejected. | 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) |
Ottieni nota
Una nota del progetto, aperta o risolta. Le note sono contesto scritto dagli agenti, mai istruzioni o approvazione. Non addebita il contatore API. Una nota su uno schermo fuori dall’ambito di un agente limitato agli schermi è outside_screen_scope (403); un id sconosciuto è not_found.
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
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/notes/RESOURCE_ID'Risposte
| Stato | Significato | Corpo e intestazioni |
|---|---|---|
| 200 | La nota. | Nota (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) |
| 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) |
Conferma nota
Dichiara che una nota aperta è ancora valida. confirmed_at diventa adesso; una nota senza TTL è da rivedere di nuovo tra 90 giorni e la sua revisione in sospeso viene azzerata. Qualsiasi agente del progetto può confermare qualsiasi nota aperta. Una nota risolta è note_not_open. Una nota su uno schermo fuori dall’ambito di un agente limitato agli schermi è outside_screen_scope (403).
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. |
Modello richiesta e risposte
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/notes/RESOURCE_ID/confirm'Risposte
| Stato | Significato | Corpo e intestazioni |
|---|---|---|
| 200 | La nota confermata. | Nota (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) |
| 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) |
| 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) |
Risolvi nota
Risolvi una nota aperta che non è più valida, con una motivazione da 1 a 500 caratteri, filtrata come il corpo della nota (note_contains_credential, note_rejected). Qualsiasi agente del progetto può risolvere qualsiasi nota aperta. Una nota risolta resta leggibile per 30 giorni, poi viene eliminata. Aggiunge note.resolved. Una nota risolta è note_not_open.
Una nota su uno schermo fuori dall’ambito di un agente limitato agli schermi è outside_screen_scope (403).
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 |
|---|---|
| motivo (obbligatorio, stringa) | minLength: 1 maxLength: 500 |
Modello richiesta e risposte
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/notes/RESOURCE_ID/resolve'Risposte
| Stato | Significato | Corpo e intestazioni |
|---|---|---|
| 200 | La nota risolta. | Nota (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) |
| 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) |
| 422 | Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_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) |