Project Files

#Get Project Tree

The project's files and folders, as a flat, sorted list. node_modules, .next, .git, dist and other build output are never included.

Path parameters

Query parameters

Response fields

Entries are sorted the way a file explorer shows them: folders before files, alphabetically, within each parent.

Example request

curl -H "api-key: tlm_sk_your_key" \
  "https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/files/tree?path=src/app&limit=100"

{
  "errors": null,
  "data": {
    "entries": [
      { "path": "src/app", "name": "app", "type": "folder", "depth": 1 },
      { "path": "src/app/layout.tsx", "name": "layout.tsx", "type": "file", "size": 1284, "depth": 2 },
      { "path": "src/app/page.tsx", "name": "page.tsx", "type": "file", "size": 3902, "depth": 2 }
    ],
    "totalEntries": 3,
    "offset": 0,
    "limit": 100,
    "hasMore": false,
    "commitSha": "a1b2c3d",
    "filesCount": 47
  }
}

Error codes

#Get File Content

The complete content of one file. Files up to 1 MB.

Path parameters

Query parameters

Response fields

Binary files (anything with a NUL byte in the first 8 KB) come back base64-encoded, so they survive a round trip through PUT /files/content.

Example request

curl -H "api-key: tlm_sk_your_key" \
  "https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/files/content?path=src/app/page.tsx"

{
  "errors": null,
  "data": {
    "path": "src/app/page.tsx",
    "name": "page.tsx",
    "size": 62,
    "encoding": "utf8",
    "content": "export default function Page() {\n  return <h1>Hello</h1>;\n}\n",
    "commitSha": "a1b2c3d"
  }
}

{
  "errors": {
    "errorCode": "FILE_NOT_FOUND",
    "errorMessage": "No file at \"src/app/missing.tsx\" in this project."
  },
  "data": null
}

Error codes

#Write File Content

Replace a file completely, or create it if it does not exist. Missing parent folders are created for you. Content up to 512 KB.

Every write is committed and snapshotted as a new version, and pushed to GitHub if the project is connected — so you can always roll back from Versions.

Path parameters

Body parameters

Response fields

Example request

curl -X PUT \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"path":"src/app/page.tsx","content":"export default function Page() {\n  return <h1>Hi</h1>;\n}\n"}' \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/files/content

{
  "errors": null,
  "data": {
    "path": "src/app/page.tsx",
    "bytesWritten": 58,
    "created": false,
    "commitSha": "d4e5f6a",
    "filesCount": 47,
    "rebuildRequired": true
  }
}

{
  "errors": {
    "errorCode": "INVALID_PATH",
    "errorMessage": "path must not contain \"..\""
  },
  "data": null
}

Error codes

#Rebuild Project

Rebuild the project and reload the server, so files you wrote become live. Asynchronous: it returns immediately and the rebuild continues in the background.

A rebuild is a cold build — the build cache is cleared first — so it usually takes 1 to 4 minutes. Poll GET /rebuild/status until status is "success" or "error".

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/rebuild

{
  "errors": null,
  "data": {
    "projectId": "my-app",
    "status": "rebuilding",
    "startedAt": "2026-08-02T09:14:03.120Z",
    "message": "Rebuild started. It usually takes 1-4 minutes. Poll GET /projects/:projectId/rebuild/status until status is \"success\" or \"error\"."
  }
}

Error codes

#Get Rebuild Status

Poll this after POST /rebuild. Every 10–15 seconds is plenty.

Path parameters

Response fields

"idle" means this project has never been rebuilt through the API.

Example request

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

{
  "errors": null,
  "data": {
    "projectId": "my-app",
    "status": "success",
    "startedAt": "2026-08-02T09:14:03.120Z",
    "finishedAt": "2026-08-02T09:16:41.902Z",
    "elapsedSeconds": 159,
    "livePreviewUrl": "https://my-app.totalum-project.com"
  }
}

{
  "errors": null,
  "data": {
    "projectId": "my-app",
    "status": "error",
    "startedAt": "2026-08-02T09:14:03.120Z",
    "finishedAt": "2026-08-02T09:15:22.418Z",
    "elapsedSeconds": 79,
    "errorCode": "REBUILD_FAILED",
    "errorMessage": "Failed to rebuild and reload: Type error in src/app/page.tsx"
  }
}

Error codes

A failed rebuild is reported as status: "error" in a 200 response, not as an HTTP error — the request to read the status succeeded, it is the rebuild that did not.