Projects API

List, read, update and delete Telbase projects and their services.

Apps are registered with telbase apps create before their first deploy (see the CLI reference); each app is a project here.

Authentication required

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

List Projects

GET /projects

List all projects in the current organization.

Permission: project.list

Query Parameters

Parameter	Type	Default	Description
`includeDeleted`	boolean	`false`	Include recently deleted projects (purged after 7 days)
`status`	string	—	Filter by status: `creating`, `running`, `suspended`, `failed`, `deleting`
`limit`	number	50	Items per page (1–100)
`offset`	number	0	Number of items to skip

Response (200)

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "my-dashboard",
      "slug": "my-dashboard",
      "tier": "production",
      "provider": "vercel",
      "status": "running",
      "framework": "nextjs",
      "url": "https://my-dashboard.telbase.ai",
      "services": [],
      "createdAt": "2026-02-28T12:00:00.000Z",
      "updatedAt": "2026-02-28T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Get Project

GET /projects/:id

Get detailed information about a project, including database, domains, latest deploy, services, and usage stats. Accepts a UUID or project slug.

Permission: project.list

Response (200)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-dashboard",
    "slug": "my-dashboard",
    "tier": "production",
    "status": "running",
    "framework": "nextjs",
    "region": null,
    "url": "https://my-dashboard.telbase.ai",
    "provider": "vercel",
    "database": {
      "id": "db_abc123",
      "status": "active",
      "plan": "starter",
      "createdAt": "2026-02-28T12:00:00.000Z"
    },
    "domains": [
      {
        "id": "dom_abc123",
        "domain": "dashboard.acme.com",
        "verified": true,
        "sslStatus": "active",
        "isPrimary": true
      }
    ],
    "latestDeploy": {
      "id": "dep_abc123",
      "status": "live",
      "trigger": "cli",
      "commitSha": null,
      "createdAt": "2026-02-28T12:00:00.000Z",
      "finishedAt": "2026-02-28T12:01:30.000Z"
    },
    "services": [],
    "stats": {
      "deployCount": 12,
      "domainCount": 1,
      "serviceCount": 0
    },
    "createdAt": "2026-02-28T12:00:00.000Z",
    "updatedAt": "2026-02-28T12:00:00.000Z"
  }
}

Update Project

PATCH /projects/:id

Update project settings.

Permission: project.settings

Request Body

Parameter	Type	Required	Description
`name`	string	No	New project name (1–100 chars)
`framework`	string	No	Framework override
`region`	string	No	Deployment region

Request

{
  "name": "my-dashboard-v2"
}

Response (200)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-dashboard-v2",
    "slug": "my-dashboard",
    "provider": "vercel",
    "status": "running",
    "framework": "nextjs",
    "region": null,
    "url": "https://my-dashboard.telbase.ai",
    "createdAt": "2026-02-28T12:00:00.000Z",
    "updatedAt": "2026-02-28T12:05:00.000Z"
  }
}

Delete Project

DELETE /projects/:id

Delete a project and all associated resources. This action is permanent.

Permission: project.delete

Response (200)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-dashboard",
    "slug": "my-dashboard",
    "status": "deleting",
    "deletedAt": "2026-02-28T12:10:00.000Z",
    "cleanup": {
      "steps": ["vercel_project_deleted", "kv_entries_removed"],
      "durationMs": 1200
    },
    "message": "Project deleted successfully"
  }
}

List Services

GET /projects/:id/services

List the services within a project. An app has one.

Permission: project.list

Response (200)

{
  "success": true,
  "data": [
    {
      "id": "svc_abc123",
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "API Server",
      "slug": "api",
      "serviceRole": "backend",
      "provider": "gcp",
      "framework": "express",
      "region": null,
      "path": "packages/api",
      "status": "running",
      "providerServiceId": "srv-abc123",
      "createdAt": "2026-02-28T12:00:00.000Z",
      "updatedAt": "2026-02-28T12:00:00.000Z"
    }
  ]
}