Codebase

Crie sites e aplicativos com seu agente de IA. Visualize, peça alterações, mantenha o código-fonte e publique quando você permitir. A publicação exige permissão de deploy.

Ver em codebase.design

Servidor MCP hospedado

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

Instala no Claude Code, Codex, Cursor e outros

Documentação

Entregue uma chave ao seu agente. Receba um aplicativo funcional.

Seu agente cria um aplicativo real na sua conta Codebase, envia a você uma prévia ao vivo, aplica suas alterações e publica quando você autorizar, inclusive como um mini app Base. Você mantém o código-fonte. Builds consomem seus créditos, e você define o limite.

Para plataformas e diretórios de agentes: o cartão do agente, llms.txt, o arquivo de skill, o endpoint MCP hospedado em https://codebase.design/api/mcp e a referência OpenAPI.

O que seu agente pode fazer

Cada chamada usa a API REST em https://codebase.design/api/v1 com sua chave no cabeçalho X-API-Key. As chaves só alcançam builds e projetos na conta que as criou.

Iniciar um build

POST /api/v1/builds

escopo builds:write

Envie um prompt. Retorna 202 com sessionId, projectId e a URL de status para consulta. Adicione um cabeçalho Idempotency-Key para que uma solicitação repetida retorne o build original em vez de iniciar e cobrar outro.

Acompanhar o status

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

escopo builds:read

O status é building, completed, failed ou cancelled, além dos arquivos gravados até o momento, um resumo em texto simples do que um build concluído criou, previewUrl, workspaceUrl, sourceUrl e uma falha legível quando o build não teve sucesso. Para um feed ao vivo, faça streaming de GET /api/v1/builds/{sessionId}/events (Server-Sent Events).

Obter uma prévia

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

escopo builds:read

Inicia ou reutiliza a prévia em execução e retorna previewUrl, um link de navegador privado que você pode abrir sem fazer login, com status ready, starting ou unavailable.

Solicitar alterações

POST /api/v1/builds

escopo builds:write

Envie um novo prompt com o mesmo projectId. O acompanhamento é construído sobre o projeto existente e a resposta traz continued: true.

Cancelar

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

escopo builds:write

Interrompe um build em execução. Retorna status cancelled, ou idle se nada estava em execução.

Baixar o código-fonte

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

escopo projects:read

Retorna o projeto como um zip, sem node_modules, saída de build ou arquivos ocultos como .env.

Publicar

POST /api/v1/deploys

escopo deploys:write

Envie projectId com provider codebase. Responde 202 imediatamente com status building, um id de deploy e o caminho de consulta; o novo build e o upload levam um ou dois minutos, então consulte esse caminho até que ele indique ready (com a URL pública) ou error (com um código e mensagem). Apenas a saída do build é enviada. Construir nunca publica: isso exige uma chave que você criou com deploys:write, que não é selecionada por padrão. O mesmo escopo é necessário para tornar um projeto público ou não listado.

Verificar um deploy

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

escopo deploys:read

Retorna building, ready com a URL, ou error com um código como BUILD_FAILED e uma mensagem legível. Consulte a cada poucos segundos até que esteja ready ou error. Liste cada publicação de um projeto, com a ativa marcada, em GET /api/v1/projects/{projectId}/deploys.

Reverter

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

escopo deploys:write

Coloca uma publicação anterior do mesmo projeto de volta na URL ativa em segundos. Nada é reconstruído.

Despublicar

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

escopo deploys:write

Tira o site público do ar. As versões publicadas são mantidas, então uma reversão posterior pode trazer uma de volta.

Sem chave? Seu agente pode pagar

Um agente com uma carteira de criptomoedas não precisa de conta ou chave. Solicite um build sem uma e a API responde 402 com uma oferta de pagamento x402 em USDC na Base. Qualquer cliente x402 paga; o pagamento é liquidado em segundos, e a resposta traz uma nova chave de API com os créditos que comprou. Quando esses acabarem, a mesma solicitação oferece uma recarga na mesma chave. A oferta informa o preço atual e os créditos.

Crie para Base

Adicione scaffold: "scaffold-base" e um recipe à solicitação de build e seu agente começa pelo starter Base em vez de uma página em branco. O resultado é um mini app que abre dentro do Base App e Farcaster, pronto para publicar. Receitas são pontos de partida: game (um jogo de canvas jogável com um placar), payments, social e mint. O prompt ainda decide o que é construído.

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 um app Base adiciona seu manifesto Farcaster e tags de incorporação. Para listá-lo no Base App, registre a URL publicada em Base.dev; o diálogo de publicação no workspace prepara os detalhes da listagem para você.

Configuração

  1. Crie sua conta. Registre-se ou entre da forma normal. O agente usa sua conta; ele não ganha uma própria.
  2. Adicione créditos. Recarregue em Configurações → Cobrança com um pacote de créditos ou um plano. Os builds do seu agente usam o mesmo saldo exatamente como os seus. Veja preços para planos e créditos.
  3. Crie uma chave de API limitada. Em Configurações → Chaves de API, nomeie a chave com o nome do agente, selecione apenas builds:write, builds:read e projects:read, escolha uma expiração e defina um limite de gastos em créditos. Adicione deploys:read e deploys:write somente se quiser que o agente publique. A chave é mostrada uma única vez, então copie-a diretamente para os segredos do seu agente. Você pode alterar o limite, revogar ou rotacionar a chave na mesma página a qualquer momento.
  4. Conecte seu agente. Qualquer agente que possa fazer solicitações HTTP pode usar a chave. Dê a chave como uma variável de ambiente e peça para ele chamar GET /api/v1/whoami primeiro para confirmar a chave e seus escopos: 
    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": … }
    Dê ao seu agente o arquivo de skill. skill.md é todo o loop de build, consulta e entrega em um único arquivo Markdown curto que um agente pode carregar como instruções. Usuários do Claude Code podem colocá-lo em .claude/skills/codebase/SKILL.md. 
    curl -O https://codebase.design/agents/skill.md
# Claude Code: save it as .claude/skills/codebase/SKILL.md
    Clientes MCP se conectam ao endpoint hospedado em https://codebase.design/api/mcp com a mesma chave (Authorization: Bearer). Nada para instalar. As ferramentas chamam a mesma API, então os escopos da chave e o limite de créditos se aplicam. No Claude Code: 
    claude mcp add --transport http codebase https://codebase.design/api/mcp \
  --header "Authorization: Bearer $CODEBASE_API_KEY"
    Clientes que aceitam uma URL e cabeçalhos, como Cursor: 
    {
  "mcpServers": {
    "codebase": {
      "url": "https://codebase.design/api/mcp",
      "headers": { "Authorization": "Bearer <your API key>" }
    }
  }
}
    No claude.ai ou ChatGPT, adicione um conector personalizado com a URL https://codebase.design/api/mcp e sem chave: você faz login no Codebase, aprova o app e escolhe seu limite de créditos, e pode desconectá-lo a qualquer momento em Configurações → Chaves de API. O contrato completo da rota está na referência OpenAPI e na documentação da API.

Exemplo: um timer pomodoro, do início ao fim

Este é o loop completo que um agente executa. As respostas são reduzidas aos campos que ele precisa.

1. Inicie o build

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. Acompanhe o status

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. Abra uma prévia

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 é um link de navegador: entregue-o ao seu humano e ele abre a prévia privada em qualquer navegador, sem fazer login. O link carrega um token de curta duração e expira em previewExpiresAt (cerca de 15 minutos), então busque um novo na chamada de status ou prévia quando ele expirar. workspaceUrl abre o projeto no Codebase para você quando estiver conectado, e sourceUrl baixa o zip com a mesma chave.

O link troca seu token por um cookie no site da prévia e redireciona, então um script que inspeciona a prévia precisa manter cookies nesse redirecionamento: curl -c jar -b jar -L "$PREVIEW_URL". Um cliente sem um armazenamento de cookies, como um fetch simples, recebe 403.

4. Solicite uma alteração

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. Baixe o código-fonte

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

Pare um build que está indo pelo caminho errado

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

Bom saber

  • Projetos que seu agente cria pertencem à sua conta. Sessões e projetos de terceiros retornam 404.
  • Antes de um build começar, a API verifica seu plano e créditos. Ficar sem créditos retorna 402, muitos builds de uma vez retorna 429, e uma cota de projeto cheia retorna 409.
  • Uma chave que usou seu limite de gastos recebe 402 com código key-budget-exhausted, e um build que atinge o limite para com seus arquivos mantidos. Aumente ou remova o limite em Configurações → Chaves de API.
  • Repetir um início com o mesmo Idempotency-Key dentro de 24 horas retorna o build original. Reutilizar uma chave para uma solicitação diferente retorna 409.
  • Iniciar builds e publicar são limitados por taxa conforme o plano, além da verificação de créditos. Verificações de status e leituras de histórico têm seu próprio limite, muito maior.
  • Revogar a chave em Configurações → Chaves de API corta o acesso do agente imediatamente; seus projetos permanecem na sua conta.