Projects API

Create, list, update, and manage Telbase projects and services.

Authentication required

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

Create Project

POST /projects

Create a new project. The project name becomes its subdomain (name.telbase.ai).

Permission: project.create

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Project name (1–100 chars)
`slug`	string	No	URL slug (max 50 chars, auto-generated from name)
`tier`	string	No	`production` or `sandbox` (default)
`provider`	string	No	`vercel` (default), `gcp`, or `aws`
`databaseProvider`	string	No	`neon`, `turso`, or `cloud_sql`
`framework`	string	No	Framework hint (e.g. `nextjs`, `vite`, `fastapi`)
`region`	string	No	Deployment region (max 50 chars)
`projectType`	string	No	`static` or `fullstack`

Request

{
  "name": "my-dashboard",
  "framework": "nextjs",
  "provider": "vercel"
}

Response (201)

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

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",
    "preDeployCommand": null,
    "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": "local",
      "commitSha": null,
      "createdAt": "2026-02-28T12:00:00.000Z",
      "finishedAt": "2026-02-28T12:01:30.000Z"
    },
    "services": [],
    "stats": {
      "envVarCount": 5,
      "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
`preDeployCommand`	string \| null	No	Pre-deploy command (max 500 chars, `null` to remove)
`provider`	string	No	Compute provider
`force`	boolean	No	Required when changing provider on a deployed project

Provider changes

Changing the compute provider on a project that has already been deployed requires "force": true. This re-provisions infrastructure on the new provider.

Request

{
  "name": "my-dashboard-v2",
  "preDeployCommand": "npx prisma migrate deploy"
}

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,
    "preDeployCommand": "npx prisma migrate deploy",
    "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"
  }
}

Create Service

POST /projects/:id/services

Add a service to a multi-service project.

Permission: project.create

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Service name (1–100 chars)
`slug`	string	Yes	URL-safe slug (1–63 chars)
`serviceRole`	string	Yes	`frontend`, `backend`, `worker`, or `api`
`provider`	string	Yes	`vercel`, `gcp`, or `aws`
`framework`	string	No	Framework for the service
`region`	string	No	Deployment region
`path`	string	No	Source path relative to project root (max 500 chars)
`pathPrefix`	string	No	URL path prefix (deprecated — routing now uses per-service subdomains)

Request

{
  "name": "API Server",
  "slug": "api",
  "serviceRole": "backend",
  "provider": "gcp",
  "framework": "express",
  "path": "packages/api"
}

Response (201)

{
  "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",
    "pathPrefix": null,
    "status": "creating",
    "createdAt": "2026-02-28T12:00:00.000Z"
  }
}

List Services

GET /projects/:id/services

List all services within a project.

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",
      "pathPrefix": null,
      "status": "running",
      "providerServiceId": "srv-abc123",
      "createdAt": "2026-02-28T12:00:00.000Z",
      "updatedAt": "2026-02-28T12:00:00.000Z"
    }
  ]
}