Totalum API for AI Agents

#What Totalum is

Totalum turns a natural-language prompt into a working, hosted, full-stack web app, and keeps changing it with more prompts. You call the API; Totalum's own AI coding agent writes the app; Totalum builds it, gives it a preview, publishes it, and runs it. There is no infrastructure to set up and no key to configure for the built-in features.

• Base URL: https://builder-api.totalum.app/api/v1/vcaas (https://api-accounts.totalum.app answers the same paths).
• Auth: header api-key: tlm_sk_… on every request. Call the API from a server only; never put the key in browser or mobile code.
• Envelope: { "errors": null, "data": … }, or { "errors": { "errorCode", "errorMessage", "errorDetails?" }, "data": null }. Branch on errorCode.
• Async: a prompt and a publish answer at once; poll their status every 10–15 seconds.
• Ids: always use the projectId the API returns (a taken id gets a random suffix).
• Legacy projects: projects created before 8 October 2026, or without the v2 engine, are legacy projects and do not have every endpoint below — see https://www.totalum.app/docs/api/migration-v2.

#What a generated app is

A standard Next.js app (App Router, React, TypeScript, Tailwind CSS) running on Cloudflare Workers, with:

• Its own SQL database (SQLite on Cloudflare D1, used through Drizzle ORM), in two environments: dev (agent + preview) and live (published site). Schema changes are migrations; a publish applies them to live. A database can be moved to Turso past 10 GB. Nightly backups on paid plans, 30-day point-in-time restore.
• Sign-in (e-mail + password, password reset, Google), with the owner as admin.
• Built-in features through totalum-sdk — no keys: e-mail, AI (chat, structured output, vision, images, video, speech, embeddings), file storage, document scanning (OCR), web scraping and search, a cloud browser, PDFs, payments (the owner's Stripe account), real-time channels, scheduled jobs, vector search, logs, site analytics, SEO.
• Mobile apps (Android and iOS, paid plans) from the same web app: a shell that opens the published site, built by Totalum and sent to the stores with the owner's own Google Play and Apple developer accounts.
• The code is the owner's: downloadable, syncable to GitHub, runnable locally.

To use a feature, say it in the prompt ("send me an e-mail on every booking", "take card payments", "let users upload photos"). For another service, add its key as a secret and name it in the prompt.

#The development cycle

launch ─▶ status "done" ─▶ preview ─▶ prompt ─▶ … ─▶ publish ─▶ live site

1. POST /projects/launch — create the project and run the first prompt.
2. GET /projects/:projectId/agent/status every 10–15 s until status is "done" (show GET …/agent/progress meanwhile).
3. GET /projects/:projectId → temporalDevelopmentProjectUrl is the preview. Read it again after every prompt.
4. More prompts: POST /projects/:projectId/agent/start, then poll again.
5. POST /projects/:projectId/deployments/deploy → poll GET …/deployments/status until "success" → the live site is productionProjectUrl (<projectId>.totalum-project.com, <projectId>.webapp-project.com when chosen as the main address with PATCH /projects/:projectId {"liveHostSuffix":"webapp-project.com"} on Professional/Enterprise, where both addresses serve the site, or the custom domain).
   • No "totalum" in the address: projects created on Professional/Enterprise start on <projectId>.webapp-project.com (pick with liveHostSuffix at create/launch); for an older project set PATCH /projects/:projectId {"liveHostSuffix":"webapp-project.com"} (the app's emails then also come from p-<projectId>@mail.webapp-project.com), or attach a custom domain (PUT /projects/:projectId/domain) or buy one (Custom Domains). Domains are per project; an account-wide domain for all projects is not supported.

Prompts, file edits and restores change dev only (each code change is a version); only a publish changes live. One prompt, publish or restore runs at a time per project (409 AGENT_RUNNING, DEPLOYMENT_RUNNING, OPERATION_IN_PROGRESS).

#Limits and credits

• Every plan can use the API. Everything is paid in credits; spending actions need a balance of at least 1 credit (403 VCAAS_INSUFFICIENT_CREDITS, 402 INSUFFICIENT_CREDITS).
• A prompt costs at least 3 credits, usually 3–50, by the work done; a failed run that built nothing is refunded. Fixed prices (create 2, publish 0.5, …) and monthly fees: GET /credit-costs.
• A prompt's agent works up to about 40 minutes, then wraps up and saves; most prompts take a few minutes. Prompt ≤ 40,000 characters, ≤ 10 attachments.
• Projects per plan: Free 2, Starter 10, Builder 50, Professional 300, Enterprise unlimited (403 MAX_PROJECTS_REACHED); creation rate per plan (429 RATE_LIMIT_EXCEEDED).
• JSON body ≤ 1 MB; upload ≤ 20 MB. Project caps: PATCH /projects/:projectId/credit-limits (defaults for API projects: development 5,000 and infrastructure 300 credits a month; set creditLimits at create; every project's development environment — preview, its database and jobs — is capped at 100 credits a month, maxDevInfrastructureCreditsPerMonth; at it only the preview stops and the next prompt resumes it). A cap is > 0 or null; 0 is refused.
• The running app: 100 built-in calls a second per project, 20 paid AI/web calls a minute per visitor.

Full list: https://www.totalum.app/docs/api/errors

#Essential endpoints

#Launch Project

Create a project and start building it with its first prompt, in one call. Secrets, attachments, credit limits and a Figma token sent here are in place before the first build starts, which is the order the build needs.

Body parameters

Response fields

Example request

curl -X POST \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"barber-bookings","prompt":"Build a booking site for a barbershop with online payments","label":"Barber bookings","creditLimits":{"maxDevelopmentCreditsPerMonth":500}}' \
  https://builder-api.totalum.app/api/v1/vcaas/projects/launch

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects/launch", {
  method: "POST",
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "projectId": "barber-bookings",
    "prompt": "Build a booking site for a barbershop with online payments",
    "label": "Barber bookings",
    "creditLimits": {
      "maxDevelopmentCreditsPerMonth": 500
    }
  }),
});
const { errors, data } = await res.json();

{
  "errors": null,
  "data": {
    "projectId": "barber-bookings",
    "description": "",
    "plan": "api",
    "createdAt": "2026-10-08T10:30:00.000Z",
    "label": "Barber bookings",
    "dataResidency": "global",
    "creditLimits": { "maxDevelopmentCreditsPerMonth": 500, "maxInfrastructureCreditsPerMonth": 300 },
    "files": [],
    "secrets": [],
    "agent": {
      "started": true,
      "status": "init",
      "runId": "run_01k6x8m2c9",
      "message": "Process started. Estimated time: about 9 minutes. This is only an approximation…",
      "expectedMinutes": 9,
      "expectedFinishAt": "2026-10-08T10:39:00.000Z"
    },
    "warnings": [],
    "engineVersion": "v2"
  }
}

Error codes

Nothing is created or charged for any of these.

#Run AI Agent

Send one prompt to the agent (or a multi-prompt batch). One run at a time per project. Once the running prompt's change is in the preview and the run is only finishing, the next prompt is accepted and waits: it starts as soon as that run ends. One prompt can wait; Stop Agent cancels the waiting one first.

A prompt is priced by the work the agent does: at least 3 credits, usually 3 to 50. A question that changes nothing is answered in seconds for 3 credits and creates no version. A run that fails without producing anything is refunded. The agent works up to about 40 minutes on one prompt, then wraps up and saves what it built; most prompts take a few minutes.

Path parameters

Body parameters

¹ Not needed when multiPrompt.prompts is given. ² Exactly one of prompts or letTotalumDecide: true.

fastMode and effort are accepted for compatibility and ignored (an ignored option is listed in data.warnings; the run still starts).

#Agent tiers

With "auto", the run's final message carries autoMode: true and modelUsed: the tier that ran ("cheap", "normal" or "expensive"), charged as that tier.

Response fields

Example request

curl -X POST \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Add a contact form that emails me every message"}' \
  https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/agent/start

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/agent/start", {
  method: "POST",
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "prompt": "Add a contact form that emails me every message"
  }),
});
const { errors, data } = await res.json();

{
  "errors": null,
  "data": {
    "projectId": "barber-bookings",
    "status": "init",
    "message": "Process started. Estimated time: about 6 minutes. This is only an approximation… Fetch GET /api/v1/vcaas/projects/barber-bookings/agent/status every 10-15 seconds to track progress; the status there is the only reliable signal that the run has finished.",
    "expectedMinutes": 6,
    "expectedFinishAt": "2026-10-08T11:16:00.000Z",
    "runId": "run_01k6xc4n7d"
  }
}

Error codes

#Get Agent Status

Whether a prompt is running, and the messages of the current (or last) run. Poll every 10–15 seconds. When status becomes "done", read the preview URL again from Get Project.

Path parameters

Response fields

Example request

curl -H "api-key: tlm_sk_your_key" \
  https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/agent/status

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/agent/status", {
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
  },
});
const { errors, data } = await res.json();

{
  "errors": null,
  "data": {
    "projectId": "barber-bookings",
    "status": "done",
    "startedAt": "2026-10-08T11:10:00.000Z",
    "realtimeConversation": [
      {
        "author": "agent",
        "message": "Added a contact form on /contact. Every message is saved and e-mailed to you. I sent a test message: saved, 200.",
        "messageType": "finished",
        "versionId": "ver_01k6xd2m8q",
        "createdAt": "2026-10-08T11:15:40.000Z",
        "autoMode": true,
        "modelUsed": "normal"
      }
    ],
    "creditsSpent": 7.4,
    "expectedMinutes": null,
    "expectedFinishAt": null,
    "multiPrompt": null,
    "runId": "run_01k6xc4n7d"
  }
}

#Get Agent Progress

A step-by-step view of the current run (or the last one): its stage, the files it changed, the builds and checks it ran. Use it to show a live "building" timeline. data is null before the first run.

Path parameters

Response fields

Example request

curl -H "api-key: tlm_sk_your_key" \
  https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/agent/progress

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/agent/progress", {
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
  },
});
const { errors, data } = await res.json();

{
  "errors": null,
  "data": {
    "runId": "run_01k6xc4n7d",
    "state": "running",
    "stage": "working",
    "startedAt": "2026-10-08T11:10:00.000Z",
    "turns": 12,
    "steps": [
      { "at": "2026-10-08T11:12:01.000Z", "kind": "edit", "file": "src/app/contact/page.tsx", "added": 64, "removed": 0 },
      { "at": "2026-10-08T11:12:30.000Z", "kind": "command", "task": "database", "ok": true }
    ],
    "totalSteps": 18,
    "files": [{ "path": "src/app/contact/page.tsx", "change": "create", "added": 64, "removed": 0 }],
    "counts": { "reads": 6, "searches": 2, "edits": 4, "commands": 3, "failedCommands": 0 }
  }
}

#Get Project

Everything about one project: its URLs, the agent's state, the last publish, its domain, secrets and spending. Read it again after every prompt: the preview address can change.

Path parameters

Response fields

Example request

curl -H "api-key: tlm_sk_your_key" \
  https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings", {
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
  },
});
const { errors, data } = await res.json();

{
  "errors": null,
  "data": {
    "projectId": "barber-bookings",
    "label": "Barber bookings",
    "description": "",
    "plan": "api",
    "agentProcessStatus": "done",
    "createdAt": "2026-10-08T10:30:00.000Z",
    "agentServerStatus": "Active",
    "deployment": { "createdAt": "2026-10-08T11:02:00.000Z", "status": "success", "versionId": "ver_01k6xd2m4n6p8q0r2s4t6v8w0y" },
    "versionRecovery": null,
    "importInProgress": null,
    "secrets": [{ "_id": "sec_01k6x9", "secretName": "STRIPE_KEY", "environment": "production" }],
    "customDomain": null,
    "developmentUrlFieldToUse": "temporalDevelopmentProjectUrl",
    "temporalDevelopmentProjectUrl": "https://barber-bookings-dev-temporal-link-preview-k3y9x2ab.totalum-project.com",
    "productionProjectUrl": "barber-bookings.totalum-project.com",
    "totalCreditsSpent": 24.6,
    "creditLimits": { "maxDevelopmentCreditsPerMonth": 500, "maxInfrastructureCreditsPerMonth": 300 },
    "multiPrompt": null,
    "engineVersion": "v2",
    "engineState": "ready",
    "dataResidency": "global",
    "sandbox": { "state": "active", "lastPromptAt": "2026-10-08T10:30:05.000Z" },
    "preview": { "url": "https://barber-bookings-dev-temporal-link-preview-k3y9x2ab.totalum-project.com", "token8": "k3y9x2ab", "status": "live", "deployState": "idle" },
    "lastDeployError": null,
    "currentRun": null,
    "state": "active",
    "pausedAt": null,
    "resumable": false,
    "contextClearPending": false,
    "operations": []
  }
}

Error codes

#List Projects

Your projects, newest first, up to 100 per page. The total is in the X-Total-Count header and X-Has-More says whether another page exists.

Query parameters

Response fields

Example request

curl -H "api-key: tlm_sk_your_key" \
  "https://builder-api.totalum.app/api/v1/vcaas/projects?limit=20&sortField=lastModified"

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects?limit=20&sortField=lastModified", {
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
  },
});
const { errors, data } = await res.json();

{
  "errors": null,
  "data": [
    {
      "projectId": "barber-bookings",
      "description": "",
      "plan": "api",
      "createdAt": "2026-10-08T10:30:00.000Z",
      "label": "Barber bookings",
      "previewImageUrl": "https://files.totalum.app/previews/barber-bookings.png",
      "lastModifiedAt": "2026-10-08T10:41:00.000Z",
      "productionProjectUrl": "barber-bookings.totalum-project.com",
      "engineVersion": "v2"
    }
  ]
}

#Deploy to Production

Publish the project's current version. It takes about 2 to 5 minutes. If the build or a migration fails, Totalum's agent tries to repair it once or twice before the publish ends in error; the live site keeps serving the previous version until a publish succeeds.

Migrations that delete data. A migration that drops a table or column, or deletes or overwrites existing live rows, runs only when the prompt that made it asked for it, or when you publish with confirmDestructive: true. Otherwise the publish ends in error with DESTRUCTIVE_MIGRATION_NEEDS_CONFIRMATION and nothing changes on live. Rows already in the live database that break a new rule end the publish with the list of those rows; Totalum never changes production data on its own.

Path parameters

Body parameters

Response fields

Example request

curl -X POST -H "api-key: tlm_sk_your_key" \
  https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/deployments/deploy

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/deployments/deploy", {
  method: "POST",
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
  },
});
const { errors, data } = await res.json();

{
  "errors": null,
  "data": {
    "projectId": "barber-bookings",
    "status": "deploying",
    "message": "Deployment started. It will take from 2 to 5 minutes depending on project size. Fetch GET /api/v1/vcaas/projects/barber-bookings/deployments/status every 10-15 seconds to track progress.",
    "deploymentId": "dep_01k6xf3a9b"
  }
}

Error codes

#Get Deployment Status

The newest publish and where it is. Poll every 10–15 seconds until status is "success" or "error".

Path parameters

Response fields

Example request

curl -H "api-key: tlm_sk_your_key" \
  https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/deployments/status

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/deployments/status", {
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
  },
});
const { errors, data } = await res.json();

{
  "errors": null,
  "data": {
    "status": "success",
    "createdAt": "2026-10-08T11:20:00.000Z",
    "deploymentId": "dep_01k6xf3a9b",
    "step": "done",
    "liveUrl": "https://barber-bookings.totalum-project.com"
  }
}

When it is "success", the address to show is productionProjectUrl on Get Project (the custom domain once active).

#Create Project

Create an empty project: no prompt, nothing built. Use it only when you will import a project into it, connect GitHub first, or write the files yourself; otherwise use Launch Project.

The project is set up in the background (about 15 seconds); a write sent before it is ready waits for it.

Body parameters

Response fields

Example request

curl -X POST \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"crm-import","label":"CRM (imported)","creditLimits":{"maxDevelopmentCreditsPerMonth":1000,"maxInfrastructureCreditsPerMonth":500}}' \
  https://builder-api.totalum.app/api/v1/vcaas/projects

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects", {
  method: "POST",
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "projectId": "crm-import",
    "label": "CRM (imported)",
    "creditLimits": {
      "maxDevelopmentCreditsPerMonth": 1000,
      "maxInfrastructureCreditsPerMonth": 500
    }
  }),
});
const { errors, data } = await res.json();

{
  "errors": null,
  "data": {
    "projectId": "crm-import",
    "description": "",
    "plan": "api",
    "createdAt": "2026-10-08T10:30:00.000Z",
    "label": "CRM (imported)",
    "dataResidency": "global",
    "engineVersion": "v2",
    "engineState": "provisioning"
  }
}

Error codes

Project limits per plan:

#Everything else

Each link is the complete reference for one area: the page, and the same page as Markdown for agents.