API Reference

Programmatic access to the Telbase platform. Manage projects, deployments, environment variables, and more.

Base URL

All API requests are made to:

https://api.telbase.ai

Authentication

Authenticate requests using a Bearer token in the Authorization header. API keys start with sk_live_.

Example request

curl https://api.telbase.ai/projects \
  -H "Authorization: Bearer sk_live_your_api_key"

Creating API keys

Generate API keys in the Dashboard under Settings → API Keys, or programmatically via POST /orgs/:orgId/api-keys.

Scoped permissions

API keys can be scoped to specific permissions. Common scopes:

project.create, project.list, project.delete, project.settings
deploy.create, deploy.cancel, deploy.rollback, deploy.logs.read
env.list, env.values.read, env.write
db.status, db.create, db.connection, db.query
domain.list, domain.create, domain.delete

Wildcard scopes are supported: deploy.* matches all deploy permissions. Keys with no explicit scopes inherit permissions from the user's role (owner, admin, developer, or viewer).

Response Format

All responses use a consistent JSON envelope.

Success

Success response

{
  "success": true,
  "data": {
    "id": "proj_abc123",
    "name": "my-app",
    "url": "https://my-app.telbase.ai"
  }
}

Paginated list

Paginated response

{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 42,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Error

Error response

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Project not found",
    "suggestion": "Run 'telbase projects' to list available projects"
  }
}

Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request body or query parameters
`AUTH_REQUIRED`	401	Missing or invalid authentication token
`PERMISSION_DENIED`	403	API key lacks required permission scope
`NOT_FOUND`	404	Resource does not exist or is not accessible
`CONFLICT`	409	Resource already exists (e.g. duplicate slug)
`LIMIT_EXCEEDED`	402	Plan quota exceeded — upgrade required
`PROVIDER_CHANGE_REQUIRES_FORCE`	400	Changing provider on a deployed project requires `force: true`
`DEPLOY_FAILED`	500	Deploy encountered a provider-level failure

Pagination

List endpoints accept limit and offset query parameters:

limit — Number of items to return (default 50, max 100)
offset — Number of items to skip (default 0)

The response includes a pagination object with total, limit, offset, and hasMore. Continue fetching while hasMore is true.

Rate Limiting

Rate limiting is currently applied to authentication endpoints only. General rate limiting with standard headers is coming soon:

X-RateLimit-Limit — Requests allowed per window
X-RateLimit-Remaining — Requests remaining
X-RateLimit-Reset — Unix timestamp when the window resets

Available APIs

API	Endpoints	Description
Projects	8	Create, list, update, delete projects and services
Deployments	12	Deploy code, stream logs, rollback, cancel
Environment Variables	6	Set, list, compare, and generate secrets

More APIs coming soon

Additional API sections for databases, domains, storage, and teams are in development.

AI Integration

Telbase is built for AI agents. Deploy responses include structured feedback that enables self-healing deploys:

decisions[] — Every infrastructure decision with reasoning
nextSteps[] — Suggested follow-up actions after a deploy
detection{} — Framework, ORM, and database detection context
suggestions[] — On failure: typed recovery actions (cli_retry, code_change, user_action)

For native AI tooling, see the MCP server documentation. For context injection, use llms-full.txt.