Deployments API

List deployments, read their status and logs, cancel them, and roll back. A deploy starts from the provider's CLI through Telbase (telbase vercel deploy, telbase gcloud run deploy); Telbase records each deployment of an app here.

Authentication required

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

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": "cli",
      "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",
    "projectName": "my-dashboard",
    "projectSlug": "my-dashboard",
    "status": "live",
    "trigger": "cli",
    "commitSha": null,
    "commitMessage": null,
    "url": "https://my-dashboard.telbase.ai",
    "startedAt": "2026-02-28T12:00:02.000Z",
    "finishedAt": "2026-02-28T12:01:30.000Z",
    "createdAt": "2026-02-28T12:00:00.000Z"
  }
}

A failed deploy also carries errorCode, errorMessage and a suggestion:

Response (200) — failed deploy

{
  "success": true,
  "data": {
    "id": "dep_xyz789",
    "status": "failed",
    "errorCode": "BUILD_FAILED",
    "errorMessage": "...",
    "suggestion": "..."
  }
}

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

Roll each service of an app with several services back to its own previous successful deploy, one after another, each once the one before it has finished.

Permission: deploys:create

Response (200)

{
  "success": true,
  "data": {
    "projectId": "proj_abc123",
    "services": [
      { "serviceName": "k7m2pq-shop", "serviceRole": "web", "status": "live", "deployId": "dep_rb1" },
      { "serviceName": "k7m2pq-shop-api", "serviceRole": "part", "status": "live", "deployId": "dep_rb2" }
    ],
    "message": "Rolled back 2 of 2 services"
  }
}

Redeploy All Services

POST /projects/:projectId/redeploy-all

Deploy again what each service of an app serves, one service after another, each once the one before it has finished.

Permission: deploys:create

Response (200)

{
  "success": true,
  "data": {
    "projectId": "proj_abc123",
    "deploys": [
      { "serviceName": "k7m2pq-shop", "serviceRole": "web", "deployId": "dep_new1", "status": "live" },
      { "serviceName": "k7m2pq-shop-api", "serviceRole": "part", "deployId": "dep_new2", "status": "live" }
    ],
    "message": "Redeployed 2 of 2 services"
  }
}