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

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	5	List, read, update and delete projects; list their services
Deployments	10	Deploy status, logs, cancel, rollback
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. Errors and refusals carry a code and, when there is something to do, a fix that names what to run instead. Agents deploy with the Telbase skills (telbase skill install).

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