AI Agent

The AI agent builds and modifies your project from natural-language prompts. Agent runs are asynchronous — you start a run, then poll for status. All endpoints require the api-key header.

#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, 10 to 30 minutes, 10 to 40 credits.
• Multi-prompt (rare, opt-in): include multiPrompt. A sequential batch that runs unsupervised. Each prompt still takes 10 to 30 minutes and 10 to 40 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.

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

# 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 10 to 30 minutes (10 to 40 credits). 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 10 to 30 minutes and costs 10 to 40 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: agent, deployment, version recovery, or server start.
• 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. Ensure project exists — POST /projects, body { "projectId": "my-app" }. Create one if the user doesn't already have a project.
2. Send prompt to AI agent — POST /projects/my-app/agent/start, body { "prompt": "Build a SaaS landing page" }. Async, takes 6–15 min.
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 1–3 min.
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 }.