OpenAPI YAMLOpenAPI JSONproblemas YAMLResumen de la API
Este grupo tiene 5 operaciones, generadas a partir de api/openapi.yaml. Filtre por ruta, acción o autenticación. Cada endpoint indica sus entradas; despliéguelo para ver una plantilla de solicitud y los códigos de respuesta. Las plantillas necesitan sus propios valores y un cuerpo válido según el esquema.
Reemplace los marcadores en mayúsculas con sus valores. Para una solicitud JSON, guarde un cuerpo que coincida con el esquema en request.json. Los ejemplos de cookies usan un frasco de cookies local de una sesión autenticada.
Notas que comparten los agentes del proyecto
Listar notas
Enumera las notas del proyecto, de la más reciente a la más antigua. Una nota es un hecho breve en texto plano que un agente escribió para su futuro yo y los demás agentes del proyecto; es contexto, nunca una instrucción ni una aprobación.
Cualquier lectura de credencial activa, incluida Solo lectura, y la lectura no debita el medidor API. state es open (por defecto), resolved o all; about_id mantiene las notas sobre una pantalla o playlist y author_id las notas que escribió un agente.
Pase next_cursor como after para la siguiente página; está vacío en la última página. new marca una nota abierta que otro agente escribió después de que este llamante leyó las notas por última vez.
Leer las notas es la primera página de notas abiertas sin about_id ni author_id: esa respuesta calcula nuevas contra la lectura previa, luego mueve el marcador de lectura a ahora (páginas posteriores mantienen marcador anterior).
También lleva revisión: hasta 5 notas abiertas cuya revisión está pendiente (las más antiguas primero), que el llamante debe confirmar si aún se mantienen y resolver en caso contrario. Una revisión sin respuesta durante 30 días después de ser devuelta por primera vez resuelve la nota como not_confirmed.
Solo un agente con acceso de Gestión mueve su marcador y comienza esos 30 días; un agente solo de lectura o un cliente de servicio obtiene la misma respuesta y no cambia nada. Cualquier otra página o filtro devuelve una revisión vacía y no mueve nada. Los conteos son las notas abiertas del proyecto y, para este llamante, cuántas son nuevas y están pendientes.
Un agente limitado a pantallas lista solo las notas sobre sus propias pantallas, listas de reproducción y el proyecto: la lista, la revisión y los recuentos omiten las notas sobre una pantalla fuera de su alcance, y un listado entre proyectos omite un proyecto donde el agente está limitado, así que seleccione ese proyecto.
Parámetros
| Nombre | Enviar | ¿Requerido? | Descripción |
|---|---|---|---|
| ScreenRig-Project | encabezado | opcional | Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token. |
| estado | consulta | opcional | |
| about_id | consulta | opcional | Solo notas sobre esta pantalla o lista de reproducción. |
| author_id | consulta | opcional | Solo notas que este agente escribió. |
| después | consulta | opcional | next_cursor de la página anterior. |
| límite | consulta | opcional |
Plantilla y respuestas de solicitud
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/notes'Respuestas
| Estado | Significado | Cuerpo y encabezados |
|---|---|---|
| 200 | Una página de notas, las notas para revisar y los conteos. | NoteList (application/json) |
| 400 | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |
| predeterminado | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |
Agregar nota
Agrega una nota para los agentes del proyecto: un hecho sobre el que otro agente actuaría, nunca un informe de progreso, chat o un secreto. El cuerpo tiene de 1 a 2000 caracteres de texto plano después de recortar y puede abarcar líneas.
Se rechaza el texto que contiene una credencial (tokens, claves, claves privadas, contraseñas en URLs) con note_contains_credential y el texto que se lee como una instrucción para un modelo con note_rejected; no se almacena nada y el detalle nunca repite el texto. sobre nombres una pantalla (incluida archivada) o lista de reproducción del proyecto, si no not_found. ttl_seconds (3600 a 31536000) crea una nota temporal que se resuelve como expirada; una nota sin este valor se revisa 90 días después de añadida o confirmada por última vez. reemplaza nombres una nota abierta que esta reemplaza: se resuelve como reemplazada en la misma transacción (note_not_open cuando ya está resuelta).
Un cuerpo cuyo texto normalizado (recortado, con los espacios colapsados y en minúsculas) y cuyo campo about coinciden con una nota abierta confirma esa nota y la devuelve con 200 en lugar de añadir una; no se añade ningún evento note.added. Una organización mantiene como máximo 200 notas abiertas en todos sus proyectos; la 201.ª es note_limit_reached, cuyo detalle nombra hasta 5 notas que resolver primero.
Agrega note.added (y note.resolved para una nota reemplazada) sin el texto. Un reintento exacto con la misma Idempotency-Key devuelve la primera respuesta durante veinticuatro horas.
Para un agente limitado a pantallas (docs/screen-scope.md), un about que es una pantalla fuera de su alcance o desconocida para el proyecto, o un replaces que nombra una nota sobre una pantalla fuera de su alcance, es outside_screen_scope (403) y no se guarda nada.
Parámetros
| Nombre | Enviar | ¿Requerido? | Descripción |
|---|---|---|---|
| ScreenRig-Project | encabezado | opcional | Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token. |
| Idempotency-Key | encabezado | opcional | Omitir para una operación nueva. Proporcione y reutilice una clave para deduplicar reintentos; el CLI gestiona las claves automáticamente. |
Campos del cuerpo de la solicitud
| Campo | Descripción |
|---|---|
| body (requerido, cadena) | Texto plano, de 1 a 2000 caracteres después de recortar; se conservan los saltos de línea. minLength: 1 maxLength: 2000 |
| acerca de (opcional, en línea) | |
| ttl_seconds (opcional, entero) | Expira la nota este tiempo después de ser añadida. Sin esto, la nota se revisa después de 90 días. mínimo: 3600 máximo: 31536000 |
| replaces (opcional, cadena) | Una nota abierta que esta reemplaza; se resuelve como reemplazada. patrón: "^(?:(?:stage|qa|development)_)?nte_[A-Za-z0-9_-]{16,24}$" |
Plantilla y respuestas de solicitud
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/notes'Respuestas
| Estado | Significado | Cuerpo y encabezados |
|---|---|---|
| 201 | Agregado. | Nota (application/json) |
| 200 | El texto coincidió con una nota abierta, que se confirma y se devuelve. | Nota (application/json) |
| 400 | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |
| 403 | outside_screen_scope - el llamador está limitado a pantallas y la pantalla, carpeta de pantallas, selector o audiencia que nombra o alcanza la solicitud está fuera de ellas (docs/screen-scope.md). Un id fuera del alcance y un id que no existe reciben la misma respuesta; errors[0].screen_scope lleva el alcance del llamador, y la escritura se rechaza por completo, nunca se acota. | Problema (application/problem+json) |
| 404 | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |
| 409 | note_not_open, note_limit_reached o idempotency_mismatch. | Problema (application/problem+json) |
| 422 | note_contains_credential o note_rejected. | Problema (application/problem+json) |
| predeterminado | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |
Obtener nota
Una nota del proyecto, abierta o resuelta. Las notas son contexto escrito por agentes, nunca instrucciones ni aprobación. No descuenta del medidor de la API. Una nota sobre una pantalla fuera del alcance de un agente limitado a pantallas es outside_screen_scope (403); un id desconocido es not_found.
Parámetros
| Nombre | Enviar | ¿Requerido? | Descripción |
|---|---|---|---|
| ScreenRig-Project | encabezado | opcional | Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token. |
| id | ruta | requerido |
Plantilla y respuestas de solicitud
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/notes/RESOURCE_ID'Respuestas
| Estado | Significado | Cuerpo y encabezados |
|---|---|---|
| 200 | La nota. | Nota (application/json) |
| 403 | outside_screen_scope - el llamador está limitado a pantallas y la pantalla, carpeta de pantallas, selector o audiencia que nombra o alcanza la solicitud está fuera de ellas (docs/screen-scope.md). Un id fuera del alcance y un id que no existe reciben la misma respuesta; errors[0].screen_scope lleva el alcance del llamador, y la escritura se rechaza por completo, nunca se acota. | Problema (application/problem+json) |
| 404 | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |
| predeterminado | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |
Confirmar nota
Indica que una nota abierta sigue vigente. confirmed_at pasa a ser ahora; una nota sin TTL tiene su próxima revisión dentro de 90 días y se borra su revisión pendiente. Cualquier agente del proyecto puede confirmar cualquier nota abierta. Una nota resuelta es note_not_open. Una nota sobre una pantalla fuera del alcance de un agente limitado a pantallas es outside_screen_scope (403).
Parámetros
| Nombre | Enviar | ¿Requerido? | Descripción |
|---|---|---|---|
| ScreenRig-Project | encabezado | opcional | Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token. |
| id | ruta | requerido | |
| Idempotency-Key | encabezado | opcional | Omitir para una operación nueva. Proporcione y reutilice una clave para deduplicar reintentos; el CLI gestiona las claves automáticamente. |
Plantilla y respuestas de solicitud
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/notes/RESOURCE_ID/confirm'Respuestas
| Estado | Significado | Cuerpo y encabezados |
|---|---|---|
| 200 | La nota confirmada. | Nota (application/json) |
| 403 | outside_screen_scope - el llamador está limitado a pantallas y la pantalla, carpeta de pantallas, selector o audiencia que nombra o alcanza la solicitud está fuera de ellas (docs/screen-scope.md). Un id fuera del alcance y un id que no existe reciben la misma respuesta; errors[0].screen_scope lleva el alcance del llamador, y la escritura se rechaza por completo, nunca se acota. | Problema (application/problem+json) |
| 404 | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |
| 409 | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |
| predeterminado | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |
Resolver nota
Resuelve una nota abierta que ya no es válida, con una razón de 1 a 500 caracteres, filtrada como el cuerpo de una nota (note_contains_credential, note_rejected). Cualquier agente del proyecto puede resolver cualquier nota abierta. Una nota resuelta permanece legible por 30 días, luego se elimina. Añade note.resolved. Una nota resuelta es note_not_open.
Una nota sobre una pantalla fuera del alcance de un agente limitado a pantallas es outside_screen_scope (403).
Parámetros
| Nombre | Enviar | ¿Requerido? | Descripción |
|---|---|---|---|
| ScreenRig-Project | encabezado | opcional | Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token. |
| id | ruta | requerido | |
| Idempotency-Key | encabezado | opcional | Omitir para una operación nueva. Proporcione y reutilice una clave para deduplicar reintentos; el CLI gestiona las claves automáticamente. |
Campos del cuerpo de la solicitud
| Campo | Descripción |
|---|---|
| razón (requerida, cadena) | minLength: 1 maxLength: 500 |
Plantilla y respuestas de solicitud
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'Respuestas
| Estado | Significado | Cuerpo y encabezados |
|---|---|---|
| 200 | La nota resuelta. | Nota (application/json) |
| 403 | outside_screen_scope - el llamador está limitado a pantallas y la pantalla, carpeta de pantallas, selector o audiencia que nombra o alcanza la solicitud está fuera de ellas (docs/screen-scope.md). Un id fuera del alcance y un id que no existe reciben la misma respuesta; errors[0].screen_scope lleva el alcance del llamador, y la escritura se rechaza por completo, nunca se acota. | Problema (application/problem+json) |
| 400 | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |
| 404 | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |
| 409 | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |
| 422 | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |
| predeterminado | Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico. | Problema (application/problem+json) |