{
  "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 5 to 40 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, the breakdown between plan and purchased credits, and the current price of every metered operation.",
      "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": "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": "Project Groups",
      "description": "Create optional folders for your Totalum projects, list them with project counts, rename them, and delete a folder without ever deleting the projects inside it.",
      "externalDocs": {
        "url": "https://www.totalum.app/docs/api/project-groups"
      }
    },
    {
      "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": "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, read backend dev server logs, and query the published site's production request 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": "Project Files",
      "description": "Browse a Totalum project's file tree, read and write individual files, and rebuild the project so your changes go live.",
      "externalDocs": {
        "url": "https://www.totalum.app/docs/api/project-files"
      }
    },
    {
      "name": "Versions",
      "description": "List a Totalum project's saved versions, read the diff a version introduced, 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, create, edit and delete records, and manage many-to-many links.",
      "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"
      }
    },
    {
      "name": "Figma API",
      "description": "Connect a Figma account to a Totalum project so the build agent can read your designs and implement them.",
      "externalDocs": {
        "url": "https://www.totalum.app/docs/api/figma"
      }
    }
  ],
  "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": "Total spendable balance — recurrentCredits + oneTimeCredits. This is the number to check before an operation"
                        },
                        "recurrentCredits": {
                          "type": "number",
                          "description": "Monthly plan credits remaining. Reset at the start of each billing period. 0 on accounts with no plan credits"
                        },
                        "oneTimeCredits": {
                          "type": "number",
                          "description": "Purchased credits remaining. These never expire"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "credits": 425,
                    "recurrentCredits": 100,
                    "oneTimeCredits": 325
                  }
                }
              }
            }
          },
          "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/credit-costs": {
      "get": {
        "operationId": "getCreditCosts",
        "summary": "Get Credit Costs",
        "description": "Retrieve the current price, in development credits, of every fixed-cost operation. Read it at runtime instead of hard-coding prices: it is the same table the API charges against, so a price change reaches your app without a release.\n\nFull reference: https://www.totalum.app/docs/api/account#get-credit-costs",
        "tags": [
          "Account"
        ],
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Get Credit Costs — Totalum docs",
          "url": "https://www.totalum.app/docs/api/account#get-credit-costs"
        },
        "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": {
                        "creditCosts": {
                          "type": "object",
                          "description": "Map of operation name to its cost in development credits",
                          "properties": {
                            "CREATE_PROJECT": {
                              "type": "number",
                              "description": "Creating a project"
                            },
                            "CREATE_DEPLOYMENT": {
                              "type": "number",
                              "description": "Deploying to production"
                            },
                            "START_SERVER": {
                              "type": "number",
                              "description": "Starting or restarting the dev server"
                            },
                            "GET_SOURCE_CODE": {
                              "type": "number",
                              "description": "Downloading the full source archive"
                            },
                            "RECOVER_VERSION": {
                              "type": "number",
                              "description": "Recovering a previous version"
                            },
                            "UPLOAD_FILE": {
                              "type": "number",
                              "description": "Uploading a file to the project"
                            },
                            "ADD_CUSTOM_DOMAIN": {
                              "type": "number",
                              "description": "Attaching a custom domain"
                            },
                            "EXPORT_PROJECT": {
                              "type": "number",
                              "description": "Exporting a project"
                            },
                            "IMPORT_PROJECT": {
                              "type": "number",
                              "description": "Importing a project"
                            },
                            "UPDATE_FILE": {
                              "type": "number",
                              "description": "Writing one file through the project-files API"
                            },
                            "REBUILD_PROJECT": {
                              "type": "number",
                              "description": "Rebuilding the project after file writes"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "creditCosts": {
                      "CREATE_PROJECT": 1,
                      "CREATE_DEPLOYMENT": 1,
                      "START_SERVER": 3,
                      "GET_SOURCE_CODE": 1,
                      "RECOVER_VERSION": 2,
                      "UPLOAD_FILE": 0.5,
                      "ADD_CUSTOM_DOMAIN": 2,
                      "EXPORT_PROJECT": 2,
                      "IMPORT_PROJECT": 6,
                      "UPDATE_FILE": 0.1,
                      "REBUILD_PROJECT": 1
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`GET_CREDIT_COSTS_ERROR` — Internal error fetching credit costs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "errors": {
                    "errorCode": "GET_CREDIT_COSTS_ERROR",
                    "errorMessage": "Error getting credit costs"
                  },
                  "data": null
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/NoCredits"
          }
        }
      }
    },
    "/api/v1/vcaas/projects/launch": {
      "post": {
        "operationId": "launchProject",
        "summary": "Launch Project",
        "description": "Create a project and start building it in one call.\n\nFull reference: https://www.totalum.app/docs/api/projects#launch-project",
        "tags": [
          "Projects"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "projectId": {
                    "type": "string",
                    "description": "Your preferred ID. Same format rules as Create Project. If it is taken, it is not an error — see the callout below"
                  },
                  "prompt": {
                    "type": "string",
                    "description": "What to build. Run as the project's first prompt, exactly as if sent to POST /agent/start"
                  },
                  "model": {
                    "type": "string",
                    "description": "\"opus\" (default) or \"sonnet\" for the first prompt. Totalum already routes automatically — set only if you are sure. An unavailable value is ignored and reported in data.agent.warnings. See Run AI Agent"
                  },
                  "effort": {
                    "type": "string",
                    "description": "How hard the agent thinks and how thoroughly it works on the first prompt: \"low\", \"medium\", \"high\" or \"xhigh\". Totalum already picks it — set only if you are sure. An invalid value is ignored and reported in data.agent.warnings"
                  },
                  "fastMode": {
                    "type": "boolean",
                    "description": "Fast mode for the first prompt (Opus only; ignored with sonnet, reported in data.agent.warnings)"
                  },
                  "description": {
                    "type": "string",
                    "description": "Project description, max 500 characters"
                  },
                  "label": {
                    "type": "string",
                    "description": "Human display name, max 80 characters"
                  },
                  "groupId": {
                    "type": "string",
                    "description": "File the project under an existing project group"
                  },
                  "files": {
                    "type": "array",
                    "description": "Attachments for the first prompt. Max 10. Each entry needs exactly one of url or content",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "description": "File name, e.g. mockup.png"
                        },
                        "description": {
                          "type": "string",
                          "description": "What the file shows — the agent reads this. imageDescription is accepted as an alias"
                        },
                        "url": {
                          "type": "string",
                          "description": "Public http(s) URL of an already-hosted file. Passed to the agent untouched; nothing is downloaded by Totalum"
                        },
                        "content": {
                          "type": "string",
                          "description": "Base64 file contents. A data:image/png;base64,… prefix is accepted and stripped. Uploaded for you, and costs UPLOAD_FILE per file"
                        }
                      },
                      "required": [
                        "name"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "creditLimits": {
                    "type": "object",
                    "description": "Monthly per-project caps, applied at creation so they cover the first run",
                    "properties": {
                      "maxDevelopmentCreditsPerMonth": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "Positive number, or null for no cap. Default: no cap"
                      },
                      "maxInfrastructureCreditsPerMonth": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "Positive number, or null for no cap. Default: 250"
                      }
                    },
                    "additionalProperties": true
                  },
                  "secrets": {
                    "type": "array",
                    "description": "Project secrets (.env values), stored before the agent starts. Max 50, names must be unique",
                    "items": {
                      "type": "object",
                      "properties": {
                        "secretName": {
                          "type": "string",
                          "description": "Environment variable name"
                        },
                        "secretValue": {
                          "type": "string",
                          "description": "The value. Never returned by any endpoint afterwards"
                        },
                        "environment": {
                          "type": "string",
                          "description": "\"development\" | \"production\" | \"both\" (default \"both\")"
                        }
                      },
                      "required": [
                        "secretName",
                        "secretValue"
                      ],
                      "additionalProperties": true
                    }
                  },
                  "figma": {
                    "type": "object",
                    "description": "Connect a Figma account so the agent can read designs linked in the prompt",
                    "properties": {
                      "token": {
                        "type": "string",
                        "description": "A Figma personal access token. Validated before anything is created, so a bad token costs you nothing"
                      }
                    },
                    "required": [
                      "token"
                    ],
                    "additionalProperties": true
                  }
                },
                "required": [
                  "projectId",
                  "prompt"
                ],
                "additionalProperties": true
              },
              "example": {
                "projectId": "barber-bookings",
                "prompt": "Build a booking system for a barbershop, with Stripe payments and email confirmations",
                "label": "Barber bookings",
                "files": [
                  {
                    "name": "brand.png",
                    "description": "our brand colours",
                    "url": "https://cdn.example.com/brand.png"
                  }
                ],
                "creditLimits": {
                  "maxDevelopmentCreditsPerMonth": 500
                },
                "secrets": [
                  {
                    "secretName": "STRIPE_SECRET_KEY",
                    "secretValue": "sk_live_xxx",
                    "environment": "production"
                  }
                ]
              }
            }
          }
        },
        "x-totalum-cost": "Uses credits",
        "externalDocs": {
          "description": "Launch Project — Totalum docs",
          "url": "https://www.totalum.app/docs/api/projects#launch-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 that was actually created. Use this for every subsequent call"
                        },
                        "requestedProjectId": {
                          "type": "string",
                          "description": "The projectId you asked for. Present only when it was taken and a suffixed name was created instead"
                        },
                        "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"
                        },
                        "label": {
                          "type": "string",
                          "description": "The display name, when one was given"
                        },
                        "groupId": {
                          "type": "string",
                          "description": "The group the project was filed under, when any"
                        },
                        "creditLimits": {
                          "type": "object",
                          "description": "The limits actually stored on the project, defaults included",
                          "properties": {
                            "maxDevelopmentCreditsPerMonth": {
                              "type": [
                                "number",
                                "null"
                              ],
                              "description": "null = no cap"
                            },
                            "maxInfrastructureCreditsPerMonth": {
                              "type": [
                                "number",
                                "null"
                              ],
                              "description": "null = no cap"
                            }
                          },
                          "additionalProperties": true
                        },
                        "files": {
                          "type": "array",
                          "description": "The attachments as the agent received them. Empty when none were sent",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string",
                                "description": "File name"
                              },
                              "imageDescription": {
                                "type": "string",
                                "description": "The description you gave, or \"\""
                              },
                              "url": {
                                "type": "string",
                                "description": "The URL the agent was given — yours for a url entry, a signed Totalum URL for an uploaded one"
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "secrets": {
                          "type": "array",
                          "description": "The secrets that were stored. Values are never echoed",
                          "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
                          }
                        },
                        "figma": {
                          "type": "object",
                          "description": "Present only when the request carried figma and the connection succeeded",
                          "properties": {
                            "connected": {
                              "type": "boolean",
                              "description": "true"
                            },
                            "account": {
                              "type": "object",
                              "description": "The linked Figma account: { id, handle, email, imgUrl }. The token is never returned",
                              "additionalProperties": true
                            }
                          },
                          "additionalProperties": true
                        },
                        "agent": {
                          "type": "object",
                          "description": "Whether the first prompt actually started",
                          "properties": {
                            "started": {
                              "type": "boolean",
                              "description": "false means the project exists but the run did not start — see warnings"
                            },
                            "warnings": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Present only when a run option (model, effort, fastMode) was ignored; one sentence per ignored value. The run still started with the defaults."
                            },
                            "status": {
                              "type": "string",
                              "description": "\"init\" when the run started; absent otherwise"
                            },
                            "message": {
                              "type": "string",
                              "description": "What to do next, in words"
                            }
                          },
                          "additionalProperties": true
                        },
                        "warnings": {
                          "type": "array",
                          "description": "Empty on the happy path. Each entry is a step that did not happen",
                          "items": {
                            "type": "object",
                            "properties": {
                              "step": {
                                "type": "string",
                                "description": "\"creditLimits\" | \"secrets\" | \"figma\" | \"files\" | \"agent\""
                              },
                              "errorCode": {
                                "type": "string",
                                "description": "Why it failed"
                              },
                              "errorMessage": {
                                "type": "string",
                                "description": "The reason, plus the endpoint that retries just that step"
                              }
                            },
                            "additionalProperties": true
                          }
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "projectId": "barber-bookings",
                    "description": "",
                    "plan": "api",
                    "createdAt": "2026-08-24T10:30:00.000Z",
                    "label": "Barber bookings",
                    "creditLimits": {
                      "maxDevelopmentCreditsPerMonth": 500,
                      "maxInfrastructureCreditsPerMonth": 250
                    },
                    "files": [
                      {
                        "name": "brand.png",
                        "imageDescription": "our brand colours",
                        "url": "https://cdn.example.com/brand.png"
                      }
                    ],
                    "secrets": [
                      {
                        "_id": "65f1a2b3c4d5e6f7a8b9c0d1",
                        "secretName": "STRIPE_SECRET_KEY",
                        "environment": "production"
                      }
                    ],
                    "agent": {
                      "started": true,
                      "status": "init",
                      "message": "Process started, can take from 5 to 40 minutes."
                    },
                    "warnings": []
                  }
                }
              }
            }
          },
          "400": {
            "description": "`MISSING_PROMPT` — prompt is required and must be a non-empty string\n`INVALID_FILES` — files is not an array, or an entry is not an object\n`TOO_MANY_FILES` — More than 10 attachments\n`INVALID_FILE_NAME` — An attachment has no name\n`INVALID_FILE_SOURCE` — An attachment has neither url nor content, or has both\n`INVALID_FILE_URL` — files[].url is not a public http(s) URL\n`INVALID_FILE_CONTENT` — files[].content is not valid base64\n`INVALID_SECRETS` — secrets is not an array, or an entry is not an object\n`TOO_MANY_SECRETS` — More than 50 secrets\n`MISSING_SECRET_FIELDS` — A secret is missing secretName or secretValue\n`DUPLICATE_SECRET_NAME` — The same secretName appears twice\n`INVALID_SECRET_ENVIRONMENT` — Not one of development, production, both\n`INVALID_CREDIT_LIMITS` — creditLimits is not an object\n`INVALID_LIMIT` — A credit limit is not a positive number (or null)\n`INVALID_FIGMA` — figma is not an object\n`MISSING_FIGMA_TOKEN` — figma.token is missing or empty\n`FIGMA_TOKEN_MALFORMED` — That does not look like a Figma token — see Check a Figma Token\n`FIGMA_TOKEN_INVALID` — Figma rejected the token\n`FIGMA_TOKEN_FORBIDDEN` — Valid token, missing the scopes Totalum needs\n`FIGMA_RATE_LIMITED` — Figma is rate-limiting the check — retry shortly\n`FIGMA_UNREACHABLE` — Figma could not be reached to check the token\n`MISSING_PROJECT_ID` — projectId is required\n`INVALID_PROJECT_NAME` — Invalid format. Lowercase letters, numbers and hyphens; must start with a letter\n`INVALID_PROJECT_NAME_LENGTH` — Project name must be between 4 and 35 characters\n`INVALID_PROJECT_GROUP` — The groupId does not exist, is not yours, or the group is full\n`LAUNCH_PROJECT_ERROR` — The project could not be created — the message carries the reason",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "description": "`INSUFFICIENT_CREDITS` — Not enough credits for the project, its attachments, or to start an agent run",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "403": {
            "description": "`MAX_PROJECTS_REACHED` — Your plan's project limit is already in use — see Create Project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "409": {
            "description": "`PROJECT_ALREADY_EXISTS` — Only when the name and six suffixed candidates were all taken",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED` — Too many Figma token checks (10/minute per account)\n`RATE_LIMIT_EXCEEDED` — You are creating projects faster than your plan allows",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/vcaas/projects": {
      "get": {
        "operationId": "listProjects",
        "summary": "List Projects",
        "description": "Get your projects, most recently created first.\n\nFull reference: https://www.totalum.app/docs/api/projects#list-projects",
        "tags": [
          "Projects"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Projects per page, 1-100 (default: 100)"
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Projects to skip, for paging (default: 0)"
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Case-insensitive match on project ID and description"
          },
          {
            "name": "sortField",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "date (default) orders by creation date; lastModified orders by when the project last changed. Any other value falls back to date"
          },
          {
            "name": "sortDirection",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "desc (default) newest first, or asc for oldest first"
          },
          {
            "name": "groupId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Return only the projects in one group. The literal value none returns only ungrouped projects"
          },
          {
            "name": "createdFrom",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Only projects created at or after this date. Inclusive. A full instant (2026-03-01T00:00:00.000Z) is used verbatim; a bare day (2026-03-01) is read as UTC"
          },
          {
            "name": "createdTo",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Only projects created at or before this date. Inclusive — a bare day is widened to that day's last millisecond, so createdFrom=X&createdTo=X returns that whole day"
          }
        ],
        "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"
                          },
                          "label": {
                            "type": "string",
                            "description": "The display name. Absent when none is set — fall back to projectId"
                          },
                          "groupId": {
                            "type": "string",
                            "description": "The group the project is filed under. Absent when ungrouped"
                          },
                          "previewImageUrl": {
                            "type": "string",
                            "description": "Screenshot of the project's home page, refreshed whenever a prompt finishes. Absent until the first prompt of a project completes"
                          },
                          "lastModifiedAt": {
                            "type": "string",
                            "description": "ISO 8601 date of the last change to the project — a prompt, a deploy, a rename, a file edit. Never null on any project, however old: it falls back through last finished run → screenshot time → updatedAt → createdAt, so you can render and compare it without a null branch. \"Same as createdAt\" is the truthful answer for a project nobody has touched since making it"
                          },
                          "productionProjectUrl": {
                            "type": "string",
                            "description": "The project's production address, {projectId}.totalum-project.com"
                          }
                        },
                        "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",
                      "label": "Acme storefront",
                      "groupId": "65f1a2b3c4d5e6f7a8b9c0d1",
                      "previewImageUrl": "https://storage.totalum.app/previews/my-app.png"
                    }
                  ]
                }
              }
            }
          },
          "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"
          }
        }
      },
      "post": {
        "operationId": "createProjectWithoutBuilding",
        "summary": "Create Project (without building)",
        "description": "Create an empty project: no prompt, no build, nothing running.\n\nFull reference: https://www.totalum.app/docs/api/projects#create-project-without-building",
        "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. Permanent — it is the organization id and the production hostname, and cannot be renamed later"
                  },
                  "description": {
                    "type": "string",
                    "description": "Project description, max 500 characters"
                  },
                  "label": {
                    "type": "string",
                    "description": "Human display name, max 80 characters. This is the part you *can* change later — see Update Project. Omitted → clients show the projectId"
                  },
                  "groupId": {
                    "type": "string",
                    "description": "File the project under an existing project group. Omitted → ungrouped"
                  }
                },
                "required": [
                  "projectId"
                ],
                "additionalProperties": true
              },
              "example": {
                "projectId": "my-app",
                "description": "A SaaS landing page",
                "label": "Acme storefront"
              }
            }
          }
        },
        "x-totalum-cost": "Uses credits",
        "externalDocs": {
          "description": "Create Project (without building) — Totalum docs",
          "url": "https://www.totalum.app/docs/api/projects#create-project-without-building"
        },
        "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"
                        },
                        "label": {
                          "type": "string",
                          "description": "The display name, when one was given. Absent when not set"
                        },
                        "groupId": {
                          "type": "string",
                          "description": "The group the project was filed under. Absent when ungrouped"
                        },
                        "requestedProjectId": {
                          "type": "string",
                          "description": "The projectId you asked for. Present only when it was taken and a suffixed name was created instead"
                        }
                      },
                      "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",
                    "label": "Acme storefront"
                  }
                }
              }
            }
          },
          "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\n`INVALID_PROJECT_GROUP` — The groupId does not exist, is not yours, or the group is full",
            "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": {
            "description": "`MAX_PROJECTS_REACHED` — Your plan's project limit is already in use — see below",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "409": {
            "description": "`PROJECT_ALREADY_EXISTS` — Only when the name and six suffixed candidates were all taken",
            "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` — You are creating projects faster than your plan allows",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                        },
                        "label": {
                          "type": "string",
                          "description": "The display name. Absent when none is set — fall back to projectId. Returned here as well as on the list so a single-project screen can show and edit the name without paging every project to find its own row"
                        },
                        "groupId": {
                          "type": "string",
                          "description": "The group the project is filed under. Absent when ungrouped"
                        },
                        "previewImageUrl": {
                          "type": "string",
                          "description": "Screenshot of the project's home page, refreshed whenever a prompt finishes. Absent until the first prompt completes"
                        },
                        "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
                        },
                        "importInProgress": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "description": "Set while an importProject call is restoring and rebuilding, otherwise null. This is the canonical signal for \"is a project import in progress\" — poll this until it is null rather than guessing from agentServerStatus, which looks identical on a cold sandbox. Reported as null once the import ends (success or failure) and also once the lock is older than 30 minutes, so it can never stay set for a job that died.",
                          "properties": {
                            "startedAt": {
                              "type": "string",
                              "description": "ISO 8601 start time, from the server that started the import — not the caller's clock"
                            },
                            "errorMessage": {
                              "type": "string",
                              "description": "Present when the import ended in failure"
                            }
                          },
                          "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 }]"
                            },
                            "_id": {
                              "type": "string",
                              "description": "The custom domain record ID"
                            },
                            "projectId": {
                              "type": "string",
                              "description": "The project the domain belongs to"
                            },
                            "deploymentId": {
                              "type": "string",
                              "description": "The deployment the domain is attached to"
                            },
                            "createdAt": {
                              "type": "string",
                              "description": "ISO 8601 date the domain was added"
                            },
                            "updatedAt": {
                              "type": "string",
                              "description": "ISO 8601 date the domain record last changed"
                            }
                          },
                          "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",
                    "label": "Acme storefront",
                    "groupId": "65f1a2b3c4d5e6f7a8b9c0d1",
                    "previewImageUrl": "https://storage.totalum.app/previews/my-app.png",
                    "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,
                    "importInProgress": 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
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateProject",
        "summary": "Update Project",
        "description": "Change a project's display label, its description, or the group it is filed under.\n\nFull reference: https://www.totalum.app/docs/api/projects#update-project",
        "tags": [
          "Projects"
        ],
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The project ID"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Display name, trimmed and capped at 80 characters. null or an empty string clears it, and clients fall back to projectId"
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Trimmed and capped at 500 characters. null or an empty string clears it"
                  },
                  "groupId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "An existing project group to file it under. null removes the project from its group"
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "label": "Acme storefront",
                "groupId": "65f1a2b3c4d5e6f7a8b9c0d1"
              }
            }
          }
        },
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Update Project — Totalum docs",
          "url": "https://www.totalum.app/docs/api/projects#update-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": "Unchanged — the id is immutable"
                        },
                        "label": {
                          "type": "string",
                          "description": "The label after the update. Absent when cleared or never set"
                        },
                        "description": {
                          "type": "string",
                          "description": "The description after the update. Empty string when none is set"
                        },
                        "groupId": {
                          "type": "string",
                          "description": "The group after the update. Absent when the project is ungrouped"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "projectId": "my-app",
                    "label": "Acme storefront",
                    "description": "A SaaS landing page",
                    "groupId": "65f1a2b3c4d5e6f7a8b9c0d1"
                  }
                }
              }
            }
          },
          "400": {
            "description": "`MISSING_PROJECT_ID` — projectId is required\n`NOTHING_TO_UPDATE` — The body contained none of label, description or groupId\n`INVALID_PROJECT_GROUP` — The group does not exist, is not yours, or already holds the maximum of 100,000 projects\n`UPDATE_PROJECT_ERROR` — Internal error updating the project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "errors": {
                    "errorCode": "NOTHING_TO_UPDATE",
                    "errorMessage": "Provide at least one of label, description or groupId"
                  },
                  "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"
                }
              }
            }
          }
        }
      },
      "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. 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}/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
                  },
                  "model": {
                    "type": "string",
                    "description": "AI model for the run. Totalum already routes each prompt to the best model automatically — set this only if you are sure of what you are doing. \"opus\" (default, the standard behaviour) or \"sonnet\" (faster and cheaper per token, less capable on hard tasks). A value that is not available is ignored, the default applies, and the reason is returned in data.warnings — the run still starts."
                  },
                  "effort": {
                    "type": "string",
                    "description": "How hard the agent thinks and how thoroughly it works: \"low\", \"medium\", \"high\" or \"xhigh\". Totalum already picks the effort for each prompt — set this only if you are sure. Omit to use the automatic choice. An invalid value is ignored and reported in data.warnings."
                  },
                  "fastMode": {
                    "type": "boolean",
                    "description": "Fast mode: same Opus quality, up to 2.5× faster, higher cost per token (billed through the metered part of the price). Opus only — ignored (with a data.warnings entry) when model is \"sonnet\" or when the value is not a boolean."
                  }
                },
                "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)"
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Present only when a run option was ignored (unknown model, invalid effort, fastMode with a non-opus model or a non-boolean). One human-readable sentence per ignored value. The run started normally with the defaults."
                        },
                        "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 5 to 40 minutes. 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` — Balance is below the minimum needed to start a run. A typical prompt costs 6 to 46 credits, so keep a working balance well above the floor — multi-prompt needs many times 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\n`REBUILD_RUNNING` — Cannot start agent while a rebuild is in progress — poll rebuild/status until it is no longer \"rebuilding\", then retry\n`GITHUB_PULL_RUNNING` — Cannot start agent while a GitHub pull is rebuilding the project — poll github/pull-status, then retry\n`IMPORT_IN_PROGRESS` — Cannot start agent while a project import is in progress — poll importInProgress 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/project-groups": {
      "post": {
        "operationId": "createProjectGroup",
        "summary": "Create Project Group",
        "description": "Create a folder for projects.\n\nFull reference: https://www.totalum.app/docs/api/project-groups#create-project-group",
        "tags": [
          "Project Groups"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Trimmed, up to 80 characters. Required — an empty name is rejected"
                  },
                  "description": {
                    "type": "string",
                    "description": "Trimmed and truncated to 500 characters rather than rejected"
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "name": "Client work",
                "description": "Everything billed to clients"
              }
            }
          }
        },
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Create Project Group — Totalum docs",
          "url": "https://www.totalum.app/docs/api/project-groups#create-project-group"
        },
        "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": {
                        "groupId": {
                          "type": "string",
                          "description": "The new group's ID — use this as groupId elsewhere"
                        },
                        "name": {
                          "type": "string",
                          "description": "The group name"
                        },
                        "description": {
                          "type": "string",
                          "description": "The description, or an empty string when none was given"
                        },
                        "createdAt": {
                          "type": "string",
                          "description": "ISO 8601 creation date"
                        },
                        "updatedAt": {
                          "type": "string",
                          "description": "ISO 8601 last-modified date"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "groupId": "65f1a2b3c4d5e6f7a8b9c0d1",
                    "name": "Client work",
                    "description": "Everything billed to clients",
                    "createdAt": "2026-08-04T10:00:00.000Z",
                    "updatedAt": "2026-08-04T10:00:00.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "`CREATE_PROJECT_GROUP_ERROR` — Name missing or longer than 80 characters, or the account already has 3,000 groups",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "errors": {
                    "errorCode": "CREATE_PROJECT_GROUP_ERROR",
                    "errorMessage": "Group name is required"
                  },
                  "data": null
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/NoCredits"
          }
        }
      },
      "get": {
        "operationId": "listProjectGroups",
        "summary": "List Project Groups",
        "description": "Your groups, newest first, each with the number of projects currently filed under it.\n\nFull reference: https://www.totalum.app/docs/api/project-groups#list-project-groups",
        "tags": [
          "Project Groups"
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Case-insensitive match on the group name only"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Page size, default 100, maximum 200"
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Groups to skip, for paging (default: 0)"
          }
        ],
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "List Project Groups — Totalum docs",
          "url": "https://www.totalum.app/docs/api/project-groups#list-project-groups"
        },
        "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 group objects, newest first",
                      "items": {
                        "type": "object",
                        "properties": {
                          "groupId": {
                            "type": "string",
                            "description": "The group ID"
                          },
                          "name": {
                            "type": "string",
                            "description": "The group name"
                          },
                          "description": {
                            "type": "string",
                            "description": "The description, or an empty string"
                          },
                          "createdAt": {
                            "type": "string",
                            "description": "ISO 8601 creation date"
                          },
                          "updatedAt": {
                            "type": "string",
                            "description": "ISO 8601 last-modified date"
                          },
                          "projectCount": {
                            "type": "number",
                            "description": "How many of your projects are filed under this group"
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": [
                    {
                      "groupId": "65f1a2b3c4d5e6f7a8b9c0d1",
                      "name": "Client work",
                      "description": "Everything billed to clients",
                      "createdAt": "2026-08-04T10:00:00.000Z",
                      "updatedAt": "2026-08-04T10:00:00.000Z",
                      "projectCount": 12
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`LIST_PROJECT_GROUPS_ERROR` — Internal error listing project groups",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "errors": {
                    "errorCode": "LIST_PROJECT_GROUPS_ERROR",
                    "errorMessage": "Error listing project groups"
                  },
                  "data": null
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/NoCredits"
          }
        }
      }
    },
    "/api/v1/vcaas/project-groups/{groupId}": {
      "get": {
        "operationId": "getProjectGroup",
        "summary": "Get Project Group",
        "description": "One group, with its current project count.\n\nFull reference: https://www.totalum.app/docs/api/project-groups#get-project-group",
        "tags": [
          "Project Groups"
        ],
        "parameters": [
          {
            "name": "groupId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The group ID"
          }
        ],
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Get Project Group — Totalum docs",
          "url": "https://www.totalum.app/docs/api/project-groups#get-project-group"
        },
        "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": {
                        "groupId": {
                          "type": "string",
                          "description": "The group ID"
                        },
                        "name": {
                          "type": "string",
                          "description": "The group name"
                        },
                        "description": {
                          "type": "string",
                          "description": "The description, or an empty string"
                        },
                        "createdAt": {
                          "type": "string",
                          "description": "ISO 8601 creation date"
                        },
                        "updatedAt": {
                          "type": "string",
                          "description": "ISO 8601 last-modified date"
                        },
                        "projectCount": {
                          "type": "number",
                          "description": "How many of your projects are filed under this group"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "groupId": "65f1a2b3c4d5e6f7a8b9c0d1",
                    "name": "Client work",
                    "description": "",
                    "createdAt": "2026-08-04T10:00:00.000Z",
                    "updatedAt": "2026-08-04T10:00:00.000Z",
                    "projectCount": 12
                  }
                }
              }
            }
          },
          "400": {
            "description": "`GET_PROJECT_GROUP_ERROR` — Internal error getting the project group",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/NoCredits"
          },
          "404": {
            "description": "`PROJECT_GROUP_NOT_FOUND` — No such group, the id is malformed, or it is not yours",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "errors": {
                    "errorCode": "PROJECT_GROUP_NOT_FOUND",
                    "errorMessage": "Project group not found"
                  },
                  "data": null
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateProjectGroup",
        "summary": "Update Project Group",
        "description": "Rename a group or change its description. Keys you do not send are left alone, so renaming a group cannot blank its description.\n\nFull reference: https://www.totalum.app/docs/api/project-groups#update-project-group",
        "tags": [
          "Project Groups"
        ],
        "parameters": [
          {
            "name": "groupId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The group ID"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Trimmed, up to 80 characters. Sending an empty name is an error — omit the key instead"
                  },
                  "description": {
                    "type": "string",
                    "description": "Trimmed and truncated to 500 characters. Send an empty string to clear it"
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "name": "Client work 2026"
              }
            }
          }
        },
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Update Project Group — Totalum docs",
          "url": "https://www.totalum.app/docs/api/project-groups#update-project-group"
        },
        "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": {
                        "groupId": {
                          "type": "string",
                          "description": "The group ID"
                        },
                        "name": {
                          "type": "string",
                          "description": "The name after the update"
                        },
                        "description": {
                          "type": "string",
                          "description": "The description after the update"
                        },
                        "createdAt": {
                          "type": "string",
                          "description": "ISO 8601 creation date"
                        },
                        "updatedAt": {
                          "type": "string",
                          "description": "ISO 8601 last-modified date"
                        },
                        "projectCount": {
                          "type": "number",
                          "description": "How many of your projects are filed under this group"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "groupId": "65f1a2b3c4d5e6f7a8b9c0d1",
                    "name": "Client work 2026",
                    "description": "Everything billed to clients",
                    "createdAt": "2026-08-04T10:00:00.000Z",
                    "updatedAt": "2026-08-04T12:30:00.000Z",
                    "projectCount": 12
                  }
                }
              }
            }
          },
          "400": {
            "description": "`UPDATE_PROJECT_GROUP_ERROR` — Empty name, name longer than 80 characters, or an internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/NoCredits"
          },
          "404": {
            "description": "`PROJECT_GROUP_NOT_FOUND` — No such group, the id is malformed, or it is not yours",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "errors": {
                    "errorCode": "PROJECT_GROUP_NOT_FOUND",
                    "errorMessage": "Project group not found"
                  },
                  "data": null
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteProjectGroup",
        "summary": "Delete Project Group",
        "description": "Delete the folder only.\n\nFull reference: https://www.totalum.app/docs/api/project-groups#delete-project-group",
        "tags": [
          "Project Groups"
        ],
        "parameters": [
          {
            "name": "groupId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The group ID"
          }
        ],
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Delete Project Group — Totalum docs",
          "url": "https://www.totalum.app/docs/api/project-groups#delete-project-group"
        },
        "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": {
                        "deleted": {
                          "type": "boolean",
                          "description": "true on successful deletion"
                        },
                        "releasedProjects": {
                          "type": "number",
                          "description": "How many projects became ungrouped. None were deleted"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "deleted": true,
                    "releasedProjects": 12
                  }
                }
              }
            }
          },
          "400": {
            "description": "`DELETE_PROJECT_GROUP_ERROR` — Internal error deleting the project group",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/NoCredits"
          },
          "404": {
            "description": "`PROJECT_GROUP_NOT_FOUND` — No such group, the id is malformed, or it is not yours",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "errors": {
                    "errorCode": "PROJECT_GROUP_NOT_FOUND",
                    "errorMessage": "Project group not found"
                  },
                  "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 importInProgress is null."
                  }
                }
              }
            }
          },
          "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}/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`REBUILD_RUNNING` — A rebuild is in progress — poll GET /projects/:projectId/rebuild/status until it is no longer \"rebuilding\", then retry\n`GITHUB_PULL_RUNNING` — A GitHub pull is rebuilding the project — poll GET /projects/:projectId/github/pull-status until it is no longer \"pulling\", then retry\n`IMPORT_IN_PROGRESS` — A project import is in progress — poll GET /projects/:projectId until importInProgress is null, then retry\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 — literally the dev server's log file on the project's sandbox VM.\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}/backend/prod/logs": {
      "get": {
        "operationId": "getProductionLogs",
        "summary": "Get Production Logs",
        "description": "Query the request logs of the published project — the one running on Cloudflare at your production URL. Each record is one request, with the console output and exceptions that happened while serving it.\n\nFull reference: https://www.totalum.app/docs/api/server#get-production-logs",
        "tags": [
          "Server"
        ],
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The project ID"
          },
          {
            "name": "getOnlyLastLogs",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "true returns only the most recent records. Default false"
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Start of the range, ISO 8601 (e.g. 2026-08-01T00:00:00Z). Must be within the last 3 days"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "End of the range, ISO 8601. Must be within the last 3 days"
          },
          {
            "name": "regexSearch",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Regex or plain string to filter by. Returns the matching entries plus nearby lines — the fastest way to find a specific log"
          }
        ],
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Get Production Logs — Totalum docs",
          "url": "https://www.totalum.app/docs/api/server#get-production-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",
                        "array"
                      ],
                      "description": "Passthrough from the log pipeline. Read the records from data.records when present, otherwise data is itself the array of records",
                      "properties": {
                        "records": {
                          "type": "array",
                          "description": "The matching request records",
                          "items": {
                            "type": "object",
                            "properties": {
                              "EventTimestampMs": {
                                "type": "number",
                                "description": "When the request was served, epoch milliseconds"
                              },
                              "Outcome": {
                                "type": "string",
                                "description": "How the request ended, e.g. ok, exception, canceled"
                              },
                              "WallTimeMs": {
                                "type": "number",
                                "description": "Wall-clock duration of the request"
                              },
                              "CPUTimeMs": {
                                "type": "number",
                                "description": "CPU time consumed by the request"
                              },
                              "Event": {
                                "type": "object",
                                "properties": {
                                  "Request": {
                                    "type": "object",
                                    "properties": {
                                      "URL": {
                                        "type": "string",
                                        "description": "The requested URL"
                                      },
                                      "Method": {
                                        "type": "string",
                                        "description": "HTTP method"
                                      }
                                    },
                                    "additionalProperties": true
                                  },
                                  "Response": {
                                    "type": "object",
                                    "properties": {
                                      "Status": {
                                        "type": "number",
                                        "description": "HTTP status returned"
                                      }
                                    },
                                    "additionalProperties": true
                                  }
                                },
                                "additionalProperties": true
                              },
                              "Logs": {
                                "type": "array",
                                "description": "Console output produced while serving this request",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "Level": {
                                      "type": "string",
                                      "description": "log, info, warn, error or debug"
                                    },
                                    "Message": {
                                      "type": "array",
                                      "description": "The logged values"
                                    },
                                    "TimestampMs": {
                                      "type": "number",
                                      "description": "When the line was written, epoch milliseconds"
                                    }
                                  },
                                  "additionalProperties": true
                                }
                              },
                              "Exceptions": {
                                "type": "array",
                                "description": "Uncaught exceptions thrown while serving this request",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "Name": {
                                      "type": "string",
                                      "description": "Exception class, e.g. TypeError"
                                    },
                                    "Message": {
                                      "type": "string",
                                      "description": "Exception message"
                                    },
                                    "TimestampMs": {
                                      "type": "number",
                                      "description": "When it was thrown, epoch milliseconds"
                                    }
                                  },
                                  "additionalProperties": true
                                }
                              }
                            },
                            "additionalProperties": true
                          }
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "records": [
                      {
                        "EventTimestampMs": 1785840843120,
                        "Outcome": "ok",
                        "WallTimeMs": 128,
                        "CPUTimeMs": 14,
                        "Event": {
                          "Request": {
                            "URL": "https://my-app.totalum-project.com/api/orders",
                            "Method": "GET"
                          },
                          "Response": {
                            "Status": 500
                          }
                        },
                        "Logs": [
                          {
                            "Level": "error",
                            "Message": [
                              "Cannot read properties of undefined"
                            ],
                            "TimestampMs": 1785840843118
                          }
                        ],
                        "Exceptions": [
                          {
                            "Name": "TypeError",
                            "Message": "Cannot read properties of undefined",
                            "TimestampMs": 1785840843119
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "`MISSING_PROJECT_ID` — projectId is required\n`PROD_LOGS_WORKER_ERROR` — The production log pipeline could not serve the query",
            "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"
                }
              }
            }
          },
          "429": {
            "description": "`PLAN_LIMIT_REACHED` — Your plan's production-log request limit was reached. Wait for the reset or upgrade",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "errors": {
                    "errorCode": "PLAN_LIMIT_REACHED",
                    "errorMessage": "Production logs request limit reached for your plan. Please upgrade or wait for the limit to reset."
                  },
                  "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. Absent on a legacy project — see below"
                        },
                        "downloadUrl": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Signed download URL (expires in minutes). Absent on a legacy project — see below"
                        },
                        "mode": {
                          "type": "string",
                          "description": "Present only on a legacy project, where it is the literal \"mongodb\" and there is no archive to download"
                        }
                      },
                      "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}/files/tree": {
      "get": {
        "operationId": "getProjectTree",
        "summary": "Get Project Tree",
        "description": "The project's files and folders, as a flat, sorted list. node_modules, .next, .git, dist and other build output are never included.\n\nFull reference: https://www.totalum.app/docs/api/project-files#get-project-tree",
        "tags": [
          "Project Files"
        ],
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The project ID"
          },
          {
            "name": "path",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Limit the tree to one subfolder, e.g. src/app. Default: the whole project"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Page size. Default 2000, max 5000"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Entries to skip. Default 0"
          }
        ],
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Get Project Tree — Totalum docs",
          "url": "https://www.totalum.app/docs/api/project-files#get-project-tree"
        },
        "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": {
                        "entries": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "path": {
                                "type": "string",
                                "description": "Path relative to the project root, e.g. src/app/page.tsx"
                              },
                              "name": {
                                "type": "string",
                                "description": "File or folder name"
                              },
                              "type": {
                                "type": "string",
                                "description": "\"file\" or \"folder\""
                              },
                              "size": {
                                "type": "number",
                                "description": "Size in bytes. Files only"
                              },
                              "depth": {
                                "type": "number",
                                "description": "0 at the project root"
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "totalEntries": {
                          "type": "number",
                          "description": "Entries matching the request before paging"
                        },
                        "offset": {
                          "type": "number",
                          "description": "The offset used"
                        },
                        "limit": {
                          "type": "number",
                          "description": "The limit used"
                        },
                        "hasMore": {
                          "type": "boolean",
                          "description": "true when more entries follow"
                        },
                        "commitSha": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Git commit the tree was read from"
                        },
                        "filesCount": {
                          "type": "number",
                          "description": "Files tracked in the project, before exclusions"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "entries": [
                      {
                        "path": "src/app",
                        "name": "app",
                        "type": "folder",
                        "depth": 1
                      },
                      {
                        "path": "src/app/layout.tsx",
                        "name": "layout.tsx",
                        "type": "file",
                        "size": 1284,
                        "depth": 2
                      },
                      {
                        "path": "src/app/page.tsx",
                        "name": "page.tsx",
                        "type": "file",
                        "size": 3902,
                        "depth": 2
                      }
                    ],
                    "totalEntries": 3,
                    "offset": 0,
                    "limit": 100,
                    "hasMore": false,
                    "commitSha": "a1b2c3d",
                    "filesCount": 47
                  }
                }
              }
            }
          },
          "400": {
            "description": "`MISSING_PROJECT_ID` — projectId is required\n`INVALID_PATH` — The path is absolute, contains .., or points inside an excluded folder",
            "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"
                }
              }
            }
          },
          "413": {
            "description": "`PROJECT_TOO_LARGE` — The project archive is too large to browse through the API — download it instead",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/vcaas/projects/{projectId}/files/content": {
      "get": {
        "operationId": "getFileContent",
        "summary": "Get File Content",
        "description": "The complete content of one file. Files up to 1 MB.\n\nFull reference: https://www.totalum.app/docs/api/project-files#get-file-content",
        "tags": [
          "Project Files"
        ],
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The project ID"
          },
          {
            "name": "path",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Path relative to the project root, e.g. src/app/page.tsx"
          }
        ],
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Get File Content — Totalum docs",
          "url": "https://www.totalum.app/docs/api/project-files#get-file-content"
        },
        "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": {
                        "path": {
                          "type": "string",
                          "description": "The normalised path"
                        },
                        "name": {
                          "type": "string",
                          "description": "File name"
                        },
                        "size": {
                          "type": "number",
                          "description": "Size of the stored file in bytes"
                        },
                        "encoding": {
                          "type": "string",
                          "description": "\"utf8\" for text, \"base64\" for binary"
                        },
                        "content": {
                          "type": "string",
                          "description": "The file content, in encoding"
                        },
                        "commitSha": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Git commit the file was read from"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "path": "src/app/page.tsx",
                    "name": "page.tsx",
                    "size": 62,
                    "encoding": "utf8",
                    "content": "export default function Page() {\n  return <h1>Hello</h1>;\n}\n",
                    "commitSha": "a1b2c3d"
                  }
                }
              }
            }
          },
          "400": {
            "description": "`INVALID_PATH` — The path is absolute, contains .., or points inside an excluded folder",
            "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`FILE_NOT_FOUND` — No file at that path",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "errors": {
                    "errorCode": "FILE_NOT_FOUND",
                    "errorMessage": "No file at \"src/app/missing.tsx\" in this project."
                  },
                  "data": null
                }
              }
            }
          },
          "413": {
            "description": "`FILE_TOO_LARGE` — The file is larger than 1 MB — download the source archive instead",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "writeFileContent",
        "summary": "Write File Content",
        "description": "Replace a file completely, or create it if it does not exist. Missing parent folders are created for you. Content up to 512 KB.\n\nFull reference: https://www.totalum.app/docs/api/project-files#write-file-content",
        "tags": [
          "Project Files"
        ],
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The project ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "path": {
                    "type": "string",
                    "description": "Path relative to the project root"
                  },
                  "content": {
                    "type": "string",
                    "description": "The complete new content. Send \"\" to empty the file"
                  },
                  "encoding": {
                    "type": "string",
                    "description": "\"utf8\" (default) or \"base64\" for binary"
                  }
                },
                "required": [
                  "path",
                  "content"
                ],
                "additionalProperties": true
              },
              "example": {
                "path": "src/app/page.tsx",
                "content": "export default function Page() {\n  return <h1>Hi</h1>;\n}\n"
              }
            }
          }
        },
        "x-totalum-cost": "1 credit",
        "externalDocs": {
          "description": "Write File Content — Totalum docs",
          "url": "https://www.totalum.app/docs/api/project-files#write-file-content"
        },
        "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": {
                        "path": {
                          "type": "string",
                          "description": "The normalised path"
                        },
                        "bytesWritten": {
                          "type": "number",
                          "description": "Bytes written"
                        },
                        "created": {
                          "type": "boolean",
                          "description": "true when the file did not exist before"
                        },
                        "commitSha": {
                          "type": "string",
                          "description": "The commit this write produced"
                        },
                        "filesCount": {
                          "type": "number",
                          "description": "Files tracked after the write"
                        },
                        "rebuildRequired": {
                          "type": "boolean",
                          "description": "Always true — call POST /rebuild to make it live"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "path": "src/app/page.tsx",
                    "bytesWritten": 58,
                    "created": false,
                    "commitSha": "d4e5f6a",
                    "filesCount": 47,
                    "rebuildRequired": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "`INVALID_PATH` — The path is absolute, contains .., or points inside an excluded folder\n`MISSING_CONTENT` — content is required and must be a string\n`INVALID_ENCODING` — encoding must be \"utf8\" or \"base64\"\n`FREE_PLAN_NO_SOURCE_EDITING` — Editing source code requires a paid plan\n`NO_SANDBOX` — The project has no sandbox yet — run the agent once first\n`SANDBOX_NOT_ACTIVE` — The sandbox is starting or archived — wait and retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "errors": {
                    "errorCode": "INVALID_PATH",
                    "errorMessage": "path must not contain \"..\""
                  },
                  "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"
          },
          "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` — The AI agent is running — wait for it to finish\n`DEPLOYMENT_RUNNING` — A deployment is in progress — wait for it to finish",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "413": {
            "description": "`FILE_TOO_LARGE` — Content is larger than 512 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/vcaas/projects/{projectId}/rebuild": {
      "post": {
        "operationId": "rebuildProject",
        "summary": "Rebuild Project",
        "description": "Rebuild the project and reload the server, so files you wrote become live. Asynchronous: it returns immediately and the rebuild continues in the background.\n\nFull reference: https://www.totalum.app/docs/api/project-files#rebuild-project",
        "tags": [
          "Project Files"
        ],
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The project ID"
          }
        ],
        "x-totalum-cost": "1 credit",
        "externalDocs": {
          "description": "Rebuild Project — Totalum docs",
          "url": "https://www.totalum.app/docs/api/project-files#rebuild-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"
                        },
                        "status": {
                          "type": "string",
                          "description": "Always \"rebuilding\""
                        },
                        "startedAt": {
                          "type": "string",
                          "description": "ISO 8601 start time"
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable next step"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "projectId": "my-app",
                    "status": "rebuilding",
                    "startedAt": "2026-08-02T09:14:03.120Z",
                    "message": "Rebuild started. It usually takes 1-4 minutes. Poll GET /projects/:projectId/rebuild/status until status is \"success\" or \"error\"."
                  }
                }
              }
            }
          },
          "400": {
            "description": "`REBUILD_LIMIT_REACHED` — Your plan's rebuild limit was reached — wait or upgrade\n`NO_SANDBOX` — The project has no sandbox yet — run the agent once first\n`SANDBOX_NOT_ACTIVE` — The sandbox is starting or archived — wait and retry",
            "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"
                }
              }
            }
          },
          "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": "`REBUILD_RUNNING` — A rebuild is already in progress for this project\n`AGENT_RUNNING` — The AI agent is running — wait for it to finish\n`DEPLOYMENT_RUNNING` — A deployment is in progress — wait for it to finish",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/vcaas/projects/{projectId}/rebuild/status": {
      "get": {
        "operationId": "getRebuildStatus",
        "summary": "Get Rebuild Status",
        "description": "Poll this after POST /rebuild. Every 10–15 seconds is plenty.\n\nFull reference: https://www.totalum.app/docs/api/project-files#get-rebuild-status",
        "tags": [
          "Project Files"
        ],
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The project ID"
          }
        ],
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Get Rebuild Status — Totalum docs",
          "url": "https://www.totalum.app/docs/api/project-files#get-rebuild-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": "\"idle\", \"rebuilding\", \"success\" or \"error\""
                        },
                        "startedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "ISO 8601 start time"
                        },
                        "finishedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "ISO 8601 finish time"
                        },
                        "elapsedSeconds": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "description": "How long it has been running, or took"
                        },
                        "livePreviewUrl": {
                          "type": "string",
                          "description": "Preview URL after a successful rebuild"
                        },
                        "errorCode": {
                          "type": "string",
                          "description": "Present when status is \"error\""
                        },
                        "errorMessage": {
                          "type": "string",
                          "description": "Present when status is \"error\""
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "projectId": "my-app",
                    "status": "success",
                    "startedAt": "2026-08-02T09:14:03.120Z",
                    "finishedAt": "2026-08-02T09:16:41.902Z",
                    "elapsedSeconds": 159,
                    "livePreviewUrl": "https://my-app.totalum-project.com"
                  }
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      }
    },
    "/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 this for Recover Version"
                              },
                              "name": {
                                "type": "string",
                                "description": "Version display name"
                              },
                              "commitSha": {
                                "type": "string",
                                "description": "Git commit this version points at — use this for Get Version Diff"
                              },
                              "commitMessage": {
                                "type": "string",
                                "description": "Git commit message"
                              },
                              "prompt": {
                                "type": "string",
                                "description": "The prompt that created this version"
                              },
                              "gcsUploaded": {
                                "type": "boolean",
                                "description": "Whether the version's snapshot finished uploading to long-term storage"
                              },
                              "recoveredVersionId": {
                                "type": "string",
                                "description": "Present when this version was produced by recovering another one — the id of the version that was restored"
                              },
                              "createdAt": {
                                "type": "string",
                                "description": "ISO 8601 creation date"
                              },
                              "updatedAt": {
                                "type": "string",
                                "description": "ISO 8601 last-modified 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",
                        "commitSha": "9f2c1ab",
                        "commitMessage": "Added contact form",
                        "prompt": "Add a contact form to the landing page",
                        "gcsUploaded": true,
                        "createdAt": "2026-03-11T10:45:00.000Z",
                        "updatedAt": "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}/version-diff": {
      "get": {
        "operationId": "getVersionDiff",
        "summary": "Get Version Diff",
        "description": "The unified diff a single version introduced, as raw text — the same format git diff produces.\n\nFull reference: https://www.totalum.app/docs/api/versions#get-version-diff",
        "tags": [
          "Versions"
        ],
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The project ID"
          },
          {
            "name": "commitSha",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The commitSha of the version, from List Versions. 7 to 40 hexadecimal characters"
          }
        ],
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Get Version Diff — Totalum docs",
          "url": "https://www.totalum.app/docs/api/versions#get-version-diff"
        },
        "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": {
                        "commitSha": {
                          "type": "string",
                          "description": "The commit the diff was produced from"
                        },
                        "diff": {
                          "type": "string",
                          "description": "Raw unified diff text. Empty string when the commit changed nothing tracked"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "commitSha": "9f2c1ab",
                    "diff": "diff --git a/src/app/page.tsx b/src/app/page.tsx\n--- a/src/app/page.tsx\n+++ b/src/app/page.tsx\n@@ -12,6 +12,9 @@\n   return (\n     <main>\n+      <ContactForm />\n     </main>\n   );\n"
                  }
                }
              }
            }
          },
          "400": {
            "description": "`MISSING_PROJECT_ID` — projectId is required\n`MISSING_COMMIT_SHA` — The commitSha query parameter is required\n`INVALID_COMMIT_SHA` — commitSha must be 7 to 40 hexadecimal characters\n`NO_ACTIVE_SANDBOX` — The project's sandbox is not running — start the project and try again",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "errors": {
                    "errorCode": "INVALID_COMMIT_SHA",
                    "errorMessage": "commitSha must be 7 to 40 hexadecimal characters"
                  },
                  "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}/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
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteDatabaseRecord",
        "summary": "Delete Database Record",
        "description": "Permanently delete one record by its ID.\n\nFull reference: https://www.totalum.app/docs/api/database#delete-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 delete"
          },
          {
            "name": "tableName",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The table name (use type from the tables-structure response)"
          }
        ],
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Delete Database Record — Totalum docs",
          "url": "https://www.totalum.app/docs/api/database#delete-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",
                      "properties": {
                        "deleted": {
                          "type": "boolean",
                          "description": "true on successful deletion"
                        },
                        "recordId": {
                          "type": "string",
                          "description": "The ID of the record that was deleted"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "deleted": true,
                    "recordId": "65f1a2b3c4d5e6f7a8b9c0d1"
                  }
                }
              }
            }
          },
          "400": {
            "description": "`MISSING_PROJECT_ID` — projectId is required\n`MISSING_RECORD_ID` — recordId is required\n`MISSING_TABLE_NAME` — tableName is required as a query parameter\n`TABLE_NOT_FOUND` — Table doesn't exist in the project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "errors": {
                    "errorCode": "MISSING_TABLE_NAME",
                    "errorMessage": "tableName is required (query parameter)"
                  },
                  "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}/link": {
      "post": {
        "operationId": "linkRecords",
        "summary": "Link Records",
        "description": "Link two records across a many-to-many relation.\n\nFull reference: https://www.totalum.app/docs/api/database#link-records",
        "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 on this side of the relation"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tableName": {
                    "type": "string",
                    "description": "The table recordId belongs to (use type from the tables-structure response)"
                  },
                  "propertyId": {
                    "type": "string",
                    "description": "The objectReference property on tableName that holds the relation"
                  },
                  "referenceId": {
                    "type": "string",
                    "description": "The _id of the record on the other side of the relation"
                  }
                },
                "required": [
                  "tableName",
                  "propertyId",
                  "referenceId"
                ],
                "additionalProperties": true
              },
              "example": {
                "tableName": "customers",
                "propertyId": "tags",
                "referenceId": "65f1a2b3c4d5e6f7a8b9c0d2"
              }
            }
          }
        },
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Link Records — Totalum docs",
          "url": "https://www.totalum.app/docs/api/database#link-records"
        },
        "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": {
                        "linked": {
                          "type": "boolean",
                          "description": "true when the link exists after the call"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "linked": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "`MISSING_PROJECT_ID` — projectId is required\n`MISSING_RECORD_ID` — recordId is required\n`MISSING_TABLE_NAME` — tableName is required\n`MISSING_PROPERTY_ID` — propertyId is required — the relation field on the table\n`MISSING_REFERENCE_ID` — referenceId is required — the _id of the record to link\n`TABLE_NOT_FOUND` — Table doesn't exist in the project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                },
                "example": {
                  "errors": {
                    "errorCode": "MISSING_PROPERTY_ID",
                    "errorMessage": "propertyId is required (the tableLink field holding the relation)"
                  },
                  "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"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "unlinkRecords",
        "summary": "Unlink Records",
        "description": "Remove a many-to-many link. The two records are untouched — only the link between them goes.\n\nFull reference: https://www.totalum.app/docs/api/database#unlink-records",
        "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 on this side of the relation"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tableName": {
                    "type": "string",
                    "description": "The table recordId belongs to (use type from the tables-structure response)"
                  },
                  "propertyId": {
                    "type": "string",
                    "description": "The objectReference property on tableName that holds the relation"
                  },
                  "referenceId": {
                    "type": "string",
                    "description": "The _id of the record on the other side of the relation"
                  }
                },
                "required": [
                  "tableName",
                  "propertyId",
                  "referenceId"
                ],
                "additionalProperties": true
              },
              "example": {
                "tableName": "customers",
                "propertyId": "tags",
                "referenceId": "65f1a2b3c4d5e6f7a8b9c0d2"
              }
            }
          }
        },
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Unlink Records — Totalum docs",
          "url": "https://www.totalum.app/docs/api/database#unlink-records"
        },
        "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": {
                        "unlinked": {
                          "type": "boolean",
                          "description": "true when the link is gone after the call"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "errors": null,
                  "data": {
                    "unlinked": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "`MISSING_PROJECT_ID` — projectId is required\n`MISSING_RECORD_ID` — recordId is required\n`MISSING_TABLE_NAME` — tableName is required\n`MISSING_PROPERTY_ID` — propertyId is required — the relation field on the table\n`MISSING_REFERENCE_ID` — referenceId is required — the _id of the record to unlink\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"
                              },
                              "updatedAt": {
                                "type": "string",
                                "description": "ISO 8601 date of the last change to this subscription"
                              }
                            },
                            "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"
          }
        }
      }
    },
    "/api/v1/vcaas/projects/{projectId}/figma/connect": {
      "post": {
        "operationId": "connectFigma",
        "summary": "Connect Figma",
        "description": "Link a Figma account to your project. The token is validated against Figma's own API before anything is stored, so an invalid token changes nothing and you get back the specific reason rather than a generic failure.\n\nFull reference: https://www.totalum.app/docs/api/figma#connect-figma",
        "tags": [
          "Figma 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": "Figma personal access token, or an Organization/Enterprise plan access token"
                  }
                },
                "required": [
                  "token"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Connect Figma — Totalum docs",
          "url": "https://www.totalum.app/docs/api/figma#connect-figma"
        },
        "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 the connection succeeded"
                        },
                        "account": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "description": "Figma user ID"
                            },
                            "handle": {
                              "type": "string",
                              "description": "Figma display name"
                            },
                            "email": {
                              "type": "string",
                              "description": "Email on the Figma account"
                            },
                            "imgUrl": {
                              "type": "string",
                              "description": "Avatar URL"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/NoCredits"
          }
        }
      },
      "delete": {
        "operationId": "disconnectFigma",
        "summary": "Disconnect Figma",
        "description": "Remove the Figma integration from your project. The stored token is deleted and the agent stops being able to read your designs. Nothing in your Figma account changes.\n\nFull reference: https://www.totalum.app/docs/api/figma#disconnect-figma",
        "tags": [
          "Figma API"
        ],
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Disconnect Figma — Totalum docs",
          "url": "https://www.totalum.app/docs/api/figma#disconnect-figma"
        },
        "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": {
                        "disconnected": {
                          "type": "boolean",
                          "description": "true on success"
                        },
                        "message": {
                          "type": "string",
                          "description": "Confirmation message"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/NoCredits"
          }
        }
      }
    },
    "/api/v1/vcaas/figma/validate": {
      "post": {
        "operationId": "checkAFigmaToken",
        "summary": "Check a Figma Token",
        "description": "Check a token against Figma without connecting it to anything. Nothing is stored and no project is involved — it answers \"would this token work?\", which is what a connect form needs before it commits. The account behind a valid token comes back so you can show *which* Figma user is about to be linked.\n\nFull reference: https://www.totalum.app/docs/api/figma#check-a-figma-token",
        "tags": [
          "Figma API"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "Figma personal access token, or an Organization/Enterprise plan access token"
                  }
                },
                "required": [
                  "token"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Check a Figma Token — Totalum docs",
          "url": "https://www.totalum.app/docs/api/figma#check-a-figma-token"
        },
        "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": {
                        "valid": {
                          "type": "boolean",
                          "description": "true when Figma accepted the token with the scopes Totalum needs"
                        },
                        "account": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "description": "Figma user ID"
                            },
                            "handle": {
                              "type": "string",
                              "description": "Figma display name"
                            },
                            "email": {
                              "type": "string",
                              "description": "Email on the Figma account"
                            },
                            "imgUrl": {
                              "type": "string",
                              "description": "Avatar URL"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/NoCredits"
          }
        }
      }
    },
    "/api/v1/vcaas/projects/{projectId}/figma/status": {
      "get": {
        "operationId": "getFigmaStatus",
        "summary": "Get Figma Status",
        "description": "Check whether Figma is connected and which account is linked.\n\nFull reference: https://www.totalum.app/docs/api/figma#get-figma-status",
        "tags": [
          "Figma API"
        ],
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "verify",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "true re-checks the stored token against Figma. This costs a live Figma call — use it when a screen opens, not on a poll"
          }
        ],
        "x-totalum-cost": "Free",
        "externalDocs": {
          "description": "Get Figma Status — Totalum docs",
          "url": "https://www.totalum.app/docs/api/figma#get-figma-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 Figma is connected"
                        },
                        "account": {
                          "type": "object",
                          "description": "The linked account (id, handle, email, imgUrl)",
                          "additionalProperties": true
                        },
                        "connectedAt": {
                          "type": "string",
                          "description": "When the connection was made"
                        },
                        "tokenValid": {
                          "type": "boolean",
                          "description": "Only with verify=true — whether Figma still accepts the token"
                        },
                        "tokenError": {
                          "type": "string",
                          "description": "Only with verify=true and a failure — the specific reason"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "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"
            }
          }
        }
      }
    }
  }
}