GitHub API

Connect a GitHub repository to your project for two-way sync. After connecting, Totalum auto-pushes to develop after every completed prompt and pushes to main when you publish (deploy). All endpoints require the api-key header and are free.

#Connect GitHub Repository

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.

syncDirection (controls behavior when the repo has existing content with no common git history):

• "totalum_to_github" (default) — pushes the Totalum project code to GitHub, replacing the repository content on both develop and main branches.
• "github_to_totalum" — pulls the GitHub repository code into Totalum, replacing the current project code. If the develop branch doesn't exist on GitHub, it is created from main.

Path parameters

Body parameters

Response fields

Example request

curl -X POST \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"token":"github_pat_xxx","repositoryFullName":"myuser/my-repo","syncDirection":"totalum_to_github"}' \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/github/connect

{
  "errors": null,
  "data": {
    "connected": true,
    "repositoryFullName": "myuser/my-repo",
    "syncAction": "push_new",
    "repoHasContent": false,
    "requiresRebuild": false
  }
}

{
  "errors": {
    "errorCode": "MISSING_GITHUB_FIELDS",
    "errorMessage": "token and repositoryFullName are required"
  },
  "data": null
}

Error codes

#Disconnect GitHub

Remove the GitHub integration from your project. Deletes the stored token and repository credentials. Code already in your project is not affected.

Path parameters

Response fields

Example request

curl -X DELETE -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/github/connect

{ "errors": null, "data": { "success": true, "message": "GitHub disconnected successfully" } }

{
  "errors": {
    "errorCode": "GITHUB_NOT_CONNECTED",
    "errorMessage": "GitHub is not connected to this project"
  },
  "data": null
}

Error codes

#Get GitHub Status

Check whether GitHub is connected and the token is still valid.

Path parameters

Response fields

Example request

curl -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/github/status

{
  "errors": null,
  "data": {
    "connected": true,
    "tokenValid": true,
    "tokenExpired": false,
    "repositoryFullName": "myuser/my-repo",
    "developBranch": "develop",
    "productionBranch": "main"
  }
}

#Pull from GitHub

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.

Path parameters

Response fields

Example request

curl -X POST -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/github/pull

{
  "errors": null,
  "data": {
    "status": "pulling",
    "message": "Pull started successfully",
    "filesUpdated": 5
  }
}

{
  "errors": {
    "errorCode": "GITHUB_NOT_CONNECTED",
    "errorMessage": "GitHub is not connected (connect first)"
  },
  "data": null
}

Error codes

#Get Pull Status

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.

Path parameters

Response fields

Example request

curl -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/github/pull-status

{ "errors": null, "data": { "status": "success", "createdAt": "2026-03-17T10:00:00.000Z" } }

#Download Environment Variables

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.

Path parameters

Response fields

Example request

curl -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/github/env

{
  "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..."
  }
}

{
  "errors": {
    "errorCode": "ENV_DOWNLOAD_ERROR",
    "errorMessage": "Failed to get environment variables"
  },
  "data": null
}

Error codes