API reference

Copies every endpoint as Markdown.

Every CloudCode endpoint, ready to copy. All endpoints are HTTPS and take JSON request bodies. Endpoints marked authrequire an Authorization: Bearer header, normally a CloudCode access token: a JWT minted from your signed-in session that is valid for 15 minutes. The Public API (cc-api/v1/…) endpoints additionally accept a personal cc_live_… API key; the Auto-Fix API also accepts its own Auto-Fix API key or a project webhook token via X-Project-Token.

Generate scoped, revocable API keys in Settings → CloudCode API Keys.

Base URL
https://cloudcode.gg/api/functions/v1
Auth header (API key)
Authorization: Bearer cc_live_…

Public API — auth, errors, limits

  • Send Authorization: Bearer cc_live_… (a personal API key), a CloudCode access token (the Better Auth JWT minted from your signed-in session, valid 15 minutes) or an MCP OAuth token. A session or OAuth token has full access; an API key is limited to the scopes chosen when it was created.
  • Keys are shown once at creation and stored only as a SHA-256 hash. Revoked or expired keys stop working immediately. Keys created before November 13, 2026 didn't carry over to the new backend; create a new one.
  • Every route also answers without the /v1 prefix (e.g. cc-api/projects).
  • Errors are JSON: { "error": "message" }. 401 missing header / invalid token / invalid or revoked API key · 403 Missing required scope: <scope> · 404 not found or unknown route · 500 server error.
  • cc-api has no rate limiting of its own. AI Chat returns 429 when the AI gateway rate-limits and 402 when you're out of credits.

API key scopes

projects:read
List / get projects; list GitHub repos
projects:write
Create projects
files:read
List files; get file content
files:write
Upsert and delete files
deploy
List and trigger deployments; list GitHub repos
agent:run
AI chat
terminal
Can be granted, but no Public API endpoint uses it yet

New keys default to projects:read + files:read and can expire after 30, 90 or 365 days, or never.

AI

6
POST

AI Agent

auth

Streaming AI agent (Server-Sent Events). The server owns the system prompt: a system string you send is cut to 20,000 characters and passed to the model as an "Additional context" user turn, not as system instructions. Send the full conversation on every request; the server keeps no history between requests. Set enable_tools + project_id to run the agentic tool loop over that project (up to 200 iterations). Runs stop between steps after 10 minutes. The agent is offered up to 71 tools, chosen per request: a core set for reading, searching, writing and patching files, sandbox commands (run_terminal, run_typecheck), the headless-browser check (check_ui), planning, memory and safety checks, plus refactoring, checks (ESLint, osv.dev vulnerability lookups), checkpoints and file history, line comments, database (get_database_schema, apply_migration; always added when the project has a connected database), history and code-generation groups added when your message asks for that kind of work. Commands run in the project's Vercel Sandbox (network limited to package registries and GitHub, no env vars, 30 commands and 8 browser checks per run); its time is billed to your credits, and command results carry executed and exit_code. A check_ui result carries screenshot_url (a JPEG data URL). plan_mode: true makes the agent propose a plan (propose_plan) instead of changing files; approving it means sending the next request. The tool loop emits typed JSON events: text, tool_call_start, tool_call_result, plan_proposed, plan_step_update, subtask_update, clarification_needed, diff_preview, dependency_graph_result, dependency_analysis, safety_warning, safety_confirmation_required, usage_progress (an estimate of the credits used so far), file_changes, usage (the settled charge and balance), done and error, the same events whichever provider runs; ": keepalive" comment lines are sent while the model works. Without tools it streams OpenAI-format chat chunks. model picks the provider: claude-opus-5-5, claude-sonnet-5-5 and claude-haiku-5-5 run on the Anthropic API (your stored Anthropic key from Settings → API Keys & Integrations if present, otherwise the platform key; 503 if neither exists); google/gemini-3.1-pro-preview, google/gemini-3-pro-preview, google/gemini-3-flash-preview, google/gemini-2.5-pro, google/gemini-2.5-flash, google/gemini-2.5-flash-lite, openai/gpt-5.2, openai/gpt-5, openai/gpt-5-mini and openai/gpt-5-nano run on Vercel AI Gateway. Aliases: opus, sonnet, haiku (the Claude 5.5 models), thinking (google/gemini-2.5-pro); retired Claude ids such as claude-sonnet-4-20250514 map to the matching Claude 5.5 model; other unknown ids fall back to google/gemini-3-flash-preview. use_anthropic is kept for older clients and only selects claude-sonnet-5-5 when model is omitted. max_tokens applies only to Claude without tools (default 32000, max 128000). client_dependencies, client_errors, session_memory, auto_apply and plan_mode are only used in tool mode. Request body limit: 4 MB.

POSThttps://cloudcode.gg/api/functions/v1/ai-agent
Example body
{
  "messages": [{ "role": "user", "content": "Build a todo app" }],
  "system": "We use Tailwind and shadcn/ui.",
  "model": "claude-sonnet-5-5",
  "enable_tools": true,
  "project_id": "uuid",
  "plan_mode": false,
  "images": [{ "dataUrl": "data:image/png;base64,..." }],
  "auto_apply": false,
  "client_dependencies": ["react", "zod"],
  "client_errors": [],
  "session_memory": ""
}
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/ai-agent' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{ "messages": [{ "role": "user", "content": "Build a todo app" }], "system": "We use Tailwind and shadcn/ui.", "model": "claude-sonnet-5-5", "enable_tools": true, "project_id": "uuid", "plan_mode": false, "images": [{ "dataUrl": "data:image/png;base64,..." }], "auto_apply": false, "client_dependencies": ["react", "zod"], "client_errors": [], "session_memory": "" }'
Response: text/event-stream (SSE)
Errors: 400 invalid JSON or empty messages · 401 · 402 { code: "INSUFFICIENT_CREDITS", error, balance } out of credits (usage is billed by tokens; free on your own Anthropic key), or "AI credits exhausted" when the gateway refuses the request · 413 body over 4 MB · 429 rate limited · 400 / 502 Claude couldn't process the request or is unavailable (fixed messages; upstream error text is never returned) · 503 AI service not configured, no Anthropic key for a Claude model, or { code: "BILLING_UNAVAILABLE" } billing temporarily unavailable
POST

Chat

auth

Streaming chat completion (always streams; OpenAI chunk format, ends with data: [DONE]). model picks the provider exactly as for AI Agent: Claude models (claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5) run on the Anthropic API, Gemini/GPT models on Vercel AI Gateway, with the same aliases and fallback. For Claude the key is the one in api_key if given, else your stored Anthropic key, else the platform key (503 if none); max_tokens applies (default 32000, max 128000). Anthropic errors are returned as fixed messages (400, 429 or 502) and the request is not re-routed to another provider. use_anthropic or api_key without a model selects claude-sonnet-5-5. A system string is treated as for AI Agent (cut to 20,000 characters and sent as an "Additional context" user turn). Supports image input on the last user message. Request body limit: 4 MB.

POSThttps://cloudcode.gg/api/functions/v1/chat
Example body
{
  "messages": [{ "role": "user", "content": "Hello" }],
  "system": "Answer briefly.",
  "model": "google/gemini-3-flash-preview",
  "images": [{ "dataUrl": "data:image/png;base64,..." }]
}
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/chat' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{ "messages": [{ "role": "user", "content": "Hello" }], "system": "Answer briefly.", "model": "google/gemini-3-flash-preview", "images": [{ "dataUrl": "data:image/png;base64,..." }] }'
Response: text/event-stream (SSE)
Errors: 400 invalid JSON or empty messages · 401 · 402 { code: "INSUFFICIENT_CREDITS", error, balance } out of credits (usage is billed by tokens; free on your own Anthropic key), or "AI credits exhausted" when the gateway refuses the request · 413 body over 4 MB · 429 rate limited · 400 / 502 Claude couldn't process the request or is unavailable (fixed messages; upstream error text is never returned) · 503 AI service not configured, no Anthropic key for a Claude model, or { code: "BILLING_UNAVAILABLE" } billing temporarily unavailable
POST

Claude Proxy

auth

Deprecated. Thin wrapper that forwards the request body (and Authorization header) to the chat function with use_anthropic: true (so a request without model runs on claude-sonnet-5-5). Call chat directly instead.

POSThttps://cloudcode.gg/api/functions/v1/claude-proxy
Example body
{
  "messages": [{ "role": "user", "content": "Hello" }],
  "max_tokens": 1024
}
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/claude-proxy' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{ "messages": [{ "role": "user", "content": "Hello" }], "max_tokens": 1024 }'
Response: text/event-stream (SSE), as returned by chat
POST

Auto-Fix API — Submit Job

auth

Queue an autonomous fix job: generates edits, verifies the build, runs vision regression, pushes to GitHub (PR or commit), polls CI with re-fix retries, and can auto-merge, verify the live deploy, and auto-revert. Authenticate with Authorization: Bearer <CloudCode access token or Auto-Fix API key from Settings → Auto-Fix API>, or with an X-Project-Token webhook token (project_id then defaults to the token's project). Provide prompt (prompt mode) or error_message (error mode, with optional file, line, stack_trace). delivery is "pr" (default) or "commit"; target_branch defaults to main; max_fix_retries is clamped to 0–3 (default 1); github_owner/github_repo default to the project's linked repo, and a repo is required. One job runs per project at a time, and the AI work is billed to the project owner's credits. Other routes: GET /jobs?project_id=… (latest 50 → { jobs }), GET /jobs/:id (→ { job }), POST /jobs/:id/cancel (queued/running only → { cancelled: true }), POST /jobs/:id/reverify (→ { reverified, vision, post_deploy_status }), POST /jobs/:id/revert (→ { reverted, revert_sha }).

POSThttps://cloudcode.gg/api/functions/v1/auto-fix-api/jobs
Example body
{
  "project_id": "uuid",
  "prompt": "Fix the failing build",
  "error_message": null,
  "target_branch": "main",
  "delivery": "pr",
  "auto_merge": false,
  "max_fix_retries": 1
}
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/auto-fix-api/jobs' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN_OR_AUTOFIX_KEY>' \
  -d '{ "project_id": "uuid", "prompt": "Fix the failing build", "error_message": null, "target_branch": "main", "delivery": "pr", "auto_merge": false, "max_fix_retries": 1 }'
Response: 202 { "job_id": "uuid", "status": "queued", "status_url": "https://cloudcode.gg/api/functions/v1/auto-fix-api/jobs/<job_id>" }
Errors: 400 missing project_id or prompt/error_message · 400 { code: "GITHUB_REPO_REQUIRED" } no linked GitHub repo · 401 · 402 { code: "INSUFFICIENT_CREDITS" } out of credits · 403 project not owned by caller, or project_id doesn't match the X-Project-Token project · 404 unknown route or job · 409 { code: "JOB_ALREADY_RUNNING", job_id } a job is already running for this project
POST

CI Fix

auth

Suggest code fixes for a failing GitHub Actions job from its logs (non-streaming). failureLogs is required and truncated to 8,000 characters; each context file is truncated to 2,000 characters.

POSThttps://cloudcode.gg/api/functions/v1/ci-fix
Example body
{
  "failureLogs": "Error: ...",
  "jobName": "build",
  "repoFullName": "owner/repo",
  "files": [{ "path": "src/App.tsx", "content": "..." }]
}
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/ci-fix' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{ "failureLogs": "Error: ...", "jobName": "build", "repoFullName": "owner/repo", "files": [{ "path": "src/App.tsx", "content": "..." }] }'
Response: { "suggestion": "markdown" }
Errors: 400 failureLogs is required · 401 · 402 { code: "INSUFFICIENT_CREDITS", error, balance } out of credits (billed by tokens) · 429 rate limited · 503 billing unavailable · 500
POST

ElevenLabs TTS

auth

Text-to-speech via ElevenLabs (eleven_turbo_v2_5, MP3). text is capped at 5,000 characters; voiceId (alphanumeric) defaults to JBFqnCBsd6RMkjVDRZzb. Requires a signed-in user's access token.

POSThttps://cloudcode.gg/api/functions/v1/elevenlabs-tts
Example body
{ "text": "Hello world", "voiceId": "21m00Tcm4TlvDq8ikWAM" }
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/elevenlabs-tts' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{ "text": "Hello world", "voiceId": "21m00Tcm4TlvDq8ikWAM" }'
Response: { "audio": "<base64>", "mime": "audio/mpeg" }
Errors: 400 text is required or invalid voiceId · 401 · 402 { code: "INSUFFICIENT_CREDITS", error, balance } out of credits (billed by characters) · 503 billing unavailable · 500 TTS failed or not configured

Deployment

3
POST

Deploy Vercel

auth

Deploy the supplied files of a project you own to Vercel and wait for the build to finish (polls for up to ~5 minutes). projectId is required and must belong to the caller (404 otherwise). With deployType "static" (default), a project whose package.json uses Vite, React, Next.js or Create React App, or has a build script, is uploaded as-is and built on Vercel with the matching framework preset (Vite/CRA get an index.html fallback; a bare React project gets the missing vite.config.mjs / index.html / src/main entry / build script added); anything else is served as plain files with @vercel/static, with package.json and Node server entry files removed and an index.html added if none exists. "node" deploys with @vercel/node using index.js / server.js / app.js as the entry. The Vercel project name is derived on the server as cc-<hash of your user id>-<project name>-<project id prefix>; projectName is ignored. The project's env vars for environment (development, staging or production; workspace overrides apply when workspaceId is given) are read on the server and passed to Vercel as build and runtime env. environment "production" targets production; any other value creates a preview deployment. Any vercel.json you send is replaced. HTML files get a console/network logger script and a "Built with CloudCode" badge (unless badge is false); Next.js projects get neither. Requires a signed-in user's access token.

POSThttps://cloudcode.gg/api/functions/v1/deploy-vercel
Example body
{
  "projectId": "<PROJECT_ID>",
  "workspaceId": null,
  "files": [{ "path": "index.html", "content": "..." }],
  "environment": "production",
  "deployType": "static",
  "badge": true
}
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/deploy-vercel' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{ "projectId": "<PROJECT_ID>", "workspaceId": null, "files": [{ "path": "index.html", "content": "..." }], "environment": "production", "deployType": "static", "badge": true }'
Response: { "url": "https://….vercel.app", "id": "dpl_…", "readyState": "READY", "deployType": "static", "mode": "vite", "vercelProject": "cc-…", "envVarCount": 3, "skippedEnvKeys": [], "notes": ["Added index.html"] }
Errors: 400 projectId required / no files to deploy / invalid deployType · 401 · 404 project or workspace not found · 429 Vercel rate limit · 502 Vercel rejected the deployment · 503 deploy service unavailable · 500 build failed or still building after ~5 minutes
GET

Vercel Connect

auth

Connect your own Vercel account so Deploy Vercel deploys to it (Settings → API Keys & Integrations). GET ?action=status → { connected, account_label, team, available, needs_reconnect }. POST ?action=start → { url } to install CloudCode's Vercel integration (sets a state cookie; Vercel redirects back to this function, which stores the token encrypted and returns you to Settings). POST ?action=disconnect uninstalls the integration (best effort) and deletes the stored token. The token is never returned.

GEThttps://cloudcode.gg/api/functions/v1/vercel-connect?action=status
cURL
curl -X GET 'https://cloudcode.gg/api/functions/v1/vercel-connect?action=status' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
Response: { "connected": true, "account_label": "jane", "team": null, "available": true, "needs_reconnect": false }
Errors: 400 Unknown action · 401
POST

Export ZIP

auth

Bundle all of a project's files into a downloadable zip archive (Content-Disposition: attachment; filename="<project name>.zip"). The project must belong to the caller.

POSThttps://cloudcode.gg/api/functions/v1/export-zip
Example body
{ "projectId": "uuid" }
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/export-zip' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{ "projectId": "uuid" }'
Response: application/zip
Errors: 400 projectId required · 401 · 404 project not found

Database

1
POST

Project Database

auth

Project Dashboard → Database: connect a project's own Neon, Supabase or other Postgres database. Requires edit access to the project. Action-based: status (→ connection, tables with RLS on/off, migration files and when each was applied), connect (connectionString, plus supabaseUrl and supabaseAnonKey for Supabase; tests the connection, stores it encrypted and, unless setEnv is false, adds DATABASE_URL and the Supabase public variables to every environment), create_neon (a database in CloudCode's Neon org that you claim later; only when status reports neonHosting: true, at most 3 unclaimed per user), claim_link (→ { url, expiresAt }: a one-time Neon transfer link, valid 7 days, never stored), refresh (re-read the schema), apply (path of a .sql file in the project; runs in one transaction, and migrations that drop or rewrite data need confirmDestructive: true) and disconnect (an unclaimed CloudCode-created database is deleted). TLS only; hosts that resolve to private addresses are refused. The connection string is never returned.

POSThttps://cloudcode.gg/api/functions/v1/project-database
Example body
{
  "action": "apply",
  "projectId": "uuid",
  "path": "supabase/migrations/20261116_todos.sql",
  "confirmDestructive": false
}
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/project-database' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{ "action": "apply", "projectId": "uuid", "path": "supabase/migrations/20261116_todos.sql", "confirmDestructive": false }'
Response: { "connected": true, "neonHosting": false, "provider": "neon", "host": "ep-….neon.tech", "database": "neondb", "schema_summary": "...", "hosted": false, "claimed_at": null, "migrations": [...] }
Errors: 400 invalid request, unknown action or not a migration path · 401 · 403 no edit access · 404 migration file not in the project · 409 already connected, nothing connected, already claimed, unclaimed limit, or { needsConfirm: true, destructive } for a destructive migration · 422 { failed: true, error } the migration failed and nothing changed · 503 creating a Neon database isn't available

GitHub

2
POST

GitHub API

auth

Authenticated proxy to the GitHub REST API using your linked GitHub token. Action-based router — actions: list_repos, get_repo, create_repo, list_branches, create_branch, push, pull, list_prs, create_pr, get_pr_diff, merge_pr, list_runs, get_run_jobs, get_job_log, list_check_runs, get_commit_status, list_commits, compare_commits, list_issues, create_issue, disconnect.

POSThttps://cloudcode.gg/api/functions/v1/github-api
Example body
{ "action": "list_repos" }
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/github-api' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{ "action": "list_repos" }'
Errors: 400 Unknown action · 401 · 403 GitHub not connected
GET

GitHub OAuth Callback

public

Handles the OAuth redirect after GitHub authorization (?code=…&state=…), stores the access token for the user identified by the single-use state nonce, then redirects (302) back to the app with ?github_connected=1&github_login=… (or ?github_error=…). Also: ?get_client_id=1 returns { client_id }, and ?create_nonce=1 (requires a signed-in user's access token) returns { nonce } for starting the OAuth flow. GitHub connections made before November 13, 2026 didn't carry over to the new backend; connect again from the GitHub tab.

GEThttps://cloudcode.gg/api/functions/v1/github-oauth-callback
cURL
curl -X GET 'https://cloudcode.gg/api/functions/v1/github-oauth-callback'

Runtime

1
POST

Terminal Exec

auth

Simulated terminal for the in-app console. No real shell is executed and nothing is installed. npm install / npm i <pkg> looks up package metadata from the npm registry and reports it; every other command returns a "Command not executed" line. Responses always carry executed: false, simulated: true, exit_code: 1.

POSThttps://cloudcode.gg/api/functions/v1/terminal-exec
Example body
{
  "command": "npm",
  "args": ["install", "zod"],
  "cwd": "/workspace"
}
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/terminal-exec' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{ "command": "npm", "args": ["install", "zod"], "cwd": "/workspace" }'
Response: { "output": [{ "text": "...", "type": "info|output|success|error" }], "resolved": [...], "executed": false, "simulated": true, "exit_code": 1 }
Errors: 401 · 500

Account

2
POST

Delete Account

auth

Permanently delete the calling user's auth account, then their projects (with chat messages, files and workspaces), stored provider keys, and profile. No request body.

POSThttps://cloudcode.gg/api/functions/v1/delete-account
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/delete-account' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
Response: { "success": true }
Errors: 400 with an error message (including missing or invalid session)
POST

Transfer Projects

auth

Transfer ownership of up to 50 of your projects to another existing user, identified by email.

POSThttps://cloudcode.gg/api/functions/v1/transfer-projects
Example body
{
  "targetEmail": "new-owner@example.com",
  "projectIds": ["uuid"]
}
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/transfer-projects' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{ "targetEmail": "new-owner@example.com", "projectIds": ["uuid"] }'
Response: { "success": true, "transferred": 1, "to": "new-owner@example.com" }
Errors: 400 missing fields, more than 50 projects, or self-transfer · 401 · 403 caller does not own a project · 404 no account with that email

Billing

4
GET

Cred Checkout — Pricing Tiers

public

List CloudCode's credit pack pricing tiers from Cred.diy (filtered to CloudCode's credit type).

GEThttps://cloudcode.gg/api/functions/v1/cred-checkout/pricing-tiers
cURL
curl -X GET 'https://cloudcode.gg/api/functions/v1/cred-checkout/pricing-tiers'
Response: { "pricing_tiers": [...] }
POST

Cred Checkout — Create Session

auth

Create a Cred.diy hosted checkout session for a CloudCode credit pack for the signed-in user (user id and email come from the access token). Success and cancel URLs are built from the request's Origin header (/billing/success and /settings). Returns Cred's hosted-checkout response as-is.

POSThttps://cloudcode.gg/api/functions/v1/cred-checkout/create-session
Example body
{
  "pricing_tier_id": "uuid",
  "signup_url": "https://cloudcode.gg/?ref=..."
}
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/cred-checkout/create-session' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{ "pricing_tier_id": "uuid", "signup_url": "https://cloudcode.gg/?ref=..." }'
Errors: 400 pricing_tier_id is required · 400 Unknown pricing tier · 401
POST

Cred Checkout — Balance

auth

Get the signed-in user's CloudCode credit balance from Cred.diy, looked up by the access token's email when present, otherwise user id. Returns Cred's response with balances filtered to CloudCode's credit type.

POSThttps://cloudcode.gg/api/functions/v1/cred-checkout/balance
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/cred-checkout/balance' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
Response: { "balances": [...], ... }
Errors: 401
POST

Referrals

auth

Invite friends (Settings → Usage & Billing). action "status" → your code and link (https://cloudcode.gg/?ref=<code>), how many signed up and were rewarded, and the credits earned. action "claim" with code records the referral for the signed-in user: only accounts created in the last 7 days, once, never your own code. Both people get 100 credits when the referred user has a confirmed email and finishes a first agent run that changes files (up to 25 rewarded friends per referrer).

POSThttps://cloudcode.gg/api/functions/v1/referrals
Example body
{ "action": "claim", "code": "abc123" }
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/referrals' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{ "action": "claim", "code": "abc123" }'
Response: { "code": "abc123", "link": "https://cloudcode.gg/?ref=abc123", "invited": 2, "rewarded": 1, "credits_earned": 100, "credits": 100, "max_rewards": 25 }
Errors: 400 invalid JSON or unknown action · 401 · 422 { ok: false, reason } the code can't be claimed

Admin

2
GET

Admin Analytics

auth

Aggregated platform analytics (admin role required). Actions: overview, page_views_timeseries, top_pages, traffic_sources, users_timeseries, recent_users, projects_stats. Optional ?range=<days> (1–365, default 30). POST ?action=refund_credits refunds credits for a lost run (one refund per run reference; admin only).

GEThttps://cloudcode.gg/api/functions/v1/admin-analytics?action=overview
cURL
curl -X GET 'https://cloudcode.gg/api/functions/v1/admin-analytics?action=overview' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
Errors: 400 Unknown action · 401 · 403 not an admin
POST

Seed Demo Data

auth

Reset and re-seed the shared demo accounts (alice/bob/carol@demo.cc) with demo projects, workspaces, and files. Requires an admin user's access token or the service-role key.

POSThttps://cloudcode.gg/api/functions/v1/seed-demo-data
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/seed-demo-data' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
Errors: 401 · 403 Admin role required · 405 non-POST

Marketing

4
POST

Notify Contact

public

Forward a contact-form submission to the team and send an auto-reply to the submitter (email via Resend).

POSThttps://cloudcode.gg/api/functions/v1/notify-contact
Example body
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "subject": "Question",
  "message": "Hi there"
}
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/notify-contact' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Jane Doe", "email": "jane@example.com", "subject": "Question", "message": "Hi there" }'
Response: { "ok": true }
POST

Confirm Subscription — Send

public

Send a "you're subscribed" welcome email (with a one-click unsubscribe link) to a newsletter subscriber via Resend. This endpoint only sends the email; the address must already be in the subscription list, and there is no confirmation step.

POSThttps://cloudcode.gg/api/functions/v1/confirm-subscription
Example body
{ "email": "subscriber@example.com" }
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/confirm-subscription' \
  -H 'Content-Type: application/json' \
  -d '{ "email": "subscriber@example.com" }'
Response: { "ok": true }
Errors: 400 invalid email · 404 email is not subscribed
GET

Confirm Subscription — Unsubscribe

public

One-click unsubscribe link target. The token is an HMAC of the email generated when the welcome email is sent. Removes the email from the newsletter list and returns an HTML confirmation page.

GEThttps://cloudcode.gg/api/functions/v1/confirm-subscription?action=unsubscribe&email=user@example.com&token=<hmac>
cURL
curl -X GET 'https://cloudcode.gg/api/functions/v1/confirm-subscription?action=unsubscribe&email=user@example.com&token=<hmac>'
Response: text/html
Errors: 400 missing or invalid email · 403 invalid token
GET

Unsubscribe from Tips

public

One-click unsubscribe link in CloudCode's tip emails. The token is an HMAC of the user id. GET returns an HTML confirmation page; POST with the same query is the RFC 8058 List-Unsubscribe-Post that mail clients send. Either turns off "Tips for your projects" (Settings → Notifications).

GEThttps://cloudcode.gg/api/functions/v1/unsubscribe?u=<user id>&t=<token>
cURL
curl -X GET 'https://cloudcode.gg/api/functions/v1/unsubscribe?u=<user id>&t=<token>'
Response: text/html
Errors: 400 missing or invalid link

Integrations

2
POST

MCP Connector

auth

Model Context Protocol endpoint (streamable HTTP) for Claude Code, claude.ai, Claude Desktop, Cursor and other MCP clients. Add the URL to your client and it discovers OAuth on its own: you sign in at /oauth/login and approve the client at /oauth/consent. No token to copy. Tools run as you, so row-level security applies. Tools: list_projects, get_project, list_project_files, read_project_file, search_files, get_file_history, write_file, edit_file, create_project, update_project, delete_project, list_checkpoints, create_checkpoint, restore_checkpoint, list_file_comments, add_file_comment, resolve_file_comment, list_env_vars, set_env_var, delete_env_var (secret values are never returned), check_vulnerabilities, list_deployments, deploy_project, run_agent (billed to your credits), get_credit_balance. See the MCP section in the Docs for setup.

POSThttps://cloudcode.gg/functions/v1/mcp
Example body
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
cURL
curl -X POST 'https://cloudcode.gg/functions/v1/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <OAUTH_ACCESS_TOKEN>' \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'
POST

Telegram Webhook

public

Inbound webhook for the @cloudcode_agent_bot Telegram bot. Verified via X-Telegram-Bot-Api-Secret-Token header — not callable directly. The Telegram bot is temporarily unavailable.

POSThttps://cloudcode.gg/api/functions/v1/telegram-webhook
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/telegram-webhook'

Public API

12
GET

Me

auth

Return the authenticated user_id, auth method, and granted scopes (null for a signed-in session or MCP OAuth token, which has full access). No scope required — use this to verify a cc_live_… key works.

GEThttps://cloudcode.gg/api/functions/v1/cc-api/v1/me
cURL
curl -X GET 'https://cloudcode.gg/api/functions/v1/cc-api/v1/me' \
  -H 'Authorization: Bearer cc_live_<YOUR_KEY>'
Response: { "user_id": "uuid", "auth_method": "api_key", "scopes": ["projects:read", "files:read"] }
GET

List Projects

auth

List the caller's projects, most recently updated first. Requires scope projects:read. Optional ?limit= (1–200, default 50).

GEThttps://cloudcode.gg/api/functions/v1/cc-api/v1/projects
cURL
curl -X GET 'https://cloudcode.gg/api/functions/v1/cc-api/v1/projects?limit=20' \
  -H 'Authorization: Bearer cc_live_<YOUR_KEY>'
Response: { "projects": [{ "id", "name", "description", "status", "is_starred", "github_repo_url", "created_at", "updated_at" }] }
Errors: 403 missing scope
POST

Create Project

auth

Create a project owned by the caller. Requires scope projects:write. name is required; description defaults to "".

POSThttps://cloudcode.gg/api/functions/v1/cc-api/v1/projects
Example body
{
  "name": "My App",
  "description": "Optional description",
  "github_repo_url": null
}
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/cc-api/v1/projects' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer cc_live_<YOUR_KEY>' \
  -d '{ "name": "My App", "description": "Optional description", "github_repo_url": null }'
Response: 201 { "project": { ... } }
Errors: 400 name is required · 403 missing scope
GET

Get Project

auth

Fetch a single project (all columns) by id. Requires scope projects:read.

GEThttps://cloudcode.gg/api/functions/v1/cc-api/v1/projects/:id
cURL
curl -X GET 'https://cloudcode.gg/api/functions/v1/cc-api/v1/projects/<PROJECT_ID>' \
  -H 'Authorization: Bearer cc_live_<YOUR_KEY>'
Response: { "project": { ... } }
Errors: 403 missing scope · 404 project not found
GET

List Files

auth

List all files in a project, sorted by path (metadata only, no content). Requires scope files:read.

GEThttps://cloudcode.gg/api/functions/v1/cc-api/v1/projects/:id/files
cURL
curl -X GET 'https://cloudcode.gg/api/functions/v1/cc-api/v1/projects/<PROJECT_ID>/files' \
  -H 'Authorization: Bearer cc_live_<YOUR_KEY>'
Response: { "files": [{ "id", "path", "language", "updated_at" }] }
Errors: 403 missing scope · 404 project not found
PUT

Upsert File

auth

Create or replace a file by path. Requires scope files:write. path is required; content defaults to "" and language to "text". Returns 200 when an existing file was updated, 201 when a new file was created.

PUThttps://cloudcode.gg/api/functions/v1/cc-api/v1/projects/:id/files
Example body
{
  "path": "src/App.tsx",
  "content": "export default function App() { return null; }",
  "language": "typescript"
}
cURL
curl -X PUT 'https://cloudcode.gg/api/functions/v1/cc-api/v1/projects/<PROJECT_ID>/files' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer cc_live_<YOUR_KEY>' \
  -d '{ "path": "src/App.tsx", "content": "export default function App() { return null; }", "language": "typescript" }'
Response: 200 | 201 { "file": { ... } }
Errors: 400 path is required · 403 missing scope · 404 project not found
GET

Get File

auth

Fetch one file, including content, by its URL-encoded path (e.g. src%2FApp.tsx). Requires scope files:read.

GEThttps://cloudcode.gg/api/functions/v1/cc-api/v1/projects/:id/files/:path
cURL
curl -X GET 'https://cloudcode.gg/api/functions/v1/cc-api/v1/projects/<PROJECT_ID>/files/src%2FApp.tsx' \
  -H 'Authorization: Bearer cc_live_<YOUR_KEY>'
Response: { "file": { "id", "path", "language", "content", "updated_at" } }
Errors: 400 malformed path encoding · 403 missing scope · 404 project or file not found
DELETE

Delete File

auth

Delete a file by its URL-encoded path. Requires scope files:write. Returns ok even if no file existed at that path.

DELETEhttps://cloudcode.gg/api/functions/v1/cc-api/v1/projects/:id/files/:path
cURL
curl -X DELETE 'https://cloudcode.gg/api/functions/v1/cc-api/v1/projects/<PROJECT_ID>/files/src%2FApp.tsx' \
  -H 'Authorization: Bearer cc_live_<YOUR_KEY>'
Response: { "ok": true }
Errors: 400 malformed path encoding · 403 missing scope · 404 project not found
GET

List Deployments

auth

The 20 most recent deployments for a project, newest first. Requires scope deploy.

GEThttps://cloudcode.gg/api/functions/v1/cc-api/v1/projects/:id/deployments
cURL
curl -X GET 'https://cloudcode.gg/api/functions/v1/cc-api/v1/projects/<PROJECT_ID>/deployments' \
  -H 'Authorization: Bearer cc_live_<YOUR_KEY>'
Response: { "deployments": [{ "id", "provider", "environment", "status", "deployment_url", "preview_url", "created_at" }] }
Errors: 403 missing scope · 404 project not found
POST

Trigger Deployment

auth

Deploy the project's current files to Vercel via deploy-vercel. Requires scope deploy. environment defaults to "production" (any other value is a preview deploy); deployType is "static" (default) or "node". The Vercel project name is derived from your account and the project (projectName is ignored), and the project's env vars for the environment are sent with the deploy. The call waits for the Vercel build (up to ~5 minutes) and records the result in the project's deployments.

POSThttps://cloudcode.gg/api/functions/v1/cc-api/v1/projects/:id/deployments
Example body
{
  "environment": "production",
  "deployType": "static"
}
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/cc-api/v1/projects/<PROJECT_ID>/deployments' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer cc_live_<YOUR_KEY>' \
  -d '{ "environment": "production", "deployType": "static" }'
Response: 202 { "deployment": { ..., "status": "ready", "deployment_url": "https://…" }, "result": { "url", "id", "readyState", "deployType" } }
Errors: 400 project has no files · 403 missing scope · 404 project not found · 502 { deployment, error } when the deploy fails · 500
POST

AI Chat

auth

Non-streaming chat completion via Vercel AI Gateway (OpenAI-compatible). Requires scope agent:run. messages is required; model takes the Gemini and GPT ids listed under AI Agent and defaults to google/gemini-3-flash-preview (Claude models return 400). Billed in credits by the tokens used. Returns 402 { code: "INSUFFICIENT_CREDITS", error: "You're out of credits", balance } before calling the model when the account has less than 1 credit, and 503 { code: "BILLING_UNAVAILABLE" } if billing can't be checked. On success the gateway's JSON response is returned; gateway failures return fixed messages (429 rate limited, 402 "AI credits exhausted", 502 otherwise).

POSThttps://cloudcode.gg/api/functions/v1/cc-api/v1/ai/chat
Example body
{
  "model": "google/gemini-2.5-flash",
  "messages": [{ "role": "user", "content": "Hello" }],
  "max_tokens": 512,
  "temperature": 0.7
}
cURL
curl -X POST 'https://cloudcode.gg/api/functions/v1/cc-api/v1/ai/chat' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer cc_live_<YOUR_KEY>' \
  -d '{ "model": "google/gemini-2.5-flash", "messages": [{ "role": "user", "content": "Hello" }], "max_tokens": 512, "temperature": 0.7 }'
Response: OpenAI-style chat completion: { "choices": [{ "message": { "role": "assistant", "content": "..." } }], ... }
Errors: 400 messages[] is required, or a Claude model · 402 out of credits · 403 missing scope · 429 rate limited · 500 AI gateway not configured · 502 AI service error
GET

List GitHub Repos

auth

List up to 100 of your GitHub repos (most recently updated first) using your linked GitHub account. Requires scope projects:read or deploy.

GEThttps://cloudcode.gg/api/functions/v1/cc-api/v1/github/repos
cURL
curl -X GET 'https://cloudcode.gg/api/functions/v1/cc-api/v1/github/repos' \
  -H 'Authorization: Bearer cc_live_<YOUR_KEY>'
Response: { "github_user": "login", "repos": [{ "id", "name", "full_name", "private", "html_url", "default_branch", "updated_at" }] }
Errors: 403 missing scope · 412 no GitHub account linked · GitHub error status passed through