Source Code & Uploads

#Download Source Code

A short-lived link to the project's current code as an archive. With the project's .env (Get Project Env) it runs locally with npm ci && npm run dev. Downloading source code is included on paid plans.

Path parameters

Query parameters

Response fields

Example request

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

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

{ "errors": null, "data": { "filesCount": 96, "lastCommitSha": "9f2c1ab4d3e5f60718293a4b5c6d7e8f90a1b2c3", "downloadUrl": "https://files.totalum.app/source/barber-bookings.tar.gz?sig=…" } }

Error codes

#Upload File

Upload one file (up to 20 MB) as multipart/form-data with the field file. Use the returned url in inputFiles of Run AI Agent. For a bigger file, pass its own public URL in inputFiles instead; no upload is needed.

Path parameters

Body parameters(multipart/form-data)

Response fields

Example request

curl -X POST \
  -H "api-key: tlm_sk_your_key" \
  -F "file=@./logo.png" \
  https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/files/upload

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("./logo.png")]), "logo.png");

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

{
  "errors": null,
  "data": {
    "fileNameId": "p/barber-bookings/01JC8Z3K4M5N6P7Q8R9S0T1V2W.png",
    "url": "https://files.totalum-project.com/p/barber-bookings/01JC8Z3K4M5N6P7Q8R9S0T1V2W.png",
    "createdAt": "2026-11-01T10:15:00.000Z"
  }
}

Error codes

#List Files

The files stored in the project, newest first: the ones uploaded through Upload File and the ones the app itself stored. Projects on the new engine only; a legacy project answers 400 ENGINE_NOT_SUPPORTED.

Path parameters

Query parameters

Response fields

Example request

curl -H "api-key: tlm_sk_your_key" \
  "https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/files?type=image&limit=20"

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

{
  "errors": null,
  "data": {
    "items": [
      {
        "key": "p/barber-bookings/01JC8Z3K4M5N6P7Q8R9S0T1V2W.png",
        "fileName": "logo.png",
        "fileSize": 48213,
        "contentType": "image/png",
        "visibility": "public-by-link",
        "createdAt": "2026-11-01T10:15:00.000Z"
      }
    ],
    "nextCursor": null
  }
}

Error codes

#Delete Files

Delete stored files by key, for example when a user asks you to erase their documents. Up to 100 keys per call. Free at any balance, and safe to repeat: a key that is already deleted (or never existed) comes back in notFound, not as an error. Projects on the new engine only; a legacy project answers 400 ENGINE_NOT_SUPPORTED.

What happens to a deleted file

• Its public URL stops being served everywhere within 1 hour: a location of Cloudflare's network that cached the file can keep serving its copy for up to 1 hour after the delete, then the URL answers 410 Gone (404 once the recovery copy is gone). A browser that already downloaded the file can keep its own copy for up to 1 hour after that download.
• Signed URLs to it stop working at once, including the ones created before the delete.
• It disappears from List Files and stops counting toward the project's storage.
• A recovery copy is kept for 30 days, then removed for good (the nightly backup copy too).
• Deleting the project deletes all of its files.

Path parameters

Body parameters

Response fields

Example request

curl -X DELETE \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["p/barber-bookings/01JC8Z3K4M5N6P7Q8R9S0T1V2W.png"]}' \
  https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/files

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/files", {
  method: "DELETE",
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "keys": [
      "p/barber-bookings/01JC8Z3K4M5N6P7Q8R9S0T1V2W.png"
    ]
  }),
});
const { errors, data } = await res.json();

{
  "errors": null,
  "data": {
    "deleted": ["p/barber-bookings/01JC8Z3K4M5N6P7Q8R9S0T1V2W.png"],
    "notFound": []
  }
}

{
  "errors": {
    "errorCode": "FILE_KEY_FORBIDDEN",
    "errorMessage": "Not files of project barber-bookings: p/other-project/01JC8Z3K4M5N6P7Q8R9S0T1V2X.pdf",
    "errorDetails": { "keys": ["p/other-project/01JC8Z3K4M5N6P7Q8R9S0T1V2X.pdf"] }
  },
  "data": null
}

Error codes