API HTTP

Todos los endpoints del daemon de Agora, con autenticación, cuerpos de las solicitudes y errores.

El daemon sirve una API JSON bajo /v1 en 127.0.0.1:7788, además del dashboard en /.

Convenciones

Auth: Authorization: Bearer <token> en todos los endpoints salvo GET /v1/health. Los endpoints de streaming también aceptan ?token=. Mirá tokens.
Actuar como un cursor: con el token de admin, mandá X-Agora-Cursor: <cursor id> para actuar como ese cursor.
self: en /v1/cursors/{id}/..., un token de cursor puede usar self como id.
Errores: {"error": "..."} con 400 (solicitud inválida), 401 (token faltante o inválido), 403 (no permitido), 404 (no encontrado), 409 (superficie bloqueada; el cuerpo incluye el lock) o 504 (timeout).
Duraciones: en la configuración del workspace son strings como "10m" o números de segundos.

Sistema

Método y ruta	Descripción
`GET /v1/health`	Liveness, sin auth.
`GET /v1/system`	Versión, uptime, recursos del daemon, memoria y CPU por workspace.
`GET /v1/me`	`{admin, cursor}` del token que hace la llamada.
`POST /v1/viewer-tokens`	Admin. `{workspace, control, ttl_seconds}` → `{token, expires_in}`. El TTL es 3600 por defecto, 86400 como máximo.

Workspaces

Método y ruta	Descripción
`POST /v1/workspaces`	Admin o permiso `workspace`. `{name, config, start, labels}` → `201` workspace. Mirá configuración.
`GET /v1/workspaces`	Workspaces visibles para el token, con estado, recursos, viewers y cursores.
`GET /v1/workspaces/{id}`	Un workspace. `?detail=1` refresca primero el uso detallado.
`DELETE /v1/workspaces/{id}`	Admin. Lo destruye. `?purge=1` además borra su home, checkpoints, eventos y su perfil (salvo que otro workspace lo comparta).
`POST /v1/workspaces/{id}/{op}`	Operaciones de ciclo de vida y control, más abajo.

Operaciones

POST /v1/workspaces/{id}/{op} con un cuerpo JSON opcional:

`op`	Cuerpo	Descripción
`start`		Arranca el display.
`suspend`	`reason`	Hace un checkpoint, cierra el navegador y libera todo. Necesita `workspace`.
`resume`		Reconstruye y devuelve las pestañas a sus dueños.
`freeze`		Detiene todos los procesos y conserva la RAM. Necesita `workspace`.
`thaw`		Continúa un workspace congelado.
`checkpoint`	`reason`, `snapshot`	Registra el estado; `snapshot: true` también copia el perfil.
`fork`	`name`	Workspace nuevo con una copia del perfil y del home. Necesita `workspace`.
`resize`	`width`, `height`	Cambia el tamaño de la pantalla.
`layout`	`layout`	`tile`, `max` o `float`.
`clipboard`	`text`	Setea el portapapeles; devuelve `{text}`.
`browser-restart`		Reinicia Chromium.
`request-human`	`reason`	Marca al cursor que llama como `needs_human` y emite `human.requested`.
`control-take`		Lock con prioridad humana sobre todo el workspace. Necesita `workspace`.
`control-return`		Lo libera; emite `control.returned`. Necesita `workspace`.
`acquire`	`surface`, `ttl_ms`, `reason`	Bloquea `win:<id>` o `tab:<target>` para el cursor que llama.
`release`	`surface`	Libera un lock.
`usage`		Memoria y CPU detalladas por proceso.

Escritorio

Método y ruta	Descripción
`GET /v1/workspaces/{id}/windows`	Ventanas de nivel superior: id, título, clase, geometría.
`POST /v1/workspaces/{id}/windows/{win}`	`{action, x, y, width, height}` con `raise`, `move`, `resize`, `release` (vuelve al layout) o `close`.
`GET /v1/workspaces/{id}/screenshot`	Imagen. Query: `window`, `x`, `y`, `w`, `h`, `format` (`jpeg` o `png`), `quality`, `max_width`. El header `X-Agora-Shot` trae un id para `/v1/shots/{sid}`.
`GET /v1/shots/{sid}`	Una captura guardada.
`POST /v1/workspaces/{id}/input`	Input en el puesto propio de quien llama, más abajo.
`POST /v1/workspaces/{id}/apps`	Necesita `process`. `{command, args, restore}` → `201` proceso. Corre como el usuario de apps con `DISPLAY` seteado.
`GET /v1/workspaces/{id}/processes`	Procesos iniciados en el workspace.
`DELETE /v1/workspaces/{id}/processes/{pid}`	Mata uno.
`GET /v1/workspaces/{id}/clipboard`	`{text}`.
`GET /v1/workspaces/{id}/locks`	Locks de superficie actuales.
`GET /v1/workspaces/{id}/board`	Tablero compartido: claims y posts después de `?since=<seq>` (`limit`).
`POST /v1/workspaces/{id}/board`	`{kind, topic, text}` → `201` post. `kind` es `claim`, `done`, `release`, `finding` o `note`. Un claim falla mientras otro cursor vivo tenga el tema o una vez que está terminado.

Input

POST /v1/workspaces/{id}/input:

`action`	Campos
`click`	`x`, `y`, `button` (1 izquierdo, 2 del medio, 3 derecho), `count`
`move`	`x`, `y`
`drag`	`x`, `y`, `x2`, `y2`
`scroll`	`x`, `y`, `dx`, `dy` (muescas; `dy > 0` scrollea hacia abajo)
`type`	`text`, `window` opcional para enfocar primero, `delay_ms`
`key`	`keys` como `Enter`, `ctrl+l`, `alt+F4`; `window` opcional

no_raise: true hace clic sin traer la ventana al frente.

Navegador

Método y ruta	Descripción
`GET /v1/workspaces/{id}/tabs`	Pestañas con sus dueños.
`POST /v1/workspaces/{id}/tabs`	`{url, isolated, same_window, observe}` → `201 {target, url, context}`; con `observe`, también `observation`.
`POST /v1/workspaces/{id}/tabs/{target}`	Una acción de pestaña, más abajo. Hace timeout a los 60 s, o a `timeout_ms` + 5 s.

Acciones de pestaña

Cuerpo: {"action": "...", ...}. Con observe: true, las acciones que cambian la página devuelven observation: lo que se ve ahora, comparado con la última vista de esa pestaña.

`action`	Campos	Devuelve
`navigate`	`url`, `wait` (`load`, `domcontentloaded`, `none`)
`back`, `forward`, `reload`
`snapshot`	`max_text` (3000 por defecto)	`snapshot`, `challenge`
`screenshot`	`full_page`, `format`, `quality`, `max_width`	`image` (base64), `mime`, `shot`
`click`	`ref` o `x`,`y`; `button`, `count`
`hover`	`ref` o `x`,`y`
`drag`	`x`, `y`, `x2`, `y2` (soporta drag de HTML5)
`fill`	`ref`, `text`, `submit`
`type`	`text`, `ref` opcional para hacer clic primero
`insert_text`	`text`
`press`	`keys`
`scroll`	`dx`, `dy` (píxeles), `x`, `y` opcionales
`select`	`ref`, `values` (valores o etiquetas)
`upload`	`files` (rutas del host), `ref` opcional (si no, el selector de archivos abierto)
`eval`	`expression` (se espera a las promesas)	el valor JSON
`wait`	`selector`, `text` o `url_contains`; `timeout_ms` (15000 por defecto)
`dialog`	`accept`, `text`
`challenge`		`challenge`
`audit`		`audit`
`emulate`	`width`, `height`, `scale`, `mobile` (ancho 0 resetea)
`focus`, `info`, `close`		`info` devuelve `tab`

Streaming

Estos aceptan un token de viewer, un token de cursor del mismo workspace (solo para mirar) o el token de admin, como header o ?token=. ?mode=observation baja el frame rate a 8 fps.

Método y ruta	Descripción
`GET /v1/workspaces/{id}/stream/ws`	WebSocket. Los mensajes binarios son frames H.264 con un header de 13 bytes (flag de keyframe, PTS de 64 bits, ancho y alto de 16 bits). Los mensajes de texto del cliente son eventos de input cuando el token permite control.
`POST /v1/workspaces/{id}/stream/webrtc`	`{sdp, mode}` con una oferta SDP → `{sdp, viewer}` con la respuesta.
`GET /v1/workspaces/{id}/stream/jpeg`	Frames JPEG guiados por daño para clientes livianos; los frames sin cambios se saltean. `?cursor=<id>` recorta a la ventana de ese cursor, `?window=<id>` a una ventana.

Cursores

Método y ruta	Descripción
`POST /v1/cursors`	Admin o `spawn`. Cuerpo más abajo → `201 {cursor, token}`. Si el lanzamiento falla, el cursor se devuelve igual con `error`.
`GET /v1/cursors`	Query: `workspace`, `parent`, `root`, `active=1`.
`GET /v1/cursors/{id}`	Estado, progreso, resultado, uso.
`GET /v1/cursors/{id}/inbox`	Mensajes después de `?since=<seq>`.
`DELETE /v1/cursors/{id}`	Borra un cursor.
`POST /v1/cursors/{id}/{op}`	Operaciones, más abajo.
`POST /v1/wait`	`{ids, all, timeout_ms}` → `{cursors, timeout}`. Espera a todos (por defecto) o a cualquiera.

Cuerpo de creación:

Campo	Descripción
`name`, `goal`, `labels`
`workspace`	Por defecto, el del padre.
`parent`	Por defecto, el cursor que llama.
`permissions`	Subconjunto de `desktop`, `browser`, `process`, `spawn`, `message`, `workspace`; intersectado con los del padre.
`budget`	`max_cursors` (hijos directos), `max_depth`.
`launch`	`{adapter, model, effort, prompt, command, tools, profile, env}`. Mirá lanzar subagentes.
`worktree`	`{repo, branch, base, ports}`.

Operaciones (POST /v1/cursors/{id}/{op}, por el propio cursor, un ancestro o el admin):

`op`	Cuerpo
`status`	`status`, `detail`
`report`	`message`, `percent`
`complete`	`result` (cualquier JSON)
`fail`	`error`
`cancel`	`reason`, `cascade` (`true` por defecto)
`pause`, `resume`
`message`	`body` (cualquier JSON). Cualquier cursor le puede mandar mensajes a otro.
`transfer`	`parent`, `workspace`
`wait`	`timeout_ms` → `{cursor, timeout}`

Eventos

Método y ruta	Descripción
`GET /v1/events`	Query: `workspace`, `cursor`, `types` (separados por comas, se permite el sufijo `*`), `since`, `limit` (≤ 500), `wait_ms` (long poll, ≤ 120000) → `{events, seq}`.
`GET /v1/events/stream`	Server-sent events con los mismos filtros. Heartbeat cada 25 s.

Los tokens que no son de admin solo ven eventos de su propio workspace.

Tipos de evento: workspace.created, workspace.state, workspace.checkpoint, workspace.forked, workspace.resumed, workspace.recovered, workspace.expired, workspace.destroyed, workspace.budget_exceeded, desktop.started, desktop.resized, desktop.window, desktop.windows, desktop.screenshot, desktop.crashed, browser.started, browser.stopped, browser.crashed, browser.tab.created, browser.tab.opened, browser.tab.navigated, browser.tab.closed, browser.tab.restored, browser.page.loaded, browser.dialog.opened, browser.dialog.closed, browser.filechooser.opened, browser.download.*, browser.challenge.detected, cursor.created, cursor.status, cursor.progress, cursor.action, cursor.pointer, cursor.message, cursor.transferred, cursor.ended, cursor.deleted, board.post, agent.launched, agent.usage, agent.exited, control.acquired, control.released, control.lost, control.taken, control.returned, human.requested, process.started, process.exited, viewer.attached, viewer.detached, stream.state, scheduler.suspend, scheduler.tab_closed, worktree.created, worktree.removed.

Worktrees

Método y ruta	Descripción
`POST /v1/worktrees`	Admin o `process`. `{repo, branch, base, ports}` → `201` worktree con `path`, `port_base`, `ports`.
`GET /v1/worktrees`	Todos los worktrees.
`DELETE /v1/worktrees/{id}`	Admin. `?force=1` lo elimina aunque tenga cambios.