API REST

La aplicación habla con el servidor mediante una API HTTP en JSON, en la misma dirección que la web. Con una clave API puedes usarla desde tus propios scripts.

Cómo funciona

La API está en https://excaliclaw.com, sin prefijo (/drawings, /collections...) y es la misma que usa la propia aplicación. Las peticiones y respuestas son JSON.

Autenticación

Clave API, para tus scripts: cabecera Authorization: Bearer exc_…. Se crea en Configuración, Claves API (ver Cuenta y ajustes). Da lectura y escritura sobre tus dibujos y colecciones, pero no puede cambiar permisos de compartir, ver el historial de versiones ni tocar el perfil.
Sesión de la aplicación: una cookie que el servidor pone al iniciar sesión y que el navegador envía sola; no hay nada que copiar.
MCP usa tokens OAuth, no claves API (ver Referencia del MCP).

Endpoints para tus scripts

Dirección	Método	Qué hace
`/drawings`	GET	Lista tus dibujos. Parámetros: `limit` (hasta 200), `offset`, `collectionId` (`null` = sin colección). Devuelve `drawings`, `totalCount`, `limit` y `offset`.
`/drawings`	POST	Crea un dibujo. Cuerpo: `name`, `collectionId`, `elements`, `appState` y `files`.
`/drawings/:id`	GET	Lee un dibujo con su escena. Admite `If-None-Match`: responde 304 si no ha cambiado.
`/drawings/:id`	PATCH	Cambia el nombre, la colección o la escena.
`/drawings/:id`	DELETE	Elimina el dibujo.
`/collections`	GET, POST	Lista o crea colecciones.
`/collections/:id`	PATCH, DELETE	Renombra o elimina una colección (sus dibujos pasan a «Sin organizar»).
`/workspace/export`	GET	Copia de seguridad de todo tu espacio en una sola petición.
`/workspace/import`	POST	Restaura una copia de seguridad.

Diagramas por HTTP

Tres endpoints convierten texto en diagramas con la misma lógica que el MCP. No guardan nada: devuelven el resultado y tú decides qué hacer con él. Aceptan la sesión o una clave API.

Dirección	Método	Qué hace
`/diagrams/mermaid/import`	POST	Cuerpo `{mermaid, direction?, title?, theme?}`. Devuelve los elementos de Excalidraw ya colocados, un resumen y avisos de lo que se aplanó.
`/diagrams/mermaid/export`	POST	Cuerpo `{elements}`. Devuelve el diagrama como texto Mermaid.
`/diagrams/repo/scan`	POST	Cuerpo `{files: [{path, content}]}` con `docker-compose`, `wrangler` o `package.json`. Devuelve la arquitectura como Mermaid, con la evidencia de cada pieza.

Límites y errores

300 peticiones por minuto por usuario o clave y 1500 por dirección IP. Iniciar sesión y registrarse: 20 por minuto por IP. Al pasarte, 429 con Retry-After.
El cuerpo de una petición no puede pasar de 10 MB (error 413).
401 sin credenciales válidas; 403 sin permiso (por ejemplo, una clave API en una ruta de permisos); 404 si no existe o no es tuyo.
402 con code: "payment_required" si hay un cobro pendiente, y 403 con code: "plan_limit_reached" al llegar al tope del plan (200 dibujos en Free).

Ejemplos con curl

Listar tus 5 últimos dibujos: curl -H "Authorization: Bearer exc_TU_CLAVE" "https://excaliclaw.com/drawings?limit=5"
Copia de seguridad completa: curl -H "Authorization: Bearer exc_TU_CLAVE" https://excaliclaw.com/workspace/export -o copia.json
Convertir Mermaid en elementos: curl -X POST -H "Authorization: Bearer exc_TU_CLAVE" -H "Content-Type: application/json" -d '{"mermaid":"flowchart TD\n A-->B"}' https://excaliclaw.com/diagrams/mermaid/import

Ojo. Una clave API da acceso completo a tus dibujos: guárdala como una contraseña y revócala desde Configuración si se filtra. La API puede cambiar; esta página describe lo que existe al escribirla.