{ "openapi": "3.1.0", "info": { "title": "Totalum App Builder API", "version": "1.0.0", "summary": "Create, build and deploy full-stack AI-generated apps programmatically.", "description": "The Totalum App Builder API lets you create a project, run the AI agent with a natural-language prompt, and deploy the result to a public URL.\n\nEvery response uses the same envelope: `{ \"errors\": null | { \"errorCode\", \"errorMessage\" }, \"data\": ... }` — the one exception is a rejected API key, which returns `401 { \"error\": \"Unauthorized api key\" }`. Branch on the status code, not only on `errors`.\n\nThe agent and deployment endpoints are asynchronous: they return immediately, and you poll the matching status endpoint every 10 to 15 seconds. An agent run takes 10 to 30 minutes; a deploy takes 2 to 5 minutes.\n\nKeep your `tlm_sk_` key on your backend — it must never reach browser code.\n\nThis document is generated from the published documentation at https://www.totalum.app/docs/api/overview, so it always matches it.\nRunnable quickstart: https://www.totalum.app/docs/quickstart", "contact": { "name": "Totalum", "url": "https://www.totalum.app/docs", "email": "contacto@totalum.app" }, "license": { "name": "Totalum Terms of Service", "url": "https://www.totalum.app/terms-of-service" } }, "externalDocs": { "description": "Totalum API documentation", "url": "https://www.totalum.app/docs/api/overview" }, "servers": [ { "url": "https://api-accounts.totalum.app", "description": "Production" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Account", "description": "Retrieve your Totalum credit balance and account details via the api-key authenticated REST API.", "externalDocs": { "url": "https://www.totalum.app/docs/api/account" } }, { "name": "Projects", "description": "Create, list, inspect, delete, and set credit limits on Totalum projects, including the main polling endpoint.", "externalDocs": { "url": "https://www.totalum.app/docs/api/projects" } }, { "name": "Project Transfer", "description": "Clone a Totalum project (database plus source code) into another project using export import codes.", "externalDocs": { "url": "https://www.totalum.app/docs/api/transfer" } }, { "name": "AI Agent", "description": "Run the Totalum AI agent to build and modify projects, poll status, read conversations, and stop runs.", "externalDocs": { "url": "https://www.totalum.app/docs/api/agent" } }, { "name": "Deployments", "description": "Build and deploy a Totalum project to its production URL and poll deployment status.", "externalDocs": { "url": "https://www.totalum.app/docs/api/deployments" } }, { "name": "Server", "description": "Start or restart the project dev server and read backend dev server logs.", "externalDocs": { "url": "https://www.totalum.app/docs/api/server" } }, { "name": "Source Code & Files", "description": "Download a Totalum project's source code and upload files as AI agent input.", "externalDocs": { "url": "https://www.totalum.app/docs/api/source-files" } }, { "name": "Versions", "description": "List a Totalum project's saved versions and recover a previous version.", "externalDocs": { "url": "https://www.totalum.app/docs/api/versions" } }, { "name": "Secrets", "description": "Create and delete encrypted environment variables that auto-sync to your Totalum project sandbox.", "externalDocs": { "url": "https://www.totalum.app/docs/api/secrets" } }, { "name": "Custom Domains", "description": "Attach or detach a custom subdomain on your deployed Totalum project and configure DNS.", "externalDocs": { "url": "https://www.totalum.app/docs/api/domains" } }, { "name": "Database", "description": "Read your Totalum project's table structure, query records with filters and nested relations, and create or edit records.", "externalDocs": { "url": "https://www.totalum.app/docs/api/database" } }, { "name": "Analytics", "description": "Retrieve daily Totalum credit spending aggregated by day, category, and usage type for charts and reports.", "externalDocs": { "url": "https://www.totalum.app/docs/api/analytics" } }, { "name": "Webhooks", "description": "Subscribe to Totalum App Builder API events and receive HTTP POST callbacks when the AI agent finishes or a credit limit is reached.", "externalDocs": { "url": "https://www.totalum.app/docs/api/webhooks" } }, { "name": "GitHub API", "description": "Connect a GitHub repo to a Totalum project, sync branches, pull changes, check status, and download env vars.", "externalDocs": { "url": "https://www.totalum.app/docs/api/github" } } ], "paths": { "/api/v1/vcaas/account": { "get": { "operationId": "getAccountInfo", "summary": "Get Account Info", "description": "Retrieve your current credit balance and account details.\n\nFull reference: https://www.totalum.app/docs/api/account#get-account-info", "tags": [ "Account" ], "x-totalum-cost": "Free", "externalDocs": { "description": "Get Account Info — Totalum docs", "url": "https://www.totalum.app/docs/api/account#get-account-info" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "credits": { "type": "number", "description": "Current credit balance" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "credits": 425 } } } } }, "400": { "description": "`GET_ACCOUNT_ERROR` — Internal error fetching account info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "GET_ACCOUNT_ERROR", "errorMessage": "Internal error fetching account info" }, "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" } } } }, "/api/v1/vcaas/projects": { "post": { "operationId": "createProject", "summary": "Create Project", "description": "Create a new vibe coding project.\n\nFull reference: https://www.totalum.app/docs/api/projects#create-project", "tags": [ "Projects" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "description": "4-35 chars, lowercase letters + numbers + hyphens, must start with letter" }, "description": { "type": "string", "description": "Project description, max 500 characters" } }, "required": [ "projectId" ], "additionalProperties": true }, "example": { "projectId": "my-app", "description": "A SaaS landing page" } } } }, "x-totalum-cost": "Uses credits", "externalDocs": { "description": "Create Project — Totalum docs", "url": "https://www.totalum.app/docs/api/projects#create-project" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "projectId": { "type": "string", "description": "The project ID" }, "description": { "type": "string", "description": "Project description" }, "plan": { "type": "string", "description": "Always \"api\" for projects created through the API" }, "createdAt": { "type": "string", "description": "ISO 8601 creation date" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "projectId": "my-app", "description": "A SaaS landing page", "plan": "api", "createdAt": "2026-03-11T10:30:00.000Z" } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required\n`INVALID_PROJECT_NAME` — Invalid format. Use lowercase letters, numbers, and hyphens. Must start with a letter\n`INVALID_PROJECT_NAME_LENGTH` — Project name must be between 4 and 35 characters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`INSUFFICIENT_CREDITS` — Not enough credits for this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "$ref": "#/components/responses/NoCredits" }, "409": { "description": "`PROJECT_ALREADY_EXISTS` — A project with this name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "PROJECT_ALREADY_EXISTS", "errorMessage": "A project with this name already exists" }, "data": null } } } }, "429": { "description": "`RATE_LIMIT_EXCEEDED` — Maximum 10 project creations per 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "operationId": "listProjects", "summary": "List Projects", "description": "Get all your projects.\n\nFull reference: https://www.totalum.app/docs/api/projects#list-projects", "tags": [ "Projects" ], "x-totalum-cost": "Free", "externalDocs": { "description": "List Projects — Totalum docs", "url": "https://www.totalum.app/docs/api/projects#list-projects" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "array", "description": "Array of project objects", "items": { "type": "object", "properties": { "projectId": { "type": "string", "description": "The project ID" }, "description": { "type": "string", "description": "Project description" }, "plan": { "type": "string", "description": "Always \"api\" for projects created through the API" }, "createdAt": { "type": "string", "description": "ISO 8601 creation date" } }, "additionalProperties": true } } }, "additionalProperties": true }, "example": { "errors": null, "data": [ { "projectId": "my-app", "description": "A SaaS landing page", "plan": "api", "createdAt": "2026-03-11T10:30:00.000Z" } ] } } } }, "400": { "description": "`LIST_PROJECTS_ERROR` — Internal error listing projects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "LIST_PROJECTS_ERROR", "errorMessage": "Internal error listing projects" }, "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" } } } }, "/api/v1/vcaas/projects/{projectId}": { "get": { "operationId": "getProjectDetails", "summary": "Get Project Details", "description": "Retrieve full project info including status, deployment, secrets, and URLs. This is the main polling endpoint for project state.\n\nFull reference: https://www.totalum.app/docs/api/projects#get-project-details", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Get Project Details — Totalum docs", "url": "https://www.totalum.app/docs/api/projects#get-project-details" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "projectId": { "type": "string", "description": "The project ID" }, "description": { "type": "string", "description": "Project description" }, "plan": { "type": "string", "description": "Always \"api\" for projects created through the API" }, "agentProcessStatus": { "type": "string", "description": "\"init\" (running) | \"done\" (finished) | \"idle\" (not started)" }, "agentServerStatus": { "type": "string", "description": "\"Active\" | \"Creating\" | \"Starting\" | \"Archived\" | \"Unarchiving\" | \"Archiving\"" }, "createdAt": { "type": "string", "description": "ISO 8601 creation date" }, "deployment": { "type": [ "object", "null" ], "description": "Latest deployment info, null if never deployed", "properties": { "status": { "type": "string", "description": "\"deploying\" | \"success\" | \"error\"" }, "createdAt": { "type": "string", "description": "ISO 8601 deployment date" }, "versionId": { "type": "string", "description": "Version ID that was deployed" } }, "additionalProperties": true }, "versionRecovery": { "type": [ "object", "null" ], "description": "Set while a recoverVersion call is running, otherwise null. This is the canonical signal for \"is a version recovery in progress\" — do NOT poll agentProcessStatus for recovery (the agent is not involved).", "properties": { "status": { "type": "string", "description": "\"recovering\" (in progress) | \"error\" (last recovery failed)" }, "versionId": { "type": "string", "description": "The version ID currently being / last attempted being recovered" }, "startedAt": { "type": "string", "description": "ISO 8601 start time" }, "errorMessage": { "type": "string", "description": "Present when status=\"error\" — surface this text to the user" } }, "additionalProperties": true }, "secrets": { "type": "array", "description": "List of secret names (values never returned)", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Secret ID (use for deletion)" }, "secretName": { "type": "string", "description": "Environment variable name" }, "environment": { "type": "string", "description": "\"development\" | \"production\" | \"both\"" } }, "additionalProperties": true } }, "customDomain": { "type": [ "object", "null" ], "description": "Custom domain info, null if none configured", "properties": { "hostname": { "type": "string", "description": "The custom domain hostname" }, "status": { "type": "string", "description": "\"pending_validation\" | \"pending_deployment\" | \"active\" | \"blocked\"" }, "sslStatus": { "type": "string", "description": "SSL certificate status" }, "dnsRecordsToAdd": { "type": "array", "description": "DNS records to configure: [{ type: \"CNAME\"|\"TXT\", name, value }]" } }, "additionalProperties": true }, "temporalDevelopmentProjectUrl": { "type": [ "string", "null" ], "description": "Live development preview URL (from the running dev server). May be null/undefined if no server has started yet." }, "cachedDevelopmentUrl": { "type": [ "string", "null" ], "description": "Cached development preview URL (static snapshot, available when server is not active). May be null/undefined if the project has never been archived." }, "developmentUrlFieldToUse": { "type": [ "string", "null" ], "description": "Which field to use for the development preview right now: \"temporalDevelopmentProjectUrl\" or \"cachedDevelopmentUrl\". If this field is null or undefined, default to temporalDevelopmentProjectUrl." }, "productionProjectUrl": { "type": "string", "description": "Production URL — custom domain if connected, otherwise {projectId}.totalum-project.com" }, "totalCreditsSpent": { "type": "number", "description": "Total credits spent on this project" }, "creditLimits": { "type": "object", "description": "Currently configured monthly credit limits for this project", "properties": { "maxDevelopmentCreditsPerMonth": { "type": [ "number", "null" ], "description": "Max development credits/month (null = no limit)" }, "maxInfrastructureCreditsPerMonth": { "type": [ "number", "null" ], "description": "Max infrastructure credits/month (null = no limit)" } }, "additionalProperties": true }, "multiPrompt": { "type": [ "object", "null" ], "description": "Present only when a multi-prompt batch was started via POST /agent/start with multiPrompt. Same shape as on GET /agent/status.", "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "projectId": "my-app", "description": "A SaaS landing page", "plan": "api", "agentProcessStatus": "done", "agentServerStatus": "Active", "createdAt": "2026-03-11T10:30:00.000Z", "deployment": { "status": "success", "createdAt": "2026-03-11T11:00:00.000Z", "versionId": "v_abc123" }, "versionRecovery": null, "secrets": [ { "_id": "s1", "secretName": "STRIPE_KEY", "environment": "both" } ], "customDomain": { "hostname": "app.mysite.com", "status": "active", "sslStatus": "active", "dnsRecordsToAdd": [ { "type": "CNAME", "name": "app", "value": "my-app.totalum-project.com" }, { "type": "TXT", "name": "_cf-custom-hostname.app", "value": "verification-token" } ] }, "temporalDevelopmentProjectUrl": "https://dev-my-app.totalum.app", "cachedDevelopmentUrl": "https://my-app-dev-a1b2c3d4.totalum-project.com", "developmentUrlFieldToUse": "temporalDevelopmentProjectUrl", "productionProjectUrl": "app.mysite.com", "totalCreditsSpent": 12.4, "creditLimits": { "maxDevelopmentCreditsPerMonth": 100, "maxInfrastructureCreditsPerMonth": null }, "multiPrompt": null } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "PROJECT_NOT_FOUND", "errorMessage": "Project does not exist or you don't own it" }, "data": null } } } } } }, "delete": { "operationId": "deleteProject", "summary": "Delete Project", "description": "Permanently delete a project and all its data.\n\nFull reference: https://www.totalum.app/docs/api/projects#delete-project", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Delete Project — Totalum docs", "url": "https://www.totalum.app/docs/api/projects#delete-project" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "true on successful deletion" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "success": true } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required\n`PLAN_NOT_API` — Only API plan projects can be deleted from this API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "PROJECT_NOT_FOUND", "errorMessage": "Project does not exist or you don't own it" }, "data": null } } } } } } }, "/api/v1/vcaas/projects/{projectId}/credit-limits": { "patch": { "operationId": "updateCreditLimits", "summary": "Update Credit Limits", "description": "Set monthly spending caps per project for development and/or infrastructure credits. By default, projects have no credit limits. Set a field to null to remove that limit.\n\nFull reference: https://www.totalum.app/docs/api/projects#update-credit-limits", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxDevelopmentCreditsPerMonth": { "description": "Max development credits per month (null to remove)" }, "maxInfrastructureCreditsPerMonth": { "description": "Max infrastructure credits per month (null to remove)" } }, "additionalProperties": true }, "example": { "maxDevelopmentCreditsPerMonth": 500, "maxInfrastructureCreditsPerMonth": 100 } } } }, "x-totalum-cost": "Free", "externalDocs": { "description": "Update Credit Limits — Totalum docs", "url": "https://www.totalum.app/docs/api/projects#update-credit-limits" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "creditLimits": { "type": "object", "properties": { "maxDevelopmentCreditsPerMonth": { "description": "Current development limit" }, "maxInfrastructureCreditsPerMonth": { "description": "Current infrastructure limit" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "creditLimits": { "maxDevelopmentCreditsPerMonth": 500, "maxInfrastructureCreditsPerMonth": 100 } } } } } }, "400": { "description": "`MISSING_LIMIT_FIELDS` — At least one of the two limit fields is required\n`INVALID_LIMIT` — Amount must be a positive number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project doesn't exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "PROJECT_NOT_FOUND", "errorMessage": "Project doesn't exist or you don't own it" }, "data": null } } } } } } }, "/api/v1/vcaas/projects/{projectId}/export": { "post": { "operationId": "exportProject", "summary": "Export Project", "description": "Export this project's database (excluding secrets/sandbox/auth/users/tokens/org) plus a reference to its source code, and get a secret import code. Rate limit: 1 per minute, 5 per hour.\n\nFull reference: https://www.totalum.app/docs/api/transfer#export-project", "tags": [ "Project Transfer" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "includeRecords": { "type": "boolean", "description": "Default false. true also exports table data records; false exports only schema/pages/config" } }, "additionalProperties": true }, "example": { "includeRecords": false } } } }, "x-totalum-cost": "Uses credits", "externalDocs": { "description": "Export Project — Totalum docs", "url": "https://www.totalum.app/docs/api/transfer#export-project" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "importCode": { "type": "string", "description": "Secret code to import this project. SECRET — anyone with it can import the data + source" }, "includeRecords": { "type": "boolean", "description": "Whether data records were included" }, "message": { "type": "string", "description": "Human-readable confirmation" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "importCode": "my-app-export-project-8f3b1c9a47e2d650b9114af0c7e3a2d1.zip", "includeRecords": false, "message": "Export ready. Save the importCode and keep it secret..." } } } } }, "400": { "description": "`PROJECT_EXPORT_LIMIT_REACHED` — Rate limit reached (1/min, 5/hour)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`INSUFFICIENT_CREDITS` — Not enough credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "INSUFFICIENT_CREDITS", "errorMessage": "Not enough credits" }, "data": null } } } }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project not found or not owned by you", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/vcaas/projects/{projectId}/import": { "post": { "operationId": "importProject", "summary": "Import Project", "description": "Import a project from an importCode into THIS (almost empty) project: restores the database, sets up the source code, then builds and runs it. Returns immediately; the restore + rebuild run in the background (a few minutes). Existing data is always dropped before restoring. Rate limit: 1 per minute, 5 per hour.\n\nFull reference: https://www.totalum.app/docs/api/transfer#import-project", "tags": [ "Project Transfer" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "importCode": { "type": "string", "description": "The importCode returned by the export endpoint (any project)" } }, "required": [ "importCode" ], "additionalProperties": true }, "example": { "importCode": "my-app-export-project-8f3b1c9a....zip" } } } }, "x-totalum-cost": "Uses credits", "externalDocs": { "description": "Import Project — Totalum docs", "url": "https://www.totalum.app/docs/api/transfer#import-project" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "projectId": { "type": "string", "description": "The target project ID" }, "status": { "type": "string", "description": "Always \"importing\"" }, "message": { "type": "string", "description": "Instructions to poll for completion" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "projectId": "my-new-app", "status": "importing", "message": "Project import started. Poll GET /projects/:projectId until agentServerStatus='Active'." } } } } }, "400": { "description": "`MISSING_IMPORT_CODE` — importCode is required\n`PROJECT_NOT_IMPORTABLE` — Target already has content (>5 tables or >1 version). Use a fresh project\n`IMPORT_IN_PROGRESS` — An import is already running for this project\n`PROJECT_IMPORT_LIMIT_REACHED` — Rate limit reached (1/min, 5/hour)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "PROJECT_NOT_IMPORTABLE", "errorMessage": "Target already has content (>5 tables or >1 version). Use a fresh project" }, "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`INSUFFICIENT_CREDITS` — Not enough credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "$ref": "#/components/responses/NoCredits" }, "409": { "description": "`AGENT_RUNNING` — Wait for the agent to finish before importing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/vcaas/projects/{projectId}/agent/start": { "post": { "operationId": "runAiAgent", "summary": "Run AI Agent", "description": "Start the AI agent with a prompt to build or modify your project. Supports two modes:\n\nFull reference: https://www.totalum.app/docs/api/agent#run-ai-agent", "tags": [ "AI Agent" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project to run the agent on" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "description": "Single-prompt: the user instruction. Multi-prompt + letTotalumDecide: the high-level goal Totalum breaks down. Multi-prompt + prompts[]: ignored." }, "inputFiles": { "type": "array", "description": "Reference images/files for the agent", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "File name" }, "imageDescription": { "type": "string", "description": "Description of the image content" }, "url": { "type": "string", "description": "Public URL or uploaded file URL" } }, "required": [ "name", "imageDescription", "url" ], "additionalProperties": true } }, "multiPrompt": { "type": "object", "description": "Opt into the unsupervised multi-prompt batch mode. Omit for normal use.", "properties": { "prompts": { "type": "array", "items": { "type": "string" }, "description": "Up to 50 prompts to run sequentially. Each item must be a non-empty string." }, "letTotalumDecide": { "type": "boolean", "description": "When true, Totalum plans the prompt list from the top-level prompt." } }, "additionalProperties": true } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Create a landing page with a contact form", "inputFiles": [] } } } }, "x-totalum-cost": "Uses credits", "externalDocs": { "description": "Run AI Agent — Totalum docs", "url": "https://www.totalum.app/docs/api/agent#run-ai-agent" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "projectId": { "type": "string", "description": "The project ID" }, "status": { "type": "string", "description": "Always \"init\" on success — for both single and multi-prompt mode" }, "message": { "type": "string", "description": "Instructions on how to poll for status (multi-prompt includes the cost/time warning)" }, "multiPrompt": { "type": "object", "description": "Present only when the request had multiPrompt. Detailed batch status is on GET /agent/status under multiPrompt.", "properties": { "totalPrompts": { "type": "number", "description": "Known when the caller provided prompts; absent while Totalum is still planning a letTotalumDecide batch." } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "projectId": "my-app", "status": "init", "message": "Process started, can take from 10 to 30 minutes (10 to 40 credits). Fetch GET .../agent/status every 10-15 seconds to track progress." } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required\n`MISSING_PROMPT` — prompt is required (single-prompt mode, or letTotalumDecide=true — it is the planner goal)\n`INVALID_MULTI_PROMPT` — multiPrompt was set but neither (or both) of prompts[] and letTotalumDecide=true were provided\n`TOO_MANY_PROMPTS` — multiPrompt.prompts exceeds the 50-item limit\n`INVALID_PROMPT_ITEM` — A multiPrompt.prompts entry is not a non-empty string\n`PROMPT_SECURITY_VIOLATION` — Prompt failed security validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`INSUFFICIENT_CREDITS` — Minimum 50 credits required to start agent (multi-prompt typically needs many more)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`AGENT_RUNNING` — An agent is already running on this project\n`AUTO_EXECUTION_ALREADY_ACTIVE` — A previous multi-prompt batch is still active (executing/paused/awaiting approval). Cancel it first.\n`DEPLOYMENT_RUNNING` — Cannot start agent while a deployment is in progress\n`RECOVERY_RUNNING` — Cannot start agent while a version recovery is in progress — poll versionRecovery until null, then retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "AGENT_RUNNING", "errorMessage": "An agent is already running on this project" }, "data": null } } } } } } }, "/api/v1/vcaas/projects/{projectId}/agent/status": { "get": { "operationId": "getAgentStatus", "summary": "Get Agent Status", "description": "Poll to track agent progress and get real-time messages. Poll every 10–15 seconds.\n\nFull reference: https://www.totalum.app/docs/api/agent#get-agent-status", "tags": [ "AI Agent" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project to poll" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Get Agent Status — Totalum docs", "url": "https://www.totalum.app/docs/api/agent#get-agent-status" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "projectId": { "type": "string", "description": "The project ID" }, "status": { "type": "string", "description": "\"init\" (a prompt is currently running) | \"done\" (last prompt finished) | \"idle\" (never run). For multi-prompt runs this flips between \"init\" and \"done\" repeatedly as the batch advances — poll multiPrompt.status to track the whole batch." }, "startedAt": { "type": [ "string", "null" ], "description": "ISO 8601 start time of the current prompt (not the whole batch)" }, "realtimeConversation": { "type": "array", "description": "Single-prompt: messages from the current run. Multi-prompt: messages from the whole batch (scoped to multiPrompt.startedAt).", "items": { "type": "object", "properties": { "author": { "type": "string", "description": "\"user\" | \"agent\"" }, "message": { "type": "string", "description": "The message text" }, "messageType": { "type": "string", "description": "\"regular\" | \"starting\" | \"building\" | \"finished\" | \"error\" | \"limit-reached\"" }, "createdAt": { "type": "string", "description": "ISO 8601 message date" }, "versionId": { "type": "string", "description": "Version created at this step" }, "secretKeysNeeded": { "type": "object", "description": "Secrets the agent needs (key: { isProvided, description })", "additionalProperties": true }, "gitDiffUrl": { "type": "string", "description": "Diff URL for this step" } }, "additionalProperties": true } }, "creditsSpent": { "type": "number", "description": "Credits spent on the current prompt (present when status is \"done\")" }, "multiPrompt": { "type": [ "object", "null" ], "description": "Present only when a multi-prompt batch exists. The canonical signal for \"is a multi-prompt run in flight\" — poll its status until \"done\"/\"cancelled\".", "properties": { "status": { "type": "string", "description": "\"planning\" | \"executing\" | \"paused\" | \"done\" | \"cancelled\"" }, "totalPrompts": { "type": "number", "description": "Number of prompts in the batch (0 during planning)" }, "currentPromptIndex": { "type": "number", "description": "Index of the in-flight prompt; -1 before the first one starts" }, "prompts": { "type": "array", "description": "Ordered list of prompts in the batch", "items": { "type": "object", "properties": { "order": { "type": "number", "description": "Position in the batch" }, "prompt": { "type": "string", "description": "The prompt text" }, "status": { "type": "string", "description": "\"pending\" | \"executing\" | \"done\" | \"failed\"" } }, "additionalProperties": true } }, "startedAt": { "type": "string", "description": "ISO 8601 start time of the whole batch" }, "updatedAt": { "type": "string", "description": "ISO 8601 last change to the batch state" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "projectId": "my-app", "status": "init", "startedAt": "2026-03-11T10:35:00.000Z", "realtimeConversation": [ { "author": "agent", "message": "Creating the project structure...", "messageType": "building", "createdAt": "2026-03-11T10:36:00.000Z" }, { "author": "agent", "message": "Project built successfully!", "messageType": "finished", "versionId": "v_abc123", "gitDiffUrl": "https://...", "secretKeysNeeded": { "STRIPE_SECRET_KEY": { "isProvided": false, "description": "Required for processing payments" } }, "createdAt": "2026-03-11T10:50:00.000Z" } ], "creditsSpent": 3.2, "multiPrompt": null } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "PROJECT_NOT_FOUND", "errorMessage": "Project does not exist or you don't own it" }, "data": null } } } } } } }, "/api/v1/vcaas/projects/{projectId}/agent/full-conversation": { "get": { "operationId": "getFullConversation", "summary": "Get Full Conversation", "description": "Retrieve the complete conversation history across all agent runs (not just the current one).\n\nFull reference: https://www.totalum.app/docs/api/agent#get-full-conversation", "tags": [ "AI Agent" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project whose conversation to fetch" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Get Full Conversation — Totalum docs", "url": "https://www.totalum.app/docs/api/agent#get-full-conversation" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "projectId": { "type": "string", "description": "The project ID" }, "conversation": { "type": "array", "description": "All messages from all agent runs", "items": { "type": "object", "properties": { "author": { "type": "string", "description": "\"user\" | \"agent\"" }, "message": { "type": "string", "description": "The message text" }, "messageType": { "type": "string", "description": "\"regular\" | \"starting\" | \"building\" | \"finished\" | \"error\" | \"limit-reached\"" }, "createdAt": { "type": "string", "description": "ISO 8601 message date" }, "versionId": { "type": "string", "description": "Version created at this step" }, "secretKeysNeeded": { "type": "object", "description": "API keys the agent needs (key: { isProvided, description }). Add missing keys as project secrets.", "additionalProperties": true }, "gitDiffUrl": { "type": "string", "description": "Diff URL for this step" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "projectId": "my-app", "conversation": [ { "author": "user", "message": "Create a landing page", "messageType": "regular", "createdAt": "..." }, { "author": "agent", "message": "Building project structure...", "messageType": "building", "createdAt": "..." }, { "author": "agent", "message": "Project built successfully!", "messageType": "finished", "versionId": "v_abc123", "gitDiffUrl": "https://...", "secretKeysNeeded": { "STRIPE_SECRET_KEY": { "isProvided": false, "description": "Required for processing payments" } }, "createdAt": "..." } ] } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "PROJECT_NOT_FOUND", "errorMessage": "Project does not exist or you don't own it" }, "data": null } } } } } } }, "/api/v1/vcaas/projects/{projectId}/agent/stop": { "post": { "operationId": "stopAgent", "summary": "Stop Agent", "description": "Send a stop signal to a running agent.\n\nFull reference: https://www.totalum.app/docs/api/agent#stop-agent", "tags": [ "AI Agent" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project whose agent to stop" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Stop Agent — Totalum docs", "url": "https://www.totalum.app/docs/api/agent#stop-agent" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "message": "Agent stop signal sent" } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required\n`NO_PROCESS_RUNNING` — No agent process is currently running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "NO_PROCESS_RUNNING", "errorMessage": "No agent process is currently running" }, "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/vcaas/projects/{projectId}/deployments/deploy": { "post": { "operationId": "deployToProduction", "summary": "Deploy to Production", "description": "Build and deploy your project to a production URL. This endpoint is asynchronous — it returns immediately with status \"deploying\" and the deployment continues in the background for 2 to 5 minutes.\n\nFull reference: https://www.totalum.app/docs/api/deployments#deploy-to-production", "tags": [ "Deployments" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "x-totalum-cost": "Uses credits", "externalDocs": { "description": "Deploy to Production — Totalum docs", "url": "https://www.totalum.app/docs/api/deployments#deploy-to-production" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "projectId": { "type": "string", "description": "The project ID" }, "status": { "type": "string", "description": "Always \"deploying\" on success" }, "message": { "type": "string", "description": "Instructions on how to poll for status" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "projectId": "my-app", "status": "deploying", "message": "Deployment started. It will take from 2 to 5 minutes. Fetch GET .../deployments/status every 10-15 seconds to track progress." } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`INSUFFICIENT_CREDITS` — Not enough credits for deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`AGENT_RUNNING` — Cannot deploy while agent is running\n`DEPLOYMENT_RUNNING` — A deployment is already in progress\n`RECOVERY_RUNNING` — A version recovery is in progress\n`SERVER_NOT_READY` — Server auto-starting, poll until Active then retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "DEPLOYMENT_RUNNING", "errorMessage": "A deployment is already in progress" }, "data": null } } } } } } }, "/api/v1/vcaas/projects/{projectId}/deployments/status": { "get": { "operationId": "getDeploymentStatus", "summary": "Get Deployment Status", "description": "Check the current deployment status. Poll until status is \"success\".\n\nFull reference: https://www.totalum.app/docs/api/deployments#get-deployment-status", "tags": [ "Deployments" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Get Deployment Status — Totalum docs", "url": "https://www.totalum.app/docs/api/deployments#get-deployment-status" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "status": { "type": [ "string", "null" ], "description": "\"deploying\" | \"success\" | \"error\" | null (if never deployed)" }, "createdAt": { "type": [ "string", "null" ], "description": "ISO 8601 deployment date" }, "versionId": { "type": "string", "description": "Version that was deployed" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "status": "success", "createdAt": "2026-03-11T11:00:00.000Z", "versionId": "v_abc123" } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "PROJECT_NOT_FOUND", "errorMessage": "Project does not exist or you don't own it" }, "data": null } } } } } } }, "/api/v1/vcaas/projects/{projectId}/agent/server/start-or-restart": { "post": { "operationId": "startOrRestartServer", "summary": "Start or Restart Server", "description": "Start or restart the development server for your project. This endpoint is asynchronous — it returns immediately with status \"starting\" and the server startup continues in the background for 2 to 4 minutes.\n\nFull reference: https://www.totalum.app/docs/api/server#start-or-restart-server", "tags": [ "Server" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "x-totalum-cost": "Uses credits", "externalDocs": { "description": "Start or Restart Server — Totalum docs", "url": "https://www.totalum.app/docs/api/server#start-or-restart-server" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Status message" }, "status": { "type": "string", "description": "Always \"starting\"" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "message": "Server start/restart initiated", "status": "starting" } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`INSUFFICIENT_CREDITS` — Not enough credits for server start", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`AGENT_RUNNING` — Cannot restart server while agent is running\n`DEPLOYMENT_RUNNING` — Cannot restart server while deployment is in progress\n`RECOVERY_RUNNING` — Cannot restart server while version recovery is in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "AGENT_RUNNING", "errorMessage": "Cannot restart server while agent is running" }, "data": null } } } } } } }, "/api/v1/vcaas/projects/{projectId}/backend/dev/logs": { "get": { "operationId": "getDevServerLogs", "summary": "Get Dev Server Logs", "description": "Retrieve backend development server stdout/stderr output.\n\nFull reference: https://www.totalum.app/docs/api/server#get-dev-server-logs", "tags": [ "Server" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Get Dev Server Logs — Totalum docs", "url": "https://www.totalum.app/docs/api/server#get-dev-server-logs" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "logs": { "type": "string", "description": "Development server stdout/stderr output" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "logs": "Server running on port 3000\n..." } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "PROJECT_NOT_FOUND", "errorMessage": "Project does not exist or you don't own it" }, "data": null } } } } } } }, "/api/v1/vcaas/projects/{projectId}/source-code": { "get": { "operationId": "downloadSourceCode", "summary": "Download Source Code", "description": "Get a signed URL to download the project source code.\n\nFull reference: https://www.totalum.app/docs/api/source-files#download-source-code", "tags": [ "Source Code & Files" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "x-totalum-cost": "Uses credits", "externalDocs": { "description": "Download Source Code — Totalum docs", "url": "https://www.totalum.app/docs/api/source-files#download-source-code" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "filesCount": { "type": "number", "description": "Total files in project" }, "lastCommitSha": { "type": "string", "description": "Latest git commit SHA" }, "downloadUrl": { "type": [ "string", "null" ], "description": "Signed download URL (expires in minutes)" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "filesCount": 47, "lastCommitSha": "a1b2c3d", "downloadUrl": "https://storage.googleapis.com/..." } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`INSUFFICIENT_CREDITS` — Not enough credits for source code download", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "INSUFFICIENT_CREDITS", "errorMessage": "Not enough credits for source code download" }, "data": null } } } }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/vcaas/projects/{projectId}/files/upload": { "post": { "operationId": "uploadFile", "summary": "Upload File", "description": "Upload a file to use as agent input (images, designs, etc.). Max 12MB. Send as multipart/form-data with the field file.\n\nFull reference: https://www.totalum.app/docs/api/source-files#upload-file", "tags": [ "Source Code & Files" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload (max 12MB)" } }, "required": [ "file" ], "additionalProperties": true } } } }, "x-totalum-cost": "Uses credits", "externalDocs": { "description": "Upload File — Totalum docs", "url": "https://www.totalum.app/docs/api/source-files#upload-file" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "fileNameId": { "type": "string", "description": "Stored file name identifier" }, "url": { "type": "string", "description": "Signed download URL, use in agent inputFiles" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "fileNameId": "logo_abc123.png", "url": "https://storage.googleapis.com/..." } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required\n`MISSING_FILE` — file is required (multipart form field \"file\")", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "MISSING_FILE", "errorMessage": "file is required (multipart form field \"file\")" }, "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`INSUFFICIENT_CREDITS` — Not enough credits for file upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`UPLOAD_FAILED` — File upload failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/vcaas/projects/{projectId}/versions": { "get": { "operationId": "listVersions", "summary": "List Versions", "description": "Get all project versions with pagination.\n\nFull reference: https://www.totalum.app/docs/api/versions#list-versions", "tags": [ "Versions" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Number of versions to return (default: 20)" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Number of versions to skip (default: 0)" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "List Versions — Totalum docs", "url": "https://www.totalum.app/docs/api/versions#list-versions" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "versions": { "type": "array", "description": "Array of version objects", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Version ID (use for recover)" }, "name": { "type": "string", "description": "Version display name" }, "commitMessage": { "type": "string", "description": "Git commit message" }, "prompt": { "type": "string", "description": "The prompt that created this version" }, "createdAt": { "type": "string", "description": "ISO 8601 creation date" } }, "additionalProperties": true } }, "totalCount": { "type": "number", "description": "Total versions available" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "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 } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "PROJECT_NOT_FOUND", "errorMessage": "Project does not exist or you don't own it" }, "data": null } } } } } } }, "/api/v1/vcaas/projects/{projectId}/versions/{id}/recover": { "post": { "operationId": "recoverVersion", "summary": "Recover Version", "description": "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.\n\nFull reference: https://www.totalum.app/docs/api/versions#recover-version", "tags": [ "Versions" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The version ID to recover (from GET /versions)" } ], "x-totalum-cost": "Uses credits", "externalDocs": { "description": "Recover Version — Totalum docs", "url": "https://www.totalum.app/docs/api/versions#recover-version" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "message": "Version recovery initiated" } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required\n`MISSING_VERSION_ID` — versionId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`INSUFFICIENT_CREDITS` — Not enough credits for version recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "INSUFFICIENT_CREDITS", "errorMessage": "Not enough credits for version recovery" }, "data": null } } } }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`AGENT_RUNNING` — Cannot recover while agent is running\n`DEPLOYMENT_RUNNING` — Cannot recover while deployment is in progress\n`RECOVERY_RUNNING` — A version recovery is already in progress\n`SERVER_NOT_READY` — Server auto-starting, poll until Active then retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/vcaas/projects/{projectId}/secrets": { "post": { "operationId": "createSecret", "summary": "Create Secret", "description": "Add an environment variable. Encrypted at rest, auto-synced to the sandbox .env.\n\nFull reference: https://www.totalum.app/docs/api/secrets#create-secret", "tags": [ "Secrets" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secretName": { "type": "string", "description": "Environment variable name" }, "secretValue": { "type": "string", "description": "The secret value, stored encrypted" }, "environment": { "type": "string", "description": "\"development\" | \"production\" | \"both\" (default: \"both\")" } }, "required": [ "secretName", "secretValue" ], "additionalProperties": true }, "example": { "secretName": "STRIPE_KEY", "secretValue": "sk_live_abc123", "environment": "both" } } } }, "x-totalum-cost": "Free", "externalDocs": { "description": "Create Secret — Totalum docs", "url": "https://www.totalum.app/docs/api/secrets#create-secret" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "_id": { "type": "string", "description": "ID of the created secret" }, "secretName": { "type": "string", "description": "The secret name" }, "environment": { "type": "string", "description": "\"development\" | \"production\" | \"both\"" }, "createdAt": { "type": "string", "description": "ISO 8601 creation date" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "_id": "65f1a2b3c4d5e6f7a8b9c0d1", "secretName": "STRIPE_KEY", "environment": "both", "createdAt": "2026-03-11T10:30:00.000Z" } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required\n`MISSING_SECRET_FIELDS` — secretName and secretValue are required\n`INVALID_SECRET_KEY_NAME` — Invalid secret key name format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "MISSING_SECRET_FIELDS", "errorMessage": "secretName and secretValue are required" }, "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/vcaas/projects/{projectId}/secrets/{secretId}": { "delete": { "operationId": "deleteSecret", "summary": "Delete Secret", "description": "Remove an environment variable by ID. The sandbox .env is synced automatically.\n\nFull reference: https://www.totalum.app/docs/api/secrets#delete-secret", "tags": [ "Secrets" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" }, { "name": "secretId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The secret ID to delete" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Delete Secret — Totalum docs", "url": "https://www.totalum.app/docs/api/secrets#delete-secret" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "true on success" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "success": true } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required\n`MISSING_SECRET_ID` — secretId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "PROJECT_NOT_FOUND", "errorMessage": "Project does not exist or you don't own it" }, "data": null } } } } } } }, "/api/v1/vcaas/projects/{projectId}/domain": { "put": { "operationId": "addCustomDomain", "summary": "Add Custom Domain", "description": "Attach a custom subdomain (e.g. app.yourdomain.com) to your deployed project.\n\nFull reference: https://www.totalum.app/docs/api/domains#add-custom-domain", "tags": [ "Custom Domains" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "type": "string", "description": "The subdomain to add (e.g. app.yourdomain.com)" } }, "required": [ "hostname" ], "additionalProperties": true }, "example": { "hostname": "app.yourdomain.com" } } } }, "x-totalum-cost": "Uses credits", "externalDocs": { "description": "Add Custom Domain — Totalum docs", "url": "https://www.totalum.app/docs/api/domains#add-custom-domain" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "true on success" }, "hostname": { "type": "string", "description": "The configured hostname" }, "status": { "type": "string", "description": "\"pending_validation\" initially" }, "dnsRecordsToAdd": { "type": "array", "description": "DNS records to add at your provider", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "\"CNAME\" or \"TXT\"" }, "name": { "type": "string", "description": "DNS record name (zone-relative, e.g. \"app\" or \"_cf-custom-hostname.app\")" }, "value": { "type": "string", "description": "DNS record value (e.g. \"my-app.totalum-project.com\" or verification token)" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "success": true, "hostname": "app.yourdomain.com", "status": "pending_validation", "dnsRecordsToAdd": [ { "type": "CNAME", "name": "app", "value": "my-app.totalum-project.com" }, { "type": "TXT", "name": "_cf-custom-hostname.app", "value": "abc123-verification-token" } ] } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required\n`MISSING_HOSTNAME` — hostname is required (e.g. app.yourdomain.com)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "`INSUFFICIENT_CREDITS` — Not enough credits to add custom domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it\n`NO_DEPLOYMENT` — No deployment found. Deploy first and wait until status is \"success\"", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "NO_DEPLOYMENT", "errorMessage": "No deployment found. Deploy first and wait until status is \"success\"" }, "data": null } } } } } }, "delete": { "operationId": "removeCustomDomain", "summary": "Remove Custom Domain", "description": "Detach the custom domain from your project.\n\nFull reference: https://www.totalum.app/docs/api/domains#remove-custom-domain", "tags": [ "Custom Domains" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Remove Custom Domain — Totalum docs", "url": "https://www.totalum.app/docs/api/domains#remove-custom-domain" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "message": "Custom domain removed" } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it\n`NO_DEPLOYMENT` — No deployment found. Deploy first and wait until status is \"success\"", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "PROJECT_NOT_FOUND", "errorMessage": "Project does not exist or you don't own it" }, "data": null } } } } } } }, "/api/v1/vcaas/projects/{projectId}/database/tables-structure": { "get": { "operationId": "getDatabaseTablesStructure", "summary": "Get Database Tables Structure", "description": "Retrieve all database table definitions including field names, types, and configuration.\n\nFull reference: https://www.totalum.app/docs/api/database#get-database-tables-structure", "tags": [ "Database" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Get Database Tables Structure — Totalum docs", "url": "https://www.totalum.app/docs/api/database#get-database-tables-structure" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "tables": { "type": "array", "description": "Array of table definitions", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Table ID" }, "type": { "type": "string", "description": "Table name (snake_case)" }, "label": { "type": "string", "description": "Human-friendly display name" }, "description": { "type": "string", "description": "Table description" }, "icon": { "type": "string", "description": "FontAwesome icon class" }, "properties": { "type": "object", "description": "Map of property name to property definition", "additionalProperties": { "type": "object", "properties": { "id": { "type": "string", "description": "Property ID" }, "name": { "type": "string", "description": "Property field name" }, "propertyType": { "type": "string", "description": "\"string\" | \"number\" | \"date\" | \"options\" | \"file\" | \"long-string\" | \"objectReference\"" }, "label": { "type": "string", "description": "Human-friendly field label" }, "description": { "type": "string", "description": "Field description" }, "objectReference": { "type": "object", "description": "Relationship config (if objectReference type)", "additionalProperties": true }, "typeExtras": { "type": "object", "description": "Type-specific config (options values, date settings, etc.)", "additionalProperties": true } }, "additionalProperties": true } } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "tables": [ { "_id": "65f1a2b3c4d5e6f7", "type": "customers", "label": "Customers", "description": "Customer records", "icon": "fa-solid fa-users", "properties": { "name": { "id": "prop_abc123", "name": "name", "propertyType": "string", "label": "Full Name" }, "email": { "id": "prop_def456", "name": "email", "propertyType": "string", "label": "Email", "typeExtras": { "string": { "type": "link" } } } } } ] } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "PROJECT_NOT_FOUND", "errorMessage": "Project does not exist or you don't own it" }, "data": null } } } } } } }, "/api/v1/vcaas/projects/{projectId}/database/query": { "post": { "operationId": "queryDatabase", "summary": "Query Database", "description": "Query records from any table with advanced filtering, sorting, pagination, aggregations, and nested related data up to 6 levels deep.\n\nFull reference: https://www.totalum.app/docs/api/database#query-database", "tags": [ "Database" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tableName": { "type": "string", "description": "The table name to query (use type from tables-structure response)" }, "queryOptions": { "type": "object", "description": "Advanced query options", "properties": { "_filter": { "type": "object", "description": "Field filters (see filter operators below)", "additionalProperties": true }, "_sort": { "type": "object", "description": "Sort by fields: { fieldName: \"asc\" | \"desc\" }", "additionalProperties": true }, "_limit": { "type": "number", "description": "Max records to return (default 50, max 1000)" }, "_offset": { "type": "number", "description": "Records to skip (for pagination)" }, "_select": { "type": "object", "description": "Include only specified fields: { fieldName: true }. Cannot use with _omit", "additionalProperties": true }, "_omit": { "type": "object", "description": "Exclude specified fields: { fieldName: true }. Cannot use with _select", "additionalProperties": true }, "_count": { "type": "boolean", "description": "Adds _count._total with total matching records (before pagination)" }, "_aggregate": { "type": "object", "description": "Aggregations: { _sum: { field: true }, _avg, _min, _max, _count }", "additionalProperties": true }, "_groupBy": { "type": [ "string", "array" ], "items": { "type": "string" }, "description": "Group results by field(s). Requires _aggregate" } }, "additionalProperties": { "type": [ "boolean", "object" ], "description": "Expand related data. true = all fields, object = nested queryOptions", "additionalProperties": true } } }, "required": [ "tableName" ], "additionalProperties": true }, "example": { "tableName": "customers", "queryOptions": { "_filter": { "status": "active", "age": { "gte": 18 } }, "_sort": { "createdAt": "desc" }, "_limit": 10, "orders": { "_filter": { "total": { "gt": 50 } }, "_limit": 5 } } } } } }, "x-totalum-cost": "Free", "externalDocs": { "description": "Query Database — Totalum docs", "url": "https://www.totalum.app/docs/api/database#query-database" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "results": { "type": "array", "description": "Array of matching records" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "results": [ { "_id": "65f1a2b3c4d5e6f7a8b9c0d1", "name": "John Doe", "email": "john@example.com", "status": "active", "age": 30, "orders": [ { "_id": "...", "total": 120.5, "createdAt": "2026-03-09T..." } ], "createdAt": "2026-03-10T08:00:00.000Z" } ] } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required\n`MISSING_TABLE_NAME` — tableName is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "MISSING_TABLE_NAME", "errorMessage": "tableName is required" }, "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/vcaas/projects/{projectId}/database/records": { "post": { "operationId": "createDatabaseRecord", "summary": "Create Database Record", "description": "Create a new record in any table. The _id field is auto-generated by the database — do not include it in the request body. The response returns the full created record including the generated _id and any default fields.\n\nFull reference: https://www.totalum.app/docs/api/database#create-database-record", "tags": [ "Database" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tableName": { "type": "string", "description": "The table name to insert into (use type from tables-structure response)" }, "data": { "type": "object", "description": "The record properties as key-value pairs. Do NOT include _id (auto-generated)", "additionalProperties": true } }, "required": [ "tableName", "data" ], "additionalProperties": true }, "example": { "tableName": "customers", "data": { "name": "John Doe", "email": "john@example.com", "status": "active", "age": 30 } } } } }, "x-totalum-cost": "Free", "externalDocs": { "description": "Create Database Record — Totalum docs", "url": "https://www.totalum.app/docs/api/database#create-database-record" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "description": "The full created record including the auto-generated _id and all fields", "properties": { "_id": { "type": "string", "description": "The auto-generated unique identifier for the new record" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "_id": "65f1a2b3c4d5e6f7a8b9c0d1", "name": "John Doe", "email": "john@example.com", "status": "active", "age": 30, "createdAt": "2026-03-25T10:00:00.000Z", "updatedAt": "2026-03-25T10:00:00.000Z" } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required\n`MISSING_TABLE_NAME` — tableName is required\n`MISSING_DATA` — data is required and must be an object\n`TABLE_NOT_FOUND` — Table doesn't exist in the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "MISSING_DATA", "errorMessage": "data is required and must be an object" }, "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/vcaas/projects/{projectId}/database/records/{recordId}": { "patch": { "operationId": "editDatabaseRecord", "summary": "Edit Database Record", "description": "Update specific fields of an existing record by its ID. Only the fields included in data will be modified — all other fields remain unchanged. The response returns the full updated record.\n\nFull reference: https://www.totalum.app/docs/api/database#edit-database-record", "tags": [ "Database" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" }, { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The _id of the record to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tableName": { "type": "string", "description": "The table name (use type from tables-structure response)" }, "data": { "type": "object", "description": "The properties to update as key-value pairs. Only included fields are modified", "additionalProperties": true } }, "required": [ "tableName", "data" ], "additionalProperties": true }, "example": { "tableName": "customers", "data": { "email": "newemail@example.com", "age": 31 } } } } }, "x-totalum-cost": "Free", "externalDocs": { "description": "Edit Database Record — Totalum docs", "url": "https://www.totalum.app/docs/api/database#edit-database-record" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "description": "The full updated record with all fields (including unchanged ones)", "properties": { "_id": { "type": "string", "description": "The record ID" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "_id": "65f1a2b3c4d5e6f7a8b9c0d1", "name": "John Doe", "email": "newemail@example.com", "status": "active", "age": 31, "createdAt": "2026-03-25T10:00:00.000Z", "updatedAt": "2026-03-25T10:05:00.000Z" } } } } }, "400": { "description": "`MISSING_PROJECT_ID` — projectId is required\n`MISSING_RECORD_ID` — recordId is required\n`MISSING_TABLE_NAME` — tableName is required\n`MISSING_DATA` — data is required and must be an object\n`TABLE_NOT_FOUND` — Table doesn't exist in the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`PROJECT_NOT_FOUND` — Project does not exist or you don't own it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "PROJECT_NOT_FOUND", "errorMessage": "Project does not exist or you don't own it" }, "data": null } } } } } } }, "/api/v1/credits/spending-analytics": { "get": { "operationId": "spendingAnalytics", "summary": "Spending Analytics", "description": "Get daily credit spending data for charts and reports. Returns data aggregated by day, category (development/infrastructure), and usage type.\n\nFull reference: https://www.totalum.app/docs/api/analytics#spending-analytics", "tags": [ "Analytics" ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Start date (YYYY-MM-DD), max 90 days before to" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string" }, "description": "End date (YYYY-MM-DD)" }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by project ID" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Spending Analytics — Totalum docs", "url": "https://www.totalum.app/docs/api/analytics#spending-analytics" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "daily": { "type": "array", "description": "Array of daily spending objects", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Date (YYYY-MM-DD)" }, "development": { "type": "number", "description": "Development credits spent that day" }, "infrastructure": { "type": "number", "description": "Infrastructure credits spent that day" }, "byType": { "type": "object", "description": "Credits by usage type (e.g. prompt, deploy, chatgpt)", "additionalProperties": true } }, "additionalProperties": true } }, "totals": { "type": "object", "properties": { "development": { "type": "number", "description": "Total development credits in range" }, "infrastructure": { "type": "number", "description": "Total infrastructure credits in range" }, "total": { "type": "number", "description": "Total credits in range" }, "byType": { "type": "object", "description": "Total credits by usage type", "additionalProperties": true } }, "additionalProperties": true }, "projects": { "type": "array", "description": "List of project IDs with spending data" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "daily": [ { "date": "2026-04-01", "development": 15, "infrastructure": 3, "byType": { "prompt": 10, "deploy": 5, "chatgpt": 2, "pdf": 1 } }, { "date": "2026-04-02", "development": 20, "infrastructure": 5, "byType": { "prompt": 15, "deploy": 3, "start_server": 2, "email": 3 } } ], "totals": { "development": 35, "infrastructure": 8, "total": 43, "byType": { "prompt": 25, "deploy": 8, "chatgpt": 2, "pdf": 1, "email": 3 } }, "projects": [ "my-app", "other-project" ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" } } } }, "/api/v1/vcaas/webhooks": { "put": { "operationId": "registerWebhook", "summary": "Register Webhook", "description": "Subscribe to an event. You'll receive a POST to your URL when the event occurs.\n\nFull reference: https://www.totalum.app/docs/api/webhooks#register-webhook", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "HTTPS URL to receive webhook POST" }, "event": { "type": "string", "description": "Event type to subscribe to. See available events above" }, "headers": { "type": "object", "description": "Custom headers to include in webhook POST", "additionalProperties": true } }, "required": [ "url", "event" ], "additionalProperties": true }, "example": { "url": "https://yourserver.com/webhook", "event": "agent.prompt.finished" } } } }, "x-totalum-cost": "Free", "externalDocs": { "description": "Register Webhook — Totalum docs", "url": "https://www.totalum.app/docs/api/webhooks#register-webhook" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook ID" }, "url": { "type": "string", "description": "The registered URL" }, "headers": { "type": "object", "description": "Custom headers", "additionalProperties": true }, "event": { "type": "string", "description": "The subscribed event" }, "createdAt": { "type": "string", "description": "ISO 8601 date" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "id": "65f1a2b3c4d5e6f7a8b9c0d1", "url": "https://yourserver.com/webhook", "event": "agent.prompt.finished", "createdAt": "2026-03-17T10:00:00.000Z" } } } } }, "400": { "description": "`MISSING_WEBHOOK_FIELDS` — url and event are required\n`INVALID_WEBHOOK_URL` — Webhook URL must use HTTPS\n`INVALID_WEBHOOK_EVENT` — Event not in allowed list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "MISSING_WEBHOOK_FIELDS", "errorMessage": "url and event are required" }, "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "409": { "description": "`WEBHOOK_EVENT_ALREADY_EXISTS` — A webhook for this event already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "operationId": "listWebhooks", "summary": "List Webhooks", "description": "Get all your registered webhooks.\n\nFull reference: https://www.totalum.app/docs/api/webhooks#list-webhooks", "tags": [ "Webhooks" ], "x-totalum-cost": "Free", "externalDocs": { "description": "List Webhooks — Totalum docs", "url": "https://www.totalum.app/docs/api/webhooks#list-webhooks" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "webhooks": { "type": "array", "description": "Array of webhooks", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook ID" }, "url": { "type": "string", "description": "Destination URL" }, "headers": { "type": "object", "description": "Custom headers", "additionalProperties": true }, "event": { "type": "string", "description": "Subscribed event" }, "createdAt": { "type": "string", "description": "ISO 8601 date" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "webhooks": [ { "id": "65f1a2b3c4d5e6f7a8b9c0d1", "url": "https://yourserver.com/webhook", "event": "agent.prompt.finished", "createdAt": "2026-03-17T10:00:00.000Z" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" } } } }, "/api/v1/vcaas/webhooks/{webhookId}": { "delete": { "operationId": "deleteWebhook", "summary": "Delete Webhook", "description": "Remove a webhook subscription.\n\nFull reference: https://www.totalum.app/docs/api/webhooks#delete-webhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The webhook ID" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Delete Webhook — Totalum docs", "url": "https://www.totalum.app/docs/api/webhooks#delete-webhook" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "true on success" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "success": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "404": { "description": "`WEBHOOK_NOT_FOUND` — Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "WEBHOOK_NOT_FOUND", "errorMessage": "Webhook not found" }, "data": null } } } } } } }, "/api/v1/vcaas/projects/{projectId}/github/connect": { "post": { "operationId": "connectGithubRepository", "summary": "Connect GitHub Repository", "description": "Connect a GitHub repository to your project using a Fine-grained Personal Access Token (PAT). This validates permissions, stores credentials, sets up branches (develop and main), and performs the initial sync. After connecting, Totalum automatically pushes to develop after every completed prompt, and pushes to main when you publish (deploy) the project.\n\nFull reference: https://www.totalum.app/docs/api/github#connect-github-repository", "tags": [ "GitHub API" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "GitHub Fine-grained Personal Access Token" }, "repositoryFullName": { "type": "string", "description": "Full repository name (e.g. \"owner/repo\")" }, "syncDirection": { "type": "string", "description": "\"totalum_to_github\" (default) or \"github_to_totalum\". Controls behavior when repo has existing content with no common history" } }, "required": [ "token", "repositoryFullName" ], "additionalProperties": true }, "example": { "token": "github_pat_xxx", "repositoryFullName": "myuser/my-repo", "syncDirection": "totalum_to_github" } } } }, "x-totalum-cost": "Free", "externalDocs": { "description": "Connect GitHub Repository — Totalum docs", "url": "https://www.totalum.app/docs/api/github#connect-github-repository" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "connected": { "type": "boolean", "description": "true if connection was successful" }, "repositoryFullName": { "type": "string", "description": "The connected repository" }, "syncAction": { "type": "string", "description": "\"push_new\", \"push\", \"pull\", \"merge_and_push\", or \"already_synced\"" }, "repoHasContent": { "type": "boolean", "description": "Whether the repo had existing content" }, "requiresRebuild": { "type": "boolean", "description": "Whether a rebuild was triggered. If true, poll GET /github/pull-status until status is \"success\" or \"error\"" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "connected": true, "repositoryFullName": "myuser/my-repo", "syncAction": "push_new", "repoHasContent": false, "requiresRebuild": false } } } } }, "400": { "description": "`MISSING_GITHUB_FIELDS` — token and repositoryFullName are required\n`INVALID_SYNC_DIRECTION` — syncDirection must be \"totalum_to_github\" or \"github_to_totalum\"\n`GITHUB_VALIDATION_FAILED` — Token invalid, missing permissions, or repo not found\n`GITHUB_SECRET_STORE_ERROR` — Failed to store GitHub credentials\n`GITHUB_SYNC_FAILED` — Initial sync with GitHub failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "MISSING_GITHUB_FIELDS", "errorMessage": "token and repositoryFullName are required" }, "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "409": { "description": "`AGENT_RUNNING` — Cannot connect while agent is running\n`SERVER_NOT_READY` — Server auto-starting, poll until Active then retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "disconnectGithub", "summary": "Disconnect GitHub", "description": "Remove the GitHub integration from your project. Deletes the stored token and repository credentials. Code already in your project is not affected.\n\nFull reference: https://www.totalum.app/docs/api/github#disconnect-github", "tags": [ "GitHub API" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Disconnect GitHub — Totalum docs", "url": "https://www.totalum.app/docs/api/github#disconnect-github" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "true on success" }, "message": { "type": "string", "description": "Confirmation message" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "success": true, "message": "GitHub disconnected successfully" } } } } }, "400": { "description": "`GITHUB_NOT_CONNECTED` — GitHub is not connected to this project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "GITHUB_NOT_CONNECTED", "errorMessage": "GitHub is not connected to this project" }, "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" } } } }, "/api/v1/vcaas/projects/{projectId}/github/status": { "get": { "operationId": "getGithubStatus", "summary": "Get GitHub Status", "description": "Check whether GitHub is connected and the token is still valid.\n\nFull reference: https://www.totalum.app/docs/api/github#get-github-status", "tags": [ "GitHub API" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Get GitHub Status — Totalum docs", "url": "https://www.totalum.app/docs/api/github#get-github-status" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "connected": { "type": "boolean", "description": "Whether GitHub is connected" }, "tokenValid": { "type": "boolean", "description": "Whether the PAT token is still valid" }, "tokenExpired": { "type": "boolean", "description": "True when the last linked PAT was detected as expired/revoked. Sticky until the user reconnects. Use this to prompt the user to reconnect" }, "repositoryFullName": { "type": "string", "description": "Connected repository, or last-known repo when tokenExpired is true" }, "developBranch": { "type": "string", "description": "\"develop\" (only if connected)" }, "productionBranch": { "type": "string", "description": "\"main\" (only if connected)" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "connected": true, "tokenValid": true, "tokenExpired": false, "repositoryFullName": "myuser/my-repo", "developBranch": "develop", "productionBranch": "main" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" } } } }, "/api/v1/vcaas/projects/{projectId}/github/pull": { "post": { "operationId": "pullFromGithub", "summary": "Pull from GitHub", "description": "Pull the latest changes from the GitHub develop branch into your project. If files changed, the server rebuilds automatically in the background. Poll the pull status endpoint until complete. This is an async operation.\n\nFull reference: https://www.totalum.app/docs/api/github#pull-from-github", "tags": [ "GitHub API" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Pull from GitHub — Totalum docs", "url": "https://www.totalum.app/docs/api/github#pull-from-github" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "status": { "type": "string", "description": "\"pulling\" (async rebuild started) or \"no_changes\"" }, "message": { "type": "string", "description": "Status message" }, "filesUpdated": { "type": "number", "description": "Number of files updated" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "status": "pulling", "message": "Pull started successfully", "filesUpdated": 5 } } } } }, "400": { "description": "`GITHUB_NOT_CONNECTED` — GitHub is not connected (connect first)\n`GITHUB_PULL_ERROR` — Failed to pull changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "GITHUB_NOT_CONNECTED", "errorMessage": "GitHub is not connected (connect first)" }, "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" }, "409": { "description": "`AGENT_RUNNING` — Cannot pull while agent is running\n`SERVER_NOT_READY` — Server auto-starting, poll until Active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/vcaas/projects/{projectId}/github/pull-status": { "get": { "operationId": "getPullStatus", "summary": "Get Pull Status", "description": "Poll this endpoint after calling Pull from GitHub, OR after a Connect GitHub call that returned requiresRebuild: true (e.g. github_to_totalum direction). Returns the current rebuild status. Auto-completes after 5 minutes.\n\nFull reference: https://www.totalum.app/docs/api/github#get-pull-status", "tags": [ "GitHub API" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Get Pull Status — Totalum docs", "url": "https://www.totalum.app/docs/api/github#get-pull-status" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "status": { "type": "string", "description": "\"pulling\", \"success\", \"error\", or null (no pull)" }, "createdAt": { "type": "string", "description": "ISO 8601 date when the pull started" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "status": "success", "createdAt": "2026-03-17T10:00:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" } } } }, "/api/v1/vcaas/projects/{projectId}/github/env": { "get": { "operationId": "downloadEnvironmentVariables", "summary": "Download Environment Variables", "description": "Get the project's environment variables as .env file content for both development and production environments. Use this to set up a local development environment or configure production deployments.\n\nFull reference: https://www.totalum.app/docs/api/github#download-environment-variables", "tags": [ "GitHub API" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The project ID" } ], "x-totalum-cost": "Free", "externalDocs": { "description": "Download Environment Variables — Totalum docs", "url": "https://www.totalum.app/docs/api/github#download-environment-variables" }, "responses": { "200": { "description": "Success. `errors` is null and `data` holds the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "null", "description": "Null on success." }, "data": { "type": "object", "properties": { "envDev": { "type": "string", "description": ".env file content for development (KEY=VALUE format, one per line)" }, "envProd": { "type": "string", "description": ".env file content for production (KEY=VALUE format, one per line)" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "errors": null, "data": { "envDev": "# Totalum Configuration\nTOTALUM_API_KEY=tlm_sk_xxx\nBETTER_AUTH_SECRET=xxxx\nNODE_ENV=development\nNEXT_PUBLIC_APP_URL=http://localhost:3000\n\n# User-defined environment variables\n...", "envProd": "# Totalum Configuration\nTOTALUM_API_KEY=tlm_sk_xxx\nBETTER_AUTH_SECRET=xxxx\nNODE_ENV=production\nNEXT_PUBLIC_APP_URL=https://my-app.totalum-project.com\n\n# User-defined environment variables\n..." } } } } }, "400": { "description": "`ENV_DOWNLOAD_ERROR` — Failed to get environment variables", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "errors": { "errorCode": "ENV_DOWNLOAD_ERROR", "errorMessage": "Failed to get environment variables" }, "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/NoCredits" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "api-key", "description": "Your Totalum API key, prefixed `tlm_sk_`. Server-side only." } }, "schemas": { "ErrorEnvelope": { "type": "object", "description": "A failed request: `data` is null and `errors` holds the code and message.", "properties": { "errors": { "$ref": "#/components/schemas/ApiError" }, "data": { "type": "null" } }, "required": [ "errors" ] }, "ApiError": { "type": "object", "properties": { "errorCode": { "type": "string", "examples": [ "PROJECT_NOT_FOUND" ] }, "errorMessage": { "type": "string", "examples": [ "Project does not exist or you don't own it" ] } }, "required": [ "errorCode", "errorMessage" ] } }, "responses": { "Unauthorized": { "description": "Missing or invalid `api-key` header. Note this is the one response that does NOT use the `{ errors, data }` envelope — it returns a bare `{ error }` string, so clients should branch on the status code rather than only checking `errors`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": true }, "example": { "error": "Unauthorized api key" } } } }, "NoCredits": { "description": "Credit balance is zero. The API requires a positive balance on every plan (`VCAAS_INSUFFICIENT_CREDITS`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }