Versions

Browse your project's version history and roll back to an earlier state.

Every completed prompt produces a version. You can list the version history and recover a previous version. Both 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 for recover)
`data.versions[].name`	string	Version display name
`data.versions[].commitMessage`	string \| undefined	Git commit message
`data.versions[].prompt`	string \| undefined	The prompt that created this version
`data.versions[].createdAt`	string	ISO 8601 creation date
`data.totalCount`	number	Total versions available

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",
        "commitMessage": "Added contact form",
        "prompt": "Add a contact form to the landing page",
        "createdAt": "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

#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