---
title: API HTTP
description: >-
  Todos los endpoints del daemon de Agora, con autenticación, cuerpos de las
  solicitudes y errores.
sidebar:
  icon: braces
---
El daemon sirve una API JSON bajo `/v1` en `127.0.0.1:7788`, además del dashboard en `/`.

## Convenciones [#conventions]

- **Auth:** `Authorization: Bearer <token>` en todos los endpoints salvo `GET /v1/health`. Los endpoints de streaming también aceptan `?token=`. Mirá [tokens](/es/security#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 [#system]

| 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](/es/concepts#configuration). |
| `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 [#operations]

`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 [#desktop]

| 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 [#browser]

| 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 [#tab-actions]

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 [#cursors]

| 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](/es/agents/tools#subagents). |
| `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 [#events]

| 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. |