AI Agent

#Run AI Agent

Start the AI agent with a prompt to build or modify your project. Supports two modes:

• Single-prompt (default, recommended): omit multiPrompt. One prompt, typically 5 to 40 minutes and 6 to 46 credits.

  5 to 40 minutes is the full envelope a run can take, from a one-line tweak to a large build, and it is also what the API's own message field quotes. Most prompts land well inside it; use the upper figure if you are writing a timeout.

• Multi-prompt (rare, opt-in): include multiPrompt. A sequential batch that runs unsupervised. Each prompt still takes 5 to 40 minutes and 6 to 46 credits, so a 10-prompt batch can run for several hours and burn hundreds of credits.

Path parameters

Body parameters

¹ prompt is required unless multiPrompt.prompts is provided (then it is ignored). ² When multiPrompt is present, exactly one of prompts (non-empty array, ≤ 50 items) or letTotalumDecide=true must be set.

model, effort and fastMode apply to every run the request starts, including each prompt of a multi-prompt batch. They only change how the agent runs — the prompt, the project and the results are otherwise identical. When you send none of them, Totalum's built-in routing already picks the best model and effort for each prompt (for example a lighter, cheaper model for questions and small changes), so most integrations should leave them out. Override only when you are sure: sonnet to force the cheaper model, fastMode when you are iterating live and want the answer sooner rather than cheaper. These options can never make a request fail: anything unavailable or invalid is dropped, the defaults apply, and data.warnings tells you what was ignored and why.

Response fields

Example request

# Single-prompt (recommended)
curl -X POST -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Create a landing page with a contact form","inputFiles":[]}' \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/agent/start

# Single-prompt on Sonnet with a lower effort level (quick question / small change)
curl -X POST -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Change the primary button colour to blue","model":"sonnet","effort":"medium"}' \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/agent/start

# Single-prompt on Opus with fast mode (same quality, faster, pricier)
curl -X POST -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Add a contact form that emails me","fastMode":true}' \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/agent/start

# Multi-prompt with explicit list
curl -X POST -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"multiPrompt":{"prompts":["Set up auth","Add a Stripe checkout","Wire up the dashboard"]}}' \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/agent/start

# Multi-prompt with Totalum planning
curl -X POST -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Build a full SaaS billing system with auth, Stripe, and a customer portal","multiPrompt":{"letTotalumDecide":true}}' \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/agent/start

{
  "errors": null,
  "data": {
    "projectId": "my-app",
    "status": "init",
    "message": "Process started, can take from 5 to 40 minutes. Fetch GET .../agent/status every 10-15 seconds to track progress."
  }
}

{
  "errors": null,
  "data": {
    "projectId": "my-app",
    "status": "init",
    "message": "Multi-prompt run started with 3 prompts. ⚠️ Multi-prompt mode is expensive and slow — only use it when a job genuinely requires multiple sequential AI runs. Each prompt typically takes 5 to 40 minutes and costs 6 to 46 credits...",
    "multiPrompt": { "totalPrompts": 3 }
  }
}

{
  "errors": { "errorCode": "AGENT_RUNNING", "errorMessage": "An agent is already running on this project" },
  "data": null
}

Error codes

#Get Agent Status

Poll to track agent progress and get real-time messages. Poll every 10–15 seconds.

Path parameters

Response fields

Example request

curl -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/agent/status

{
  "errors": null,
  "data": {
    "projectId": "my-app",
    "status": "init",
    "startedAt": "2026-03-11T10:35:00.000Z",
    "realtimeConversation": [
      {
        "author": "agent",
        "message": "Creating the project structure...",
        "messageType": "building",
        "createdAt": "2026-03-11T10:36:00.000Z"
      },
      {
        "author": "agent",
        "message": "Project built successfully!",
        "messageType": "finished",
        "versionId": "v_abc123",
        "gitDiffUrl": "https://...",
        "secretKeysNeeded": {
          "STRIPE_SECRET_KEY": { "isProvided": false, "description": "Required for processing payments" }
        },
        "createdAt": "2026-03-11T10:50:00.000Z"
      }
    ],
    "creditsSpent": 3.2,
    "multiPrompt": null
  }
}

{
  "errors": null,
  "data": {
    "projectId": "my-app",
    "status": "init",
    "startedAt": "2026-03-11T11:05:00.000Z",
    "realtimeConversation": [ /* messages from the whole batch */ ],
    "multiPrompt": {
      "status": "executing",
      "totalPrompts": 3,
      "currentPromptIndex": 1,
      "prompts": [
        { "order": 0, "prompt": "Set up auth",        "status": "done" },
        { "order": 1, "prompt": "Add Stripe checkout", "status": "executing" },
        { "order": 2, "prompt": "Wire up dashboard",   "status": "pending" }
      ],
      "startedAt": "2026-03-11T10:35:00.000Z",
      "updatedAt": "2026-03-11T11:05:00.000Z"
    }
  }
}

{
  "errors": { "errorCode": "PROJECT_NOT_FOUND", "errorMessage": "Project does not exist or you don't own it" },
  "data": null
}

Error codes

#Get Full Conversation

Retrieve the complete conversation history across all agent runs (not just the current one).

Path parameters

Response fields

Example request

curl -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/agent/full-conversation

{
  "errors": null,
  "data": {
    "projectId": "my-app",
    "conversation": [
      { "author": "user", "message": "Create a landing page", "messageType": "regular", "createdAt": "..." },
      { "author": "agent", "message": "Building project structure...", "messageType": "building", "createdAt": "..." },
      {
        "author": "agent",
        "message": "Project built successfully!",
        "messageType": "finished",
        "versionId": "v_abc123",
        "gitDiffUrl": "https://...",
        "secretKeysNeeded": {
          "STRIPE_SECRET_KEY": { "isProvided": false, "description": "Required for processing payments" }
        },
        "createdAt": "..."
      }
    ]
  }
}

{
  "errors": { "errorCode": "PROJECT_NOT_FOUND", "errorMessage": "Project does not exist or you don't own it" },
  "data": null
}

Error codes

#Stop Agent

Send a stop signal to a running agent.

Path parameters

Response fields

Example request

curl -X POST -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/agent/stop

{ "errors": null, "data": { "message": "Agent stop signal sent" } }

{
  "errors": { "errorCode": "NO_PROCESS_RUNNING", "errorMessage": "No agent process is currently running" },
  "data": null
}

Error codes

#Concurrency rules

• Only one heavy operation at a time per project. Six things count: an agent run, a deployment, a version recovery, a rebuild (started by POST /rebuild or by the visual editor), a GitHub pull, and a project import. Starting another while one runs answers 409 with the code that names it — AGENT_RUNNING, DEPLOYMENT_RUNNING, RECOVERY_RUNNING, REBUILD_RUNNING, GITHUB_PULL_RUNNING or IMPORT_IN_PROGRESS — and the message says what to poll.
• Two exceptions, on purpose: a server restart is allowed during a rebuild, a pull or an import (it is the way out of one that died), and a file write is allowed during a rebuild (the write is simply not in that build — rebuild again).
• If deploy or recover is called and the server is not active, it auto-starts (charges START_SERVER credits) and returns SERVER_NOT_READY. Poll GET /projects/:projectId until agentServerStatus is "Active", then retry.
• Agent start IS allowed during server operations (the backend waits internally).

#Complete integration flow

1. Create the project and start building it — POST /projects/launch, body { "projectId": "my-app", "prompt": "Build a SaaS landing page" }. One call. Async, takes 5 to 40 minutes. Use the projectId it returns (a taken name is auto-suffixed), and check agent.started and warnings.
   • Already have an empty project? Then start at step 2 instead: POST /projects/my-app/agent/start, body { "prompt": "..." }. That is the only case where the two calls are separate — see Launch Project.
2. Send follow-up prompts — POST /projects/my-app/agent/start, body { "prompt": "Add a pricing page" }. Same endpoint, same polling, for every change after the first.
3. Poll agent status (every 10–15s) — GET /projects/my-app/agent/status. "init" = working (show realtimeConversation), "done" = finished (creditsSpent = total). On "done", immediately call GET /projects/:projectId and refresh the preview URL.
   • 3.1 Refresh preview URL (on page load, page refresh, and after every prompt finishes) — GET /projects/my-app, read developmentUrlFieldToUse: use cachedDevelopmentUrl (static snapshot while the server is archived) or temporalDevelopmentProjectUrl (live dev server); default temporalDevelopmentProjectUrl if null/undefined. Reload the iframe when the URL changes.
4. Publish — POST /projects/my-app/deployments/deploy. Builds, deploys, and assigns a public URL. Takes 2 to 5 minutes.
5. Poll deployment status (every 10–15s) — GET /projects/my-app/deployments/status; on "success", get productionProjectUrl from GET /projects/my-app.
6. (Optional) Custom domain — PUT /projects/my-app/domain, body { "hostname": "app.yourdomain.com" }; configure the returned DNS records; poll customDomain.status until "active".

#Global error codes

All errors are shaped as { "errors": { "errorCode": "CODE", "errorMessage": "..." }, "data": null }.