Deployments API

Deploy code, monitor build progress, stream logs, and manage rollbacks.

Authentication required

All endpoints require a Bearer token with the appropriate permission scope. See Authentication.

Start Deploy

POST /projects/:id/deploys

Start a new deployment. Telbase auto-detects the framework and provisions infrastructure. Returns immediately with a deploy ID — the build runs asynchronously.

Permission: deploy.create

Request Body

Parameter	Type	Required	Description
`source`	string	No	`github` or `local`
`repoUrl`	string	No	GitHub repository URL (required for first GitHub deploy)
`branch`	string	No	Git branch to deploy (max 100 chars)
`commitSha`	string	No	Specific commit SHA (max 40 chars)
`commitMessage`	string	No	Commit message for display (max 500 chars)
`clearCache`	boolean	No	Clear build cache before deploying
`provisionDatabase`	boolean	No	Explicitly request database provisioning
`databaseProvider`	string	No	`neon`, `turso`, or `cloud_sql`
`dbType`	string	No	ORM type: `prisma` or `drizzle`
`rootDir`	string	No	Subdirectory for monorepos (max 200 chars)
`forceEnvSync`	boolean	No	Force re-sync all env vars to the provider
`provisionStorage`	boolean	No	Request R2 storage bucket provisioning
`healthCheck`	object	No	Health check configuration (see below)
`serviceId`	string	No	Target service UUID for multi-service projects

Health Check Object

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable post-deploy health verification
`path`	string	`/`	Health check endpoint (max 200 chars)
`maxWaitMs`	number	30000	Timeout in ms (1,000–300,000)
`intervalMs`	number	2000	Poll interval in ms (500–30,000)
`expectedStatus`	number	200	Expected HTTP status code (100–599)

Request

{
  "source": "github",
  "repoUrl": "https://github.com/acme/dashboard",
  "branch": "main",
  "provisionDatabase": true,
  "databaseProvider": "neon"
}

Asynchronous

This endpoint returns 202 Accepted, not 200. The deploy runs asynchronously. Poll Get Deploy Status to track progress.

Response (202)

{
  "success": true,
  "data": {
    "id": "dep_abc123",
    "projectId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "building",
    "url": "https://my-dashboard.telbase.ai",
    "isFirstDeploy": false,
    "databaseProvisioned": true,
    "provider": "vercel",
    "framework": "nextjs",
    "decisions": [
      { "type": "compute", "choice": "vercel", "reason": "Next.js detected" },
      { "type": "database", "choice": "neon", "reason": "Explicit request" }
    ],
    "nextSteps": [
      "Monitor deploy: GET /deploys/dep_abc123",
      "View logs: GET /deploys/dep_abc123/stream"
    ],
    "detection": {
      "ormType": "prisma",
      "confidence": "high",
      "source": "github_api",
      "databaseProvider": "neon",
      "computeProvider": "vercel",
      "framework": "nextjs",
      "warnings": []
    },
    "message": "Deploy started"
  }
}

Upload & Deploy

POST /projects/:id/deploys/upload

Upload a tarball of your project source and deploy it. This is the endpoint used by the CLI for local deploys.

Permission: deploy.create

Content type: multipart/form-data. Maximum file size: 100 MB.

Form Fields

Field	Type	Required	Description
`tarball`	File	Yes	Gzipped tarball of project source
`hasDockerfile`	string	No	`true` if Dockerfile present
`needsDB`	string	No	`true` to request database
`dbType`	string	No	`prisma` or `drizzle`
`databaseProvider`	string	No	`neon`, `turso`, or `cloud_sql`
`framework`	string	No	Detected framework
`runtime`	string	No	Detected runtime
`serviceId`	string	No	Target service UUID

Note

Most AI agents should use the GitHub source endpoint (Start Deploy) instead. This upload endpoint is primarily used by the CLI for local file deploys.

List Deploys

GET /projects/:id/deploys

List deployments for a project, most recent first.

Permission: deploy.logs.read

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number (min 1)
`perPage`	number	10	Items per page (1–100)
`serviceId`	string	—	Filter by service UUID

Response (200)

{
  "success": true,
  "data": [
    {
      "id": "dep_abc123",
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "live",
      "trigger": "local",
      "commitSha": null,
      "commitMessage": null,
      "createdAt": "2026-02-28T12:00:00.000Z",
      "finishedAt": "2026-02-28T12:01:30.000Z"
    }
  ],
  "pagination": {
    "total": 12,
    "page": 1,
    "perPage": 10,
    "hasMore": true
  }
}

Get Deploy Status

GET /deploys/:id

Get the full status of a deployment. This is the primary polling endpoint for tracking deploy progress.

Permission: deploy.logs.read

Response (200)

{
  "success": true,
  "data": {
    "id": "dep_abc123",
    "projectId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "live",
    "url": "https://my-dashboard.telbase.ai",
    "trigger": "github",
    "commitSha": "a1b2c3d4",
    "commitMessage": "Add user dashboard",
    "provider": "vercel",
    "framework": "nextjs",
    "detection": {
      "ormType": "prisma",
      "confidence": "high",
      "source": "github_api",
      "databaseProvider": "neon",
      "framework": "nextjs"
    },
    "healthCheck": {
      "status": "healthy",
      "statusCode": 200,
      "durationMs": 450
    },
    "createdAt": "2026-02-28T12:00:00.000Z",
    "finishedAt": "2026-02-28T12:01:30.000Z"
  }
}

On failure, the response includes diagnostic fields:

Response (200) — failed deploy

{
  "success": true,
  "data": {
    "id": "dep_xyz789",
    "status": "failed",
    "errorCode": "BUILD_FAILED",
    "errorMessage": "Build command failed with exit code 1",
    "extractedErrors": ["Module not found: 'next/image'"],
    "detection": { ... },
    "suggestions": [
      { "type": "code_change", "file": "package.json", "description": "Add missing dependency: next" },
      { "type": "cli_retry", "command": "telbase deploy --local --clear-cache" }
    ],
    "aiDiagnosis": {
      "diagnosis": "next/image imported but 'next' not in package.json dependencies",
      "confidence": 0.95,
      "category": "missing_dependency",
      "fixes": [{ "type": "dependency", "description": "npm install next", "autoFixable": true }],
      "fixesAreAlternatives": false,
      "redeployCommand": "telbase deploy"
    }
  }
}

aiDiagnosis (optional) — AI-generated root cause analysis. Present on failed deploys when confidence ≥ 0.5. Each fix includes autoFixable (true if the agent can apply it without user input). Auto-apply fixes at confidence ≥ 0.7. Category is one of: missing_dependency, env_var, config, code_error, infrastructure, migration, port_binding, memory, misclassification, provider_degraded, unknown.

Get Deploy Logs

GET /deploys/:id/logs

Get build logs for a deployment as structured log entries.

Permission: deploy.logs.read

Response (200)

{
  "success": true,
  "data": {
    "logs": [
      { "timestamp": "2026-02-28T12:00:05.000Z", "message": "Installing dependencies..." },
      { "timestamp": "2026-02-28T12:00:15.000Z", "message": "Building application..." },
      { "timestamp": "2026-02-28T12:01:00.000Z", "message": "Deploy complete" }
    ]
  }
}

Stream Deploy Logs

GET /deploys/:id/stream

Stream build logs in real time via Server-Sent Events (SSE). The stream sends a heartbeat every 30 seconds and closes when the deploy reaches a terminal state.

Permission: deploy.logs.read

SSE authentication

Since EventSource does not support custom headers, you can pass the token as a query parameter: /deploys/:id/stream?token=sk_live_...

SSE client example

// JavaScript example
const es = new EventSource(
  'https://api.telbase.ai/deploys/dep_abc123/stream?token=sk_live_...'
);

es.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.message);
};

es.onerror = () => es.close();

Cancel Deploy

POST /deploys/:id/cancel

Cancel a deploy that is currently building.

Permission: deploy.cancel

Response (200)

{
  "success": true,
  "data": {
    "id": "dep_abc123",
    "status": "cancelled",
    "message": "Deploy cancelled"
  }
}

List Rollback Targets

GET /projects/:id/rollback-targets

List previous successful deployments that can be used as rollback targets.

Permission: deploy.logs.read

Query Parameters

Parameter	Type	Default	Description
`serviceId`	string	—	Filter by service UUID

Response (200)

{
  "success": true,
  "data": [
    {
      "id": "dep_prev1",
      "status": "live",
      "commitSha": "a1b2c3d4",
      "commitMessage": "Previous stable version",
      "createdAt": "2026-02-27T10:00:00.000Z",
      "finishedAt": "2026-02-27T10:01:30.000Z"
    }
  ]
}

Rollback to Previous

POST /projects/:id/rollback

Rollback to the most recent successful deployment.

Permission: deploy.rollback

Response (202)

{
  "success": true,
  "data": {
    "id": "dep_rollback1",
    "status": "building",
    "rollbackFrom": "dep_abc123",
    "rollbackTo": "dep_prev1",
    "message": "Rollback initiated"
  }
}

Rollback to Specific Deploy

POST /projects/:id/rollback/:deployId

Rollback to a specific previous deployment by ID.

Permission: deploy.rollback

Response (202)

{
  "success": true,
  "data": {
    "id": "dep_rollback2",
    "status": "building",
    "rollbackTo": "dep_prev1",
    "message": "Rollback initiated"
  }
}

Rollback All Services

POST /projects/:projectId/rollback-all

Rollback all services in a multi-service project to their most recent successful deployments.

Permission: deploy.rollback

Response (202)

{
  "success": true,
  "data": {
    "rollbacks": [
      { "serviceId": "svc_frontend", "deployId": "dep_rb1", "status": "building" },
      { "serviceId": "svc_backend", "deployId": "dep_rb2", "status": "building" }
    ],
    "message": "Rollback initiated for all services"
  }
}

Redeploy All Services

POST /projects/:projectId/redeploy-all

Trigger a fresh deployment of all services in a multi-service project.

Permission: deploy.create

Response (202)

{
  "success": true,
  "data": {
    "deploys": [
      { "serviceId": "svc_frontend", "deployId": "dep_new1", "status": "building" },
      { "serviceId": "svc_backend", "deployId": "dep_new2", "status": "building" }
    ],
    "message": "Redeploy initiated for all services"
  }
}