# Totalum App Builder API — Account

This file is the complete reference for this area. The short guide for agents is https://www.totalum.app/totalum-api.md.

- Base URL: `https://builder-api.totalum.app/api/v1/vcaas`
- Authentication: header `api-key: tlm_sk_…` on every request, from a server only.
- Response envelope: `{ "errors": null | { "errorCode", "errorMessage", "errorDetails?" }, "data": … }`.


---

# Account

> Balance, prices and account-wide settings.

Account-level endpoints: no project in the path.

## Get Account Info

```endpoint
method: GET
path: /api/v1/vcaas/account
cost: Free
```

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**

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

:::success 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 |

## Get Credit Costs

```endpoint
method: GET
path: /api/v1/vcaas/credit-costs
cost: Free
```

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](https://www.totalum.app/docs/api/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**

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

:::success 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
    }
  }
}
```
:::

## Get Data Residency

```endpoint
method: GET
path: /api/v1/vcaas/account/data-residency
cost: Free
```

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**

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

:::success Success · 200 OK
```json
{ "errors": null, "data": { "dataResidency": "global" } }
```
:::

## Set Data Residency

```endpoint
method: PUT
path: /api/v1/vcaas/account/data-residency
cost: Free
```

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**

```bash
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
```

:::success 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 |