API Reference CLI Reference Connections
https://api.tenantsdb.com
🔐 Authentication
All endpoints except /signup and /login require an API key.
🔑
Include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY
POST /signup
Create a new account. Returns an API key for your first project.
Request Body
FieldTypeDescription
email string required Email address
password string required Password (min 8 characters)
project_name string optional Project name (default: "My Project")
Response
JSON 
{
  "success": true,
  "api_key": "tenantsdb_sk_a91de156...",
  "project_id": "tdb_2abf90d3"
}
POST /login
Login to existing account. Returns all projects with API keys.
Request Body
FieldTypeDescription
email string required Email address
password string required Password
Response
JSON
{
  "success": true,
  "projects": [
    {
      "project_id": "tdb_2abf90d3",
      "name": "Healthcare SaaS",
      "api_key": "tenantsdb_sk_a91de156..."
    }
  ]
}
📁 Projects
Projects are the top-level organizational boundary. Each project has its own workspaces, blueprints, tenants, and API keys.
GET /projects
List all projects for the authenticated customer.
JSON
{
  "success": true,
  "count": 2,
  "projects": [
    {
      "project_id": "tdb_2abf90d3",
      "name": "Healthcare SaaS",
      "api_key_count": 2,
      "created_at": "2026-01-17T20:12:06Z"
    },
    {
      "project_id": "tdb_43cd4942",
      "name": "E-commerce Platform",
      "api_key_count": 1,
      "created_at": "2026-01-17T20:12:24Z"
    }
  ]
}
POST /projects
Create a new project. Returns a new API key.
Request Body
FieldTypeDescription
name string required Project name
POST /projects/{id}/switch
Switch to a different project. Returns the API key for the target project. Accepts project ID or project name.
Response
JSON
{
  "success": true,
  "project_id": "tdb_43cd4942",
  "name": "E-commerce Platform",
  "api_key": "tenantsdb_sk_42d5be1a...",
  "proxy_password": "tdb_a9b55759ef905535"
}
DELETE /projects/{id}
Delete a project and all its resources (workspaces, blueprints, tenants, API keys).
🔑 API Keys
Manage API keys for the current project.
GET /apikeys
List all API keys for the current project.
POST /apikeys
Generate a new API key.
DELETE /apikeys/{id}
Delete an API key.
🏗️ Workspaces
Workspaces are development environments where you design your database schema. Changes in workspaces are captured as blueprints for deployment.
GET /workspaces
List all workspaces.
POST /workspaces
Create a workspace. Automatically creates a linked blueprint.
Request Body
FieldTypeDescription
name string required Workspace name
database string required PostgreSQL, MySQL, MongoDB, or Redis
Response
JSON
{
  "success": true,
  "id": "myapp",
  "blueprint": "myapp",
  "database": "PostgreSQL",
  "connection": {
    "host": "pg.tenantsdb.com",
    "port": 5432,
    "database": "myapp_dev",
    "user": "tdb_2abf90d3",
    "password": "tdb_d2bf66ed7898c448"
  },
  "connection_string": "postgresql://tdb_2abf90d3:tdb_d2bf66ed@pg.tenantsdb.com:5432/myapp_dev"
}
GET /workspaces/{id}
Get workspace details including schema and connection info.
DELETE /workspaces/{id}
Delete a workspace. Fails if tenants are deployed to its blueprint.
POST /workspaces/{id}/queries
Run a query in the workspace dev database.
POST /workspaces/{id}/schema
Import schema from template, JSON, or external database.
From Template
JSON
{
  "source": "template",
  "template": "fintech"
}
From Database
JSON
{
  "source": "database",
  "connection": {
    "type": "postgresql",
    "host": "db.example.com",
    "port": 5432,
    "database": "mydb",
    "user": "admin",
    "password": "secret"
  }
}
GET /workspaces/{id}/diff
Get pending DDL changes ready for deployment.
POST /workspaces/{id}/import-data
Import data from an external database. Tenants are auto-created based on the routing field.
Request Body
JSON
{
  "connection": {
    "type": "postgresql",
    "host": "db.example.com",
    "port": 5432,
    "database": "mydb",
    "user": "admin",
    "password": "secret"
  },
  "routing_field": "tenant_id",
  "options": {
    "drop_routing_column": true,
    "create_tenants": true
  }
}
📐 Blueprints
Blueprints are versioned schema snapshots created from workspaces. They define what gets deployed to tenant databases.
GET /blueprints
List all blueprints.
GET /blueprints/{name}
Get blueprint schema and deployment status.
GET /blueprints/{name}/versions
List all versions of a blueprint.
👥 Tenants
Tenants are your customers' isolated database instances. Each tenant gets its own physical database, created from a blueprint.
L1
Shared
Multi-tenant pool. Cost-effective, instant provisioning. Each tenant gets a separate database on a shared server.
L2
Dedicated
Own VM. Full physical isolation, dedicated resources. Provisioned on Hetzner Cloud (~2 min).
GET /tenants
List all tenants for the current project.
POST /tenants
Create a new tenant with database(s) from blueprint(s).
Request Body
FieldTypeDescription
tenant_id string required Tenant name
databases array required Array of {blueprint, isolation_level}
Response
JSON
{
  "success": true,
  "tenant_id": "acme",
  "status": "ready",
  "databases": [
    {
      "blueprint": "fintech",
      "database_type": "PostgreSQL",
      "isolation_level": 1,
      "connection": {
        "database": "fintech__acme",
        "connection_string": "postgresql://tdb_2abf90d3:tdb_d2bf66ed@pg.tenantsdb.com:5432/fintech__acme"
      }
    }
  ]
}
GET /tenants/{id}
Get tenant details with all database connections.
DELETE /tenants/{id}
Soft-delete a tenant. Add ?hard=true for permanent deletion.
POST /tenants/{id}/suspend
Suspend a tenant (block all queries).
POST /tenants/{id}/resume
Resume a suspended tenant.
PATCH /tenants/{id}/isolation
Migrate tenant between isolation levels (L1 ↔ L2). Zero-downtime migration with automatic data transfer.
Request Body
JSON
{
  "isolation_level": 2
}
POST /tenants/{id}/backup
Trigger an on-demand backup to S3.
GET /tenants/{id}/backups
List all backups for a tenant.
GET /tenants/{id}/logs
Get query execution logs.
Query Parameters
ParamTypeDescription
type string optional Filter: error, slow
since string optional Time filter: 1h, 24h, 7d
GET /tenants/{id}/metrics
Get performance metrics (query count, latency, success rate).
🚀 Deployments
Deploy blueprint schema changes to tenant databases. Runs DDL migrations across all or selected tenants.
GET /deployments
List all deployment jobs.
POST /deployments
Create a new deployment.
Request Body
FieldTypeDescription
blueprint_name string required Blueprint to deploy
version string optional Version to deploy
deploy_all boolean optional Deploy to all tenants
GET /deployments/{id}
Get deployment status and progress.
⚡ Admin
Direct query execution on tenant databases.
POST /admin/query
Run a query directly on one or all tenant databases.
Request Body
FieldTypeDescription
tenant_id string optional* Target tenant
query string required OQL or native query
database_type string optional PostgreSQL, MySQL, MongoDB, Redis
blueprint string required Blueprint name
all_tenants boolean optional* Query all tenants
* Either tenant_id or all_tenants: true is required.