Legacy Projects — What Differs

#What legacy projects do not have

These endpoints answer 400 ENGINE_NOT_SUPPORTED on a legacy project:

• Project state and control: Get Project State, Get Agent Progress, Pause / Resume, Rotate Preview URL.
• Agent settings: the project system prompt and custom MCP servers, Resume Multi-Prompt Batch.
• Database: backups, restore points, point-in-time restore and the move to Turso; Ask Database, Get Database Usage, Undo Agent Run Database Change.
• Operations: Get Project Logs, Get Project Usage, Get Site Analytics, Feature Limits, the per-visitor Rate Limit, Scheduled Jobs.
• Keys and files: project API keys and Get Project Env.
• Ship: Mobile Apps, Payments and the project webhook, Visual Edits, and attaching a domain bought on Totalum.
• Options: EU-only data (dataResidency: "eu" answers 400 DATA_RESIDENCY_UNAVAILABLE), the agent tiers (cheap, normal, expensive, auto).

#What behaves differently

Request-level refusals (ROUTE_NOT_FOUND, METHOD_NOT_ALLOWED, INVALID_JSON, PAYLOAD_TOO_LARGE) answer in the JSON envelope on the current engine only. On a legacy project, and on the older host api-accounts.totalum.app, 403 VCAAS_INSUFFICIENT_CREDITS answers { "error", "code" }, a secret that fails validation { "success": false, "message", "errors": [...] }, and INVALID_WEBHOOK_EVENT lists only agent.prompt.finished and project.credit_limit.reached (every event is still accepted on the current engine).

#The database endpoints

Only the database endpoints are a different set. Legacy projects keep the legacy database endpoints (a JSON query language over the legacy project database); current-engine projects use the SQL-shaped Database endpoints. Calling one set on the other engine's project answers 400 PROJECT_ENGINE_MISMATCH, and errorDetails.useEndpoint names the endpoint to call. Paths are relative to https://builder-api.totalum.app/api/v1/vcaas.

The three records routes keep their path; on a current-engine project their body is { env, table, data }.

{
  "errors": {
    "errorCode": "PROJECT_ENGINE_MISMATCH",
    "errorMessage": "This project uses the new engine. Use POST /projects/:projectId/database/rows instead of POST /projects/:projectId/database/query — see https://www.totalum.app/docs/api/migration-v2",
    "errorDetails": { "engine": "v2", "useEndpoint": "POST /projects/:projectId/database/rows", "docsUrl": "https://www.totalum.app/docs/api/migration-v2" }
  },
  "data": null
}

Side by side — paid orders of 100 or more, newest first:

- POST /projects/my-app/database/query
- {"tableName":"orders","queryOptions":{"_filter":{"status":"paid","total":{"gte":100}},"_sort":{"createdAt":-1},"_limit":20}}
+ POST /projects/my-app/database/rows
+ {"env":"live","table":"orders","filter":{"and":[{"column":"status","op":"eq","value":"paid"},{"column":"total","op":"gte","value":100}]},"sort":[{"column":"created_at","dir":"desc"}],"page":{"limit":20}}

#Creating a project on an engine

New projects are created on the current engine. Send "engineVersion": "v2" on Create or Launch Project to require it (a refusal creates nothing). "engineVersion": "legacy" still creates a legacy project for an integration that depends on the legacy database endpoints.

#Choose The Engine For New Projects

While the current engine is offered as an opt-in, this switch makes the account's new projects use it (read it with GET /api/v1/vcaas/account/v2-opt-in: { v2OptIn, available }, where available says whether the switch decides anything right now). The account's own key only.

Body parameters

Response fields

Example request

curl -X PUT \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"v2OptIn":true}' \
  https://builder-api.totalum.app/api/v1/vcaas/account/v2-opt-in

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/account/v2-opt-in", {
  method: "PUT",
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "v2OptIn": true
  }),
});
const { errors, data } = await res.json();

{ "errors": null, "data": { "v2OptIn": true } }

Error codes