Export & Import

#Export Project

Create an export and get its code. At most 5 exports an hour per project. The records exported are the live database's (a project never published exports none).

Path parameters

Body parameters

Response fields

Example request

curl -X POST \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"includeRecords":true}' \
  https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/export

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/export", {
  method: "POST",
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "includeRecords": true
  }),
});
const { errors, data } = await res.json();

{ "errors": null, "data": { "importCode": "barber-bookings-export-project-8f3b1c9a47e2d650b9114af0c7e3a2d1", "includeRecords": true, "message": "Export ready. Save the importCode (keep it secret) and pass it to import-project as importCode.", "includeFiles": true, "files": { "count": 12, "bytes": 3145728 } } }

Error codes

#Import Project

Import an export into this project, which must be new and empty. The imported project keeps this project's id: to give it an id of your choice, create the project with that id first (with sourceImportCode, so it is made on the code's engine). The data fills both the development and the live database; then the code is built. Runs in the background (a few minutes): poll Get Project until importInProgress is null. Prompts are refused (IMPORT_IN_PROGRESS) meanwhile.

Path parameters

Body parameters

Response fields

Example request

curl -X POST \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"importCode":"barber-bookings-export-project-8f3b1c9a47e2d650b9114af0c7e3a2d1"}' \
  https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings-copy/import

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings-copy/import", {
  method: "POST",
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "importCode": "barber-bookings-export-project-8f3b1c9a47e2d650b9114af0c7e3a2d1"
  }),
});
const { errors, data } = await res.json();

{ "errors": null, "data": { "projectId": "barber-bookings-copy", "status": "importing", "message": "Import started. Poll GET /api/v1/vcaas/projects/barber-bookings-copy every 10-15s until importInProgress is null, then until agentServerStatus='Active'. Prompting is blocked until the import finishes." } }

Error codes

#Migrate to the New Engine

Move a project built on the legacy engine to the new engine. It makes a new project, <projectId>v2 (with a few random letters added when that name is taken) or the id you pass as projectId in the body, and leaves the legacy project exactly as it is: it keeps working and serving its users until you switch. Needs the Starter plan or above.

What the new project gets:

• The data: the legacy database (its tables, fields and every record) is kept as a private file of the new project, legacy-database.json, and every uploaded file the records point at (a file field, or a storage link kept as text) is copied into the new project's storage (the records point at the copies). There is no limit on the number of uploaded files: the first 2,000 are copied during this call, and the rest in the background shortly after (filesPending counts them); until each one is copied, its record keeps pointing at the old file, which keeps working.
• Many-to-many relations: the legacy engine kept these links apart from the records; every link is copied too (manyToManyLinks counts them), and the agent turns each many-to-many relation into a join table of the new database.
• Private files stay private: the legacy engine served uploaded files only through signed, expiring links, so each one is copied as a private file of the new project (an ID card scan never gets a public URL). Its field holds { name, key, url: null, private: true }; the rebuilt app shows or downloads it through one of its own routes that checks the signed-in user and redirects to a short-lived signed URL, await totalum.files.getSignedUrl(key) (or totalum.files.presign(keys) for several; see Files). A file that was publicly reachable without a signature stays public.
• The secrets: the project's own secrets are copied with the same development and live values, stored encrypted on the new project before its first prompt, so the app reads them as before (process.env.NAME on the server). Their values never appear in the response or the agent's prompt; the response lists their names. The legacy Totalum API key and BETTER_AUTH_SECRET are not copied: the new project has its own.
• The code: the AI agent receives the legacy code, the legacy database structure and the legacy SDK reference, and rebuilds the same app on the new engine (pages, flows, design, sign-in; its users keep their accounts). It designs the SQL tables and moves every record into them with a data migration generated by code from legacy-database.json: on the development database during the run, on the live database when you first publish the new project. The databases hold only the app's own tables; legacy-database.json stays in the project's files.

What does not carry over, and the new engine's own rules:

• One field value can be at most 2 MB in the new database. Images or documents stored inline as base64 text in a field are larger than that: turn them into uploaded files in the legacy app before migrating.
• BETTER_AUTH_SECRET is not reused (the new project has its own), so anything encrypted with the old one does not move: users who had two-factor authentication must set it up again. Passwords keep working.
• Sessions do not carry over: every user signs in again once, on the new app.
• The new app's sign-in rules: a session lasts 7 days (renewed once a day while it is used), and on the published site 10 wrong passwords for one e-mail, or 30 from one IP address, lock that e-mail or address out for 15 minutes.

The legacy app keeps running, so its data keeps changing: until the new project's first publish, Refresh Migrated Data reads it again into legacy-database.json, for free.

It answers once the new project exists and its first prompt has started (this call can take a minute). Follow the agent with Get Agent Status on the new projectId. The migration fee is 15 credits, charged once. The AI rebuild that follows always runs on the top tier and is billed like a prompt: typically 60–80 credits more, depending on the app's size. If the migration cannot start, nothing is charged and no project is kept. Limits: up to 20,000 records and 20 MB of data, and up to 20 MB of code in total (a code file over 1 MB is skipped and counted in codeFilesSkipped). Custom domains, GitHub and Figma connections do not move: set them again on the new project. A secret the new engine cannot take (a name it reserves, such as one starting with TOTALUM_, or an empty value) is listed in secretsNotCopied: set it again under another name.

Path parameters

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-new"}' \
  https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/migrate-to-v2

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/migrate-to-v2", {
  method: "POST",
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "projectId": "barber-bookings-new"
  }),
});
const { errors, data } = await res.json();

{ "errors": null, "data": { "projectId": "barber-bookings-new", "sourceProjectId": "barber-bookings", "engineVersion": "v2", "creditsCharged": 15, "migrated": { "tables": 6, "records": 412, "files": 38, "filesNotCopied": 0, "filesPending": 0, "manyToManyLinks": 54, "codeFiles": 126, "codeFilesSkipped": 0, "secrets": ["STRIPE_SECRET_KEY", "RESEND_API_KEY"], "secretsNotCopied": [] }, "agent": { "started": true, "status": "init", "runId": "run_01m4b8w0d9", "expectedMinutes": 18, "message": "Process started. …" } } }

Error codes

#Refresh Migrated Data

The legacy app keeps working while its new version is being built, so its data keeps changing. Call this on the new project (the one Migrate to the New Engine made) to read the legacy project again, records, many-to-many links and files, into a fresh legacy-database.json (same file, same key). Files already copied are not copied again; new ones are, private as above (past 2,000 new files, in the background). The legacy project is only read. It costs nothing beyond the storage of the new files.

It works only before the new project's first publish: the live database is loaded from legacy-database.json after that publish, and from then on the live database is the app's data, so the call is refused (MIGRATION_ALREADY_PUBLISHED). To bring the development database up to date after a refresh, ask the agent: "Run scripts/legacy-data.ts again on dev with the refreshed legacy-database.json". The usual order: refresh, publish, then load the live data (the agent's final message tells you the exact prompt).

Path 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-new/migrate-to-v2/refresh-data

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

{ "errors": null, "data": { "projectId": "barber-bookings-new", "sourceProjectId": "barber-bookings", "snapshotKey": "pv/barber-bookings-new/…/legacy-database.json", "refreshed": { "tables": 6, "records": 431, "manyToManyLinks": 57, "files": 3, "filesAlreadyCopied": 38, "filesNotCopied": 0, "filesPending": 0 }, "message": "legacy-database.json now holds the legacy project as it is now. …" } }

Error codes