Versions

Browse your project's version history, see what changed, and roll back to an earlier state.

Every completed prompt produces a version — and so does every file write, GitHub pull and import. You can list the version history, read the exact changes a version introduced, and recover a previous version. All three require the api-key header.

#List Versions

GET/api/v1/vcaas/projects/:projectId/versionsFree

Get all project versions with pagination.

Path parameters

Parameter	Type	Description
`projectId`	string	The project ID

Query parameters

Field	Type	Required	Description
`limit`	number	No	Number of versions to return (default: 20)
`skip`	number	No	Number of versions to skip (default: 0)

Response fields

Field	Type	Description
`data.versions`	array	Array of version objects
`data.versions[]._id`	string	Version ID — use this for Recover Version
`data.versions[].name`	string	Version display name
`data.versions[].commitSha`	string \| undefined	Git commit this version points at — use this for Get Version Diff
`data.versions[].commitMessage`	string \| undefined	Git commit message
`data.versions[].prompt`	string \| undefined	The prompt that created this version
`data.versions[].gcsUploaded`	boolean \| undefined	Whether the version's snapshot finished uploading to long-term storage
`data.versions[].recoveredVersionId`	string \| undefined	Present when this version was produced by recovering another one — the id of the version that was restored
`data.versions[].createdAt`	string	ISO 8601 creation date
`data.versions[].updatedAt`	string	ISO 8601 last-modified date
`data.totalCount`	number	Total versions available

Two different identifiers

_id and commitSha are not interchangeable. Recovery takes the _id; the diff takes the commitSha. Both come from this response, and there is no lookup from one to the other.

Example request

bash

curl -H "api-key: tlm_sk_your_key" \
  "https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/versions?limit=20&skip=0"

Success · 200 OK

json

{
  "errors": null,
  "data": {
    "versions": [
      {
        "_id": "v_abc123",
        "name": "Version 3",
        "commitSha": "9f2c1ab",
        "commitMessage": "Added contact form",
        "prompt": "Add a contact form to the landing page",
        "gcsUploaded": true,
        "createdAt": "2026-03-11T10:45:00.000Z",
        "updatedAt": "2026-03-11T10:45:00.000Z"
      }
    ],
    "totalCount": 3
  }
}

Error · 404

json

{
  "errors": {
    "errorCode": "PROJECT_NOT_FOUND",
    "errorMessage": "Project does not exist or you don't own it"
  },
  "data": null
}

Error codes

Code	HTTP	Meaning
`MISSING_PROJECT_ID`	400	projectId is required
`PROJECT_NOT_FOUND`	404	Project does not exist or you don't own it

End of List VersionsNext endpointGETGet Version Diff

#Get Version Diff

GET/api/v1/vcaas/projects/:projectId/version-diffFree

The unified diff a single version introduced, as raw text — the same format git diff produces.

The sha is a query parameter, not a path segment

Every other version route is addressed by the version's _id, but a diff can only be produced from its commitSha and there is no lookup between the two. Rather than put two different identifiers in the same position on sibling routes, the path says what it takes: ?commitSha=….

The project must be awake

The diff is computed on the project's sandbox, so a sleeping project answers NO_ACTIVE_SANDBOX. That is a real state rather than a transient failure — prompt the user to start the project (or call Start or Restart Server) instead of retrying.

Path parameters

Parameter	Type	Description
`projectId`	string	The project ID

Query parameters

Field	Type	Required	Description
`commitSha`	string	Yes	The `commitSha` of the version, from List Versions. 7 to 40 hexadecimal characters

Response fields

Field	Type	Description
`data.commitSha`	string	The commit the diff was produced from
`data.diff`	string	Raw unified diff text. Empty string when the commit changed nothing tracked

Works for versions the agent did not create

Until this endpoint existed, the only viewable changes were the gitDiffUrl on an agent conversation message, so versions produced by a manual file write, a GitHub pull or an import had no visible history at all. This covers all of them.

Example request

bash

curl -H "api-key: tlm_sk_your_key" \
  "https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/version-diff?commitSha=9f2c1ab"

Success · 200 OK

json

{
  "errors": null,
  "data": {
    "commitSha": "9f2c1ab",
    "diff": "diff --git a/src/app/page.tsx b/src/app/page.tsx\n--- a/src/app/page.tsx\n+++ b/src/app/page.tsx\n@@ -12,6 +12,9 @@\n   return (\n     <main>\n+      <ContactForm />\n     </main>\n   );\n"
  }
}

Error · 400

json

{
  "errors": {
    "errorCode": "INVALID_COMMIT_SHA",
    "errorMessage": "commitSha must be 7 to 40 hexadecimal characters"
  },
  "data": null
}

Error codes

Code	HTTP	Meaning
`MISSING_PROJECT_ID`	400	projectId is required
`PROJECT_NOT_FOUND`	404	Project does not exist or you don't own it
`MISSING_COMMIT_SHA`	400	The `commitSha` query parameter is required
`INVALID_COMMIT_SHA`	400	`commitSha` must be 7 to 40 hexadecimal characters
`NO_ACTIVE_SANDBOX`	400	The project's sandbox is not running — start the project and try again

End of Get Version DiffNext endpointPOSTRecover Version

#Recover Version

POST/api/v1/vcaas/projects/:projectId/versions/:id/recoverUses credits

Restore a previous version of the project. This endpoint is asynchronous: it returns immediately and the recovery continues in the background for 1 to 4 minutes.

Asynchronous

Poll GET /projects/:projectId every 10–15 seconds and watch the versionRecovery field. While the recovery is running, versionRecovery.status is "recovering". Recovery is complete the moment versionRecovery becomes null. If versionRecovery.status is "error", surface versionRecovery.errorMessage to the user. Do NOT poll agentProcessStatus for recovery — the agent is not involved in a version recovery.

Note

If the server is not active, it auto-starts (charges START_SERVER credits extra) and returns SERVER_NOT_READY.

Path parameters

Parameter	Type	Description
`projectId`	string	The project ID
`id`	string	The version ID to recover (from GET /versions)

Response fields

Field	Type	Description
`data.message`	string	Confirmation message

Example request

bash

curl -X POST -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/versions/v_abc123/recover

Success · 200 OK

json

{ "errors": null, "data": { "message": "Version recovery initiated" } }

Error · 402

json

{
  "errors": {
    "errorCode": "INSUFFICIENT_CREDITS",
    "errorMessage": "Not enough credits for version recovery"
  },
  "data": null
}

Error codes

Code	HTTP	Meaning
`MISSING_PROJECT_ID`	400	projectId is required
`PROJECT_NOT_FOUND`	404	Project does not exist or you don't own it
`MISSING_VERSION_ID`	400	versionId is required
`AGENT_RUNNING`	409	Cannot recover while agent is running
`DEPLOYMENT_RUNNING`	409	Cannot recover while deployment is in progress
`RECOVERY_RUNNING`	409	A version recovery is already in progress
`SERVER_NOT_READY`	409	Server auto-starting, poll until Active then retry
`INSUFFICIENT_CREDITS`	402	Not enough credits for version recovery

End of Recover Version Back to top