API Overview

Base path

The versioned REST API is mounted at /api/v1. Responses include API version and request-id headers so client logs can connect back to server-side traces.

Authentication

The API accepts scoped API keys and OAuth bearer tokens. API keys can be created and revoked from account settings. OAuth supports browser-based account authorization and device-code login for terminal-style clients.

Build with curl

One POST starts a build, one GET polls it, and one POST opens a live preview. Responses are structured JSON.

# Start a build (returns 202 + a session to poll)
curl -X POST https://codebase.design/api/v1/builds \
  -H "X-API-Key: $CODEBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a pomodoro timer with work/break cycles and a session counter"}'
# → { "sessionId": "…", "projectId": "…", "status": "building",
#     "poll": "/api/v1/builds/<sessionId>/status" }

# Poll until status is "completed" (or "failed")
curl https://codebase.design/api/v1/builds/$SESSION_ID/status \
  -H "X-API-Key: $CODEBASE_API_KEY"
# → { "status": "completed", "filesCreated": [...], "timeline": [...] }

# Then start a live preview of the built app
curl -X POST https://codebase.design/api/v1/builds/$SESSION_ID/preview \
  -H "X-API-Key: $CODEBASE_API_KEY"
# → { "ok": true, "previewPath": "/preview/<projectId>" }

Most builds finish in a few minutes; complex apps can take longer. Automated QA checks that the result builds and opens in a real browser before a build reports complete.

Core route families

• Projects: project lookup and generated app resources.
• Builds: build creation, status, and related session activity.
• Deploys: deployment requests and provider-specific deploy status.
• Gallery and community: public sharing and discovery surfaces.
• Account activity, credits, billing, prompts, chat, and inference: account and product integrations.

Interactive reference

Use /api-docs/ for the Swagger UI proxy when the backend docs server is running. For production scripts, prefer the documented /api/v1 routes and scoped credentials rather than browser session cookies.