# Totalum App Builder API — Building on Totalum's API from your app

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": … }`.


---

# Building on Totalum's API from your app

> For apps whose own users create apps — the key, where it lives, and who pays.

Some apps are themselves app builders: their users describe an app and the app creates it. Such an app calls this API from its own server, with a Totalum API key of its own.

## Where the key comes from

- **In the Totalum app** — on the **first prompt of a new project**, when that prompt asks for an app that creates or hosts apps for its own users, Totalum adds the key for you, but only if you may manage the account's API keys (owner, admin, or a member allowed to manage API keys). It creates an account API key named `App builder — <project name>` and stores it in the project as the secret `TOTALUM_VCAAS_API_KEY`. A card in the chat tells you it was added. Later prompts are never checked, and nothing is added for anyone who may not manage API keys.
- **Through this API or the MCP** — nothing is ever added automatically, whatever the prompt says. Create a key on your account and pass it yourself as the project secret `TOTALUM_VCAAS_API_KEY` (environment `both`): in the `secrets` of [Launch Project](https://www.totalum.app/docs/api/projects#launch-project), or with [Create Secret](https://www.totalum.app/docs/api/secrets#create-secret) before the prompt that needs it.

## Rules for the key

- It is an **account** key (`tlm_sk_…`): everything the app does with it — every project it creates and every prompt it sends — is billed to your account and counts against your plan's limits.
- It lives only in the project secret `TOTALUM_VCAAS_API_KEY`, read on the server. Never put it in source code, a committed `.env`, or a `NEXT_PUBLIC_*` variable, and never call this API from browser code.
- You can revoke it at any time from your API keys, like any other key.

## What the app calls

The same endpoints as any other client: [Launch Project](https://www.totalum.app/docs/api/projects#launch-project), [Get Agent Status](https://www.totalum.app/docs/api/agent#get-agent-status), [Run AI Agent](https://www.totalum.app/docs/api/agent#run-ai-agent), [Get Project Details](https://www.totalum.app/docs/api/projects#get-project), [Deploy to Production](https://www.totalum.app/docs/api/deployments#deploy-to-production), [List Versions](https://www.totalum.app/docs/api/versions#list-versions) and [Delete Project](https://www.totalum.app/docs/api/projects#delete-project). The whole reference is at `https://www.totalum.app/totalum-api.md`.