Codebase

Создавайте веб-сайты и приложения с вашим ИИ-агентом. Предпросмотр, запрос изменений, сохранение исходного кода и публикация, когда вы разрешите. Публикация требует разрешения на развертывание.

Смотреть на codebase.design

Размещённый MCP-сервер

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

Устанавливается в Claude Code, Codex, Cursor и другие

Документация

Hand your agent a key. Get back a working app.

Your agent builds a real app on your Codebase account, sends you a live preview, takes your changes, and publishes it when you say so, including as a Base mini app. You keep the source. Builds spend your credits, and you set the limit.

For agent platforms and directories: the agent card, llms.txt, the skill file, the hosted MCP endpoint at https://codebase.design/api/mcp, and the OpenAPI reference.

What your agent can do

Every call uses the REST API at https://codebase.design/api/v1 with your key in the X-API-Key header. Keys only reach builds and projects on the account that created them.

Start a build

POST /api/v1/builds

scope builds:write

Send a prompt. Returns 202 with sessionId, projectId, and the status URL to poll. Add an Idempotency-Key header so a retried request returns the original build instead of starting and charging another.

Follow status

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

scope builds:read

Status is building, completed, failed, or cancelled, plus the files written so far, a plain-text summary of what a completed build made, previewUrl, workspaceUrl, sourceUrl, and a readable failure when the build did not succeed. For a live feed, stream GET /api/v1/builds/{sessionId}/events (Server-Sent Events).

Get a preview

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

scope builds:read

Starts or reuses the running preview and returns previewUrl, a private browser link you can open without signing in, with status ready, starting, or unavailable.

Request changes

POST /api/v1/builds

scope builds:write

Send a new prompt with the same projectId. The follow-up builds on the existing project and the response carries continued: true.

Cancel

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

scope builds:write

Stops a running build. Returns status cancelled, or idle if nothing was running.

Download the source

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

scope projects:read

Returns the project as a zip, without node_modules, build output, or hidden files such as.env.

Publish

POST /api/v1/deploys

scope deploys:write

Send projectId with provider codebase. Answers 202 right away with status building, a deploy id and the poll path; the fresh build and upload take a minute or two, so poll that path until it reads ready (with the public URL) or error (with a code and message). Only the build output is shipped. Building never publishes: this needs a key you created with deploys:write, which is not selected by default. The same scope is needed to make a project public or unlisted.

Check a deploy

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

scope deploys:read

Returns building, ready with the URL, or error with a code such as BUILD_FAILED and a readable message. Poll every few seconds until it is ready or error. List every publish of a project, with the live one marked, at GET /api/v1/projects/{projectId}/deploys.

Roll back

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

scope deploys:write

Puts an earlier publish of the same project back on the live URL in seconds. Nothing is rebuilt.

Unpublish

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

scope deploys:write

Takes the public site down. The published versions are kept, so a later rollback can bring one back.

No key? Your agent can pay

An agent with a crypto wallet does not need an account or a key. Ask for a build without one and the API answers 402 with an x402 payment offer in USDC on Base. Any x402 client pays it; the payment settles in seconds, and the response carries a new API key holding the credits it bought. When those run out, the same request offers a top-up on the same key. The offer names the current price and credits.

Build for Base

Add scaffold: "scaffold-base" and a recipe to the build request and your agent starts from the Base starter instead of a blank page. The result is a mini app that opens inside the Base App and Farcaster, ready to publish. Recipes are starting points: game (a playable canvas game with a leaderboard), payments, social, and mint. The prompt still decides what gets built.

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.

Publishing a Base app adds its Farcaster manifest and embed tags. To list it in the Base App, register the published URL on Base.dev; the publish dialog in the workspace prepares the listing details for you.

Set it up

  1. Create your account. Sign up or sign in the normal way. The agent uses your account; it does not get one of its own.
  2. Add credits. Top up in Settings → Billing with a credit pack or a plan. Your agent's builds draw from the same balance exactly like yours do. See pricing for plans and credits.
  3. Create a limited API key. In Settings → API keys, name the key after the agent, select only builds:write, builds:read, and projects:read, pick an expiry, and set a spending limit in credits. Add deploys:read and deploys:write only if you want the agent to publish. The key is shown once, so copy it straight into your agent's secrets. You can change the limit, revoke, or rotate the key from the same page at any time.
  4. Connect your agent. Any agent that can make HTTP requests can use the key. Give it the key as an environment variable and have it call GET /api/v1/whoami first to confirm the key and its scopes: 
    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": … }
    Give your agent the skill file. skill.md is the whole build, poll, and hand-off loop in one short Markdown file an agent can load as instructions. Claude Code users can drop it into .claude/skills/codebase/SKILL.md. 
    curl -O https://codebase.design/agents/skill.md
# Claude Code: save it as .claude/skills/codebase/SKILL.md
    MCP clients connect to the hosted endpoint at https://codebase.design/api/mcp with the same key (Authorization: Bearer). Nothing to install. The tools call the same API, so the key's scopes and credit limit apply. In Claude Code: 
    claude mcp add --transport http codebase https://codebase.design/api/mcp \
  --header "Authorization: Bearer $CODEBASE_API_KEY"
    Clients that take a URL and headers, such as Cursor: 
    {
  "mcpServers": {
    "codebase": {
      "url": "https://codebase.design/api/mcp",
      "headers": { "Authorization": "Bearer <your API key>" }
    }
  }
}
    In claude.ai or ChatGPT, add a custom connector with the URL https://codebase.design/api/mcp and no key: you sign in to Codebase, approve the app and choose its credit limit, and can disconnect it any time under Settings → API keys. The full route contract is in the OpenAPI reference and the API docs.

Example: a pomodoro timer, start to finish

This is the whole loop an agent runs. Responses are trimmed to the fields it needs.

1. Start the 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. Follow 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. Open a preview

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 is a browser link: hand it to your human and it opens the private preview in any browser, without signing in. The link carries a short-lived token and expires at previewExpiresAt (about 15 minutes), so fetch a fresh one from the status or preview call when it runs out. workspaceUrl opens the project in Codebase for you when you are signed in, and sourceUrl downloads the zip with the same key.

The link swaps its token for a cookie on the preview site and redirects, so a script that inspects the preview has to keep cookies across that redirect: curl -c jar -b jar -L "$PREVIEW_URL". A client without a cookie jar, such as a plain fetch, gets 403.

4. Request a change

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. Download the source

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

Stop a build that is going the wrong way

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

Good to know

  • Projects your agent builds belong to your account. Sessions and projects owned by anyone else return 404.
  • Before a build starts, the API checks your plan and credits. Running out of credits returns 402, too many builds at once returns 429, and a full project allowance returns 409.
  • A key that has used its spending limit gets 402 with code key-budget-exhausted, and a build that reaches the limit stops with its files kept. Raise or remove the limit in Settings → API keys.
  • Retrying a start with the same Idempotency-Key within 24 hours returns the original build. Reusing a key for a different request returns 409.
  • Starting builds and publishing are rate limited per plan, on top of the credit check. Status checks and history reads have their own, much higher limit.
  • Revoking the key in Settings → API keys cuts the agent off immediately; its projects stay in your account.