Account

Balance, prices and account-wide settings.

Account-level endpoints: no project in the path.

#Get Account Info

GET/api/v1/vcaas/accountapi-keyFree

Your spendable credit balance. Check it before a large batch of prompts.

Response fields

Field	Type	Description
`data.credits`	number	Total spendable balance (`recurrentCredits + oneTimeCredits`)
`data.recurrentCredits`	number	Plan credits left this billing period (used first)
`data.oneTimeCredits`	number	Purchased credits (never expire)
`data.engineOptIn`	object \| undefined	`{ eligible, mode }`: whether new projects can be created with `engineVersion: "v2"`

Example request

curl -H "api-key: tlm_sk_your_key" \
  https://builder-api.totalum.app/api/v1/vcaas/account

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

Success · 200 OK

json

{ "errors": null, "data": { "credits": 425.5, "recurrentCredits": 100, "oneTimeCredits": 325.5, "engineOptIn": { "eligible": true, "mode": "default" } } }

Error codes

Code	HTTP	Meaning
`ACCOUNT_SERVICE_UNAVAILABLE`	503	The balance cannot be read right now; retry in a few minutes

End of Get Account InfoNext endpointGETGet Credit Costs

#Get Credit Costs

GET/api/v1/vcaas/credit-costsapi-keyFree

The price in credits of every fixed-price action, and the monthly fees. Read it at runtime instead of hard-coding prices. Prompts are not listed: they are metered (at least 3 credits each). The app's own usage (hosting, database, AI, e-mail…) is metered too: see Usage & Analytics.

Query parameters

Field	Type	Required	Description
`engine`	string	No	`v2` (default for new accounts)

Response fields

Field	Type	Description
`data.creditCosts.CREATE_PROJECT`	number	Creating a project
`data.creditCosts.CREATE_DEPLOYMENT`	number	Publishing
`data.creditCosts.START_SERVER`	number	Restarting the development environment
`data.creditCosts.GET_SOURCE_CODE`	number	Downloading the source code
`data.creditCosts.RECOVER_VERSION`	number	Restoring a version
`data.creditCosts.UPLOAD_FILE`	number	Uploading a file (free)
`data.creditCosts.ADD_CUSTOM_DOMAIN`	number	Adding a custom domain
`data.creditCosts.EXPORT_PROJECT`	number	Exporting a project
`data.creditCosts.IMPORT_PROJECT`	number	Importing a project
`data.creditCosts.UPDATE_FILE`	number	Writing a file (free)
`data.creditCosts.REBUILD_PROJECT`	number	Rebuilding the preview
`data.creditCosts.BACKUP_CREATE_MANUAL`	number	A manual database backup
`data.creditCosts.BACKUP_RESTORE`	number	Restoring a backup or a point in time
`data.creditCosts.VISUAL_EDIT_APPLY`	number	Applying a visual-edit batch
`data.creditCosts.PAUSE_RESUME`	number	Pausing, or resuming, a project
`data.creditCosts.MONTHLY_PROJECT_FEE`	number	A month a project is published on a paid plan
`data.creditCosts.MONTHLY_HOSTING_FEE`	number	That project's hosting, the same month
`data.creditCosts.MONTHLY_CUSTOM_DOMAIN_FEE`	number	A month a custom domain is active

Example request

curl -H "api-key: tlm_sk_your_key" \
  "https://builder-api.totalum.app/api/v1/vcaas/credit-costs?engine=v2"

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/credit-costs?engine=v2", {
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
  },
});
const { errors, data } = await res.json();

Success · 200 OK

json

{
  "errors": null,
  "data": {
    "creditCosts": {
      "CREATE_PROJECT": 2,
      "CREATE_DEPLOYMENT": 0.5,
      "START_SERVER": 2,
      "GET_SOURCE_CODE": 2,
      "RECOVER_VERSION": 2,
      "UPLOAD_FILE": 0,
      "ADD_CUSTOM_DOMAIN": 4,
      "EXPORT_PROJECT": 4,
      "IMPORT_PROJECT": 12,
      "UPDATE_FILE": 0,
      "REBUILD_PROJECT": 2,
      "BACKUP_CREATE_MANUAL": 2,
      "BACKUP_RESTORE": 4,
      "VISUAL_EDIT_APPLY": 0.6,
      "PAUSE_RESUME": 2,
      "MONTHLY_PROJECT_FEE": 1,
      "MONTHLY_HOSTING_FEE": 2,
      "MONTHLY_CUSTOM_DOMAIN_FEE": 3
    }
  }
}

End of Get Credit CostsNext endpointGETGet Data Residency

#Get Data Residency

GET/api/v1/vcaas/account/data-residencyapi-keyFree

The account's default for new projects: global (each database placed nearest its users, with read copies elsewhere) or eu (databases created and kept inside the European Union only).

Response fields

Field	Type	Description
`data.dataResidency`	string	`"global"` or `"eu"`

Example request

curl -H "api-key: tlm_sk_your_key" \
  https://builder-api.totalum.app/api/v1/vcaas/account/data-residency

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

Success · 200 OK

json

{ "errors": null, "data": { "dataResidency": "global" } }

End of Get Data ResidencyNext endpointPUTSet Data Residency

#Set Data Residency

PUT/api/v1/vcaas/account/data-residencyapi-keyFree

Set the default for projects created from now on. Existing projects never move; a project's own dataResidency on create or launch wins. A key restricted to some projects cannot change it.

Body parameters

Field	Type	Required	Description
`dataResidency`	string	Yes	`"global"` or `"eu"`

Response fields

Field	Type	Description
`data.dataResidency`	string	The new default

Example request

curl -X PUT \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"dataResidency":"eu"}' \
  https://builder-api.totalum.app/api/v1/vcaas/account/data-residency

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/account/data-residency", {
  method: "PUT",
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "dataResidency": "eu"
  }),
});
const { errors, data } = await res.json();

Success · 200 OK

json

{ "errors": null, "data": { "dataResidency": "eu" } }

Error codes

Code	HTTP	Meaning
`INVALID_DATA_RESIDENCY`	400	Not `"global"` or `"eu"`
`API_KEY_SCOPE_FORBIDDEN`	403	This key cannot change account settings

End of Set Data Residency Back to top