Codebase

Crea sitios web y aplicaciones con tu agente de IA. Previsualiza, solicita cambios, conserva el código fuente y publica cuando lo permitas. La publicación requiere permiso de despliegue.

Ver en codebase.design

Servidor MCP alojado

npx add-mcp 'https://codebase.design/api/mcp'

Se instala en Claude Code, Codex, Cursor y más

Documentación

Dale una clave a tu agente. Recibe una aplicación funcional.

Tu agente construye una aplicación real en tu cuenta de Codebase, te envía una vista previa en vivo, toma tus cambios y la publica cuando tú lo indiques, incluso como una mini app de Base. Tú conservas el código fuente. Las compilaciones consumen tus créditos, y tú estableces el límite.

Para plataformas y directorios de agentes: la tarjeta del agente, llms.txt, el archivo de habilidades, el endpoint MCP alojado en https://codebase.design/api/mcp, y la referencia de OpenAPI.

Lo que tu agente puede hacer

Cada llamada utiliza la API REST en https://codebase.design/api/v1 con tu clave en el encabezado X-API-Key. Las claves solo alcanzan compilaciones y proyectos en la cuenta que las creó.

Iniciar una compilación

POST /api/v1/builds

alcance builds:write

Envía un prompt. Devuelve 202 con sessionId, projectId y la URL de estado para consultar. Agrega un encabezado Idempotency-Key para que una solicitud reintentada devuelva la compilación original en lugar de iniciar y cobrar otra.

Seguir el estado

GET /api/v1/builds/{sessionId}/status

alcance builds:read

El estado es building, completed, failed o cancelled, además de los archivos escritos hasta ahora, un resumen en texto plano de lo que creó una compilación completada, previewUrl, workspaceUrl, sourceUrl y un fallo legible cuando la compilación no tuvo éxito. Para una transmisión en vivo, usa GET /api/v1/builds/{sessionId}/events (Server-Sent Events).

Obtener una vista previa

POST /api/v1/builds/{sessionId}/preview

alcance builds:read

Inicia o reutiliza la vista previa en ejecución y devuelve previewUrl, un enlace de navegador privado que puedes abrir sin iniciar sesión, con estado ready, starting o unavailable.

Solicitar cambios

POST /api/v1/builds

alcance builds:write

Envía un nuevo prompt con el mismo projectId. La continuación se basa en el proyecto existente y la respuesta incluye continued: true.

Cancelar

POST /api/v1/builds/{sessionId}/cancel

alcance builds:write

Detiene una compilación en ejecución. Devuelve estado cancelled, o idle si no había nada en ejecución.

Descargar el código fuente

GET /api/v1/projects/{projectId}/export

alcance projects:read

Devuelve el proyecto como un zip, sin node_modules, salida de compilación ni archivos ocultos como .env.

Publicar

POST /api/v1/deploys

alcance deploys:write

Envía projectId con provider codebase. Responde 202 de inmediato con estado building, un id de despliegue y la ruta de consulta; la compilación nueva y la subida tardan uno o dos minutos, así que consulta esa ruta hasta que diga ready (con la URL pública) o error (con un código y mensaje). Solo se envía la salida de la compilación. Compilar nunca publica: esto necesita una clave que hayas creado con deploys:write, que no está seleccionada por defecto. El mismo alcance se necesita para hacer un proyecto público o no listado.

Verificar un despliegue

GET /api/v1/deploys/{provider}/{deployId}

alcance deploys:read

Devuelve building, ready con la URL, o error con un código como BUILD_FAILED y un mensaje legible. Consulta cada pocos segundos hasta que esté ready o error. Lista cada publicación de un proyecto, con la activa marcada, en GET /api/v1/projects/{projectId}/deploys.

Revertir

POST /api/v1/deploys/{deployId}/rollback

alcance deploys:write

Coloca una publicación anterior del mismo proyecto de vuelta en la URL pública en segundos. No se reconstruye nada.

Despublicar

DELETE /api/v1/projects/{projectId}/site

alcance deploys:write

Elimina el sitio público. Las versiones publicadas se conservan, por lo que una reversión posterior puede traer una de vuelta.

¿Sin clave? Tu agente puede pagar

Un agente con una billetera cripto no necesita una cuenta ni una clave. Solicita una compilación sin una y la API responde 402 con una oferta de pago x402 en USDC en Base. Cualquier cliente x402 la paga; el pago se liquida en segundos, y la respuesta incluye una nueva clave de API con los créditos que compró. Cuando se agotan, la misma solicitud ofrece una recarga en la misma clave. La oferta indica el precio actual y los créditos.

Compilar para Base

Agrega scaffold: "scaffold-base" y un recipe a la solicitud de compilación y tu agente comienza desde el iniciador de Base en lugar de una página en blanco. El resultado es una mini app que se abre dentro de Base App y Farcaster, lista para publicar. Las recetas son puntos de partida: game (un juego de lienzo jugable con una tabla de clasificación), payments, social y mint. El prompt aún decide qué se construye.

curl -X POST https://codebase.design/api/v1/builds \
  -H "X-API-Key: $CODEBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "An endless runner where you tap to jump over asteroids, with a leaderboard",
       "scaffold": "scaffold-base", "recipe": "game"}'
# 202 → same response as any build. Poll it, preview it, and publish it the same way.

Publicar una app de Base agrega su manifiesto de Farcaster y etiquetas de inserción. Para listarla en Base App, registra la URL publicada en Base.dev; el diálogo de publicación en el espacio de trabajo prepara los detalles del listado por ti.

Configúralo

  1. Crea tu cuenta. Regístrate o inicia sesión de la manera habitual. El agente usa tu cuenta; no obtiene una propia.
  2. Agrega créditos. Recarga en Configuración → Facturación con un paquete de créditos o un plan. Las compilaciones de tu agente se descuentan del mismo saldo exactamente como las tuyas. Consulta precios para planes y créditos.
  3. Crea una clave de API limitada. En Configuración → Claves de API, nombra la clave según el agente, selecciona solo builds:write, builds:read y projects:read, elige una expiración y establece un límite de gasto en créditos. Agrega deploys:read y deploys:write solo si quieres que el agente publique. La clave se muestra una sola vez, así que cópiala directamente en los secretos de tu agente. Puedes cambiar el límite, revocar o rotar la clave desde la misma página en cualquier momento.
  4. Conecta tu agente. Cualquier agente que pueda hacer solicitudes HTTP puede usar la clave. Entrégale la clave como variable de entorno y haz que llame a GET /api/v1/whoami primero para confirmar la clave y sus alcances: 
    export CODEBASE_API_KEY="cb_live_..."   # the key you just created
curl https://codebase.design/api/v1/whoami \
  -H "X-API-Key: $CODEBASE_API_KEY"
# → { "userId": "…", "scopes": ["builds:write", "builds:read", "projects:read"],
#     "keyPrefix": "…", "environment": "live", "expiresAt": … }
    Dale a tu agente el archivo de habilidades. skill.md es todo el ciclo de compilar, consultar y entregar en un solo archivo Markdown corto que un agente puede cargar como instrucciones. Los usuarios de Claude Code pueden colocarlo en .claude/skills/codebase/SKILL.md. 
    curl -O https://codebase.design/agents/skill.md
# Claude Code: save it as .claude/skills/codebase/SKILL.md
    Los clientes MCP se conectan al endpoint alojado en https://codebase.design/api/mcp con la misma clave (Authorization: Bearer). Nada que instalar. Las herramientas llaman a la misma API, por lo que los alcances de la clave y el límite de créditos se aplican. En Claude Code: 
    claude mcp add --transport http codebase https://codebase.design/api/mcp \
  --header "Authorization: Bearer $CODEBASE_API_KEY"
    Clientes que aceptan una URL y encabezados, como Cursor: 
    {
  "mcpServers": {
    "codebase": {
      "url": "https://codebase.design/api/mcp",
      "headers": { "Authorization": "Bearer <your API key>" }
    }
  }
}
    En claude.ai o ChatGPT, agrega un conector personalizado con la URL https://codebase.design/api/mcp y sin clave: inicias sesión en Codebase, apruebas la app y eliges su límite de créditos, y puedes desconectarla en cualquier momento en Configuración → Claves de API. El contrato completo de rutas está en la referencia de OpenAPI y en los documentos de la API.

Ejemplo: un temporizador pomodoro, de principio a fin

Este es el ciclo completo que ejecuta un agente. Las respuestas se recortan a los campos que necesita.

1. Iniciar la compilación

curl -X POST https://codebase.design/api/v1/builds \
  -H "X-API-Key: $CODEBASE_API_KEY" \
  -H "Idempotency-Key: pomodoro-001" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A pomodoro timer with 25/5 work and break cycles and a session counter"}'
# 202 → { "sessionId": "…", "projectId": "…", "status": "building",
#         "continued": false, "model": "…",
#         "poll": "/api/v1/builds/<sessionId>/status", "workspaceUrl": "…" }
# Sending the same request with the same Idempotency-Key again returns this
# build instead of starting a second one.

2. Seguir el estado

curl https://codebase.design/api/v1/builds/$SESSION_ID/status \
  -H "X-API-Key: $CODEBASE_API_KEY"
# → { "status": "completed", "summary": "<what the build made, in plain text>",
#     "changedFiles": [...], "previewUrl": "https://…", "previewExpiresAt": …,
#     "workspaceUrl": "…", "sourceUrl": "…", "failure": null, ... }
# Poll every few seconds until status is "completed", "failed", or "cancelled".
# A build that did not succeed has "failure": { "code", "message", "retryable" }.

3. Abrir una vista previa

curl -X POST https://codebase.design/api/v1/builds/$SESSION_ID/preview \
  -H "X-API-Key: $CODEBASE_API_KEY"
# → { "ok": true, "status": "ready", "previewUrl": "https://…", "previewExpiresAt": …,
#     "workspaceUrl": "…", "sourceUrl": "…" }
# "starting" means the preview is still booting; the link works once it is up.

previewUrl es un enlace de navegador: entrégalo a tu humano y abre la vista previa privada en cualquier navegador, sin iniciar sesión. El enlace lleva un token de corta duración y expira en previewExpiresAt (aproximadamente 15 minutos), así que obtén uno nuevo de la llamada de estado o vista previa cuando se agote. workspaceUrl abre el proyecto en Codebase para ti cuando has iniciado sesión, y sourceUrl descarga el zip con la misma clave.

El enlace intercambia su token por una cookie en el sitio de vista previa y redirige, por lo que un script que inspeccione la vista previa debe mantener cookies a través de esa redirección: curl -c jar -b jar -L "$PREVIEW_URL". Un cliente sin un contenedor de cookies, como un fetch simple, recibe 403.

4. Solicitar un cambio

curl -X POST https://codebase.design/api/v1/builds \
  -H "X-API-Key: $CODEBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "'"$PROJECT_ID"'", "prompt": "Add a sound when a cycle ends and a dark theme toggle"}'
# 202 → { "sessionId": "…", "projectId": "<same projectId>", "status": "building",
#         "continued": true, ... }
# Poll the returned sessionId the same way.

5. Descargar el código fuente

curl -L https://codebase.design/api/v1/projects/$PROJECT_ID/export \
  -H "X-API-Key: $CODEBASE_API_KEY" \
  -o pomodoro.zip

Detener una compilación que va por mal camino

curl -X POST https://codebase.design/api/v1/builds/$SESSION_ID/cancel \
  -H "X-API-Key: $CODEBASE_API_KEY"
# → { "sessionId": "…", "status": "cancelled", "stopped": true, ... }

Bueno saber

  • Los proyectos que tu agente compila pertenecen a tu cuenta. Las sesiones y proyectos propiedad de cualquier otra persona devuelven 404.
  • Antes de que comience una compilación, la API verifica tu plan y créditos. Quedarse sin créditos devuelve 402, demasiadas compilaciones a la vez devuelve 429, y un límite completo de proyectos devuelve 409.
  • Una clave que ha usado su límite de gasto recibe 402 con código key-budget-exhausted, y una compilación que alcanza el límite se detiene con sus archivos conservados. Aumenta o elimina el límite en Configuración → Claves de API.
  • Reintentar un inicio con el mismo Idempotency-Key dentro de 24 horas devuelve la compilación original. Reutilizar una clave para una solicitud diferente devuelve 409.
  • Iniciar compilaciones y publicar tienen límites de velocidad por plan, además de la verificación de créditos. Las verificaciones de estado y lecturas de historial tienen su propio límite, mucho más alto.
  • Revocar la clave en Configuración → Claves de API corta al agente de inmediato; sus proyectos permanecen en tu cuenta.