curl -s https://api.tenantsdb.com/regions

{
  "regions": [
    {
      "zone": "eu-central",
      "label": "Europe",
      "is_default": true
    },
    {
      "zone": "ap-southeast",
      "label": "Asia Pacific"
    },
    {
      "zone": "us-east",
      "label": "US East"
    },
    {
      "zone": "us-west",
      "label": "US West"
    }
  ]
}

curl -s https://api.tenantsdb.com/errors

{
  "codes": {
    "ok":                { "status": 200, "description": "Request succeeded" },
    "created":           { "status": 201, "description": "Resource was created" },
    "bad_request":       { "status": 400, "description": "Invalid input or missing fields" },
    "auth_required":     { "status": 401, "description": "Authorization header missing" },
    "unauthorized":      { "status": 401, "description": "Invalid API key" },
    "forbidden":         { "status": 403, "description": "Tier limit reached or wrong project" },
    "role_required":     { "status": 403, "description": "API key role insufficient for endpoint" },
    "scope_denied":      { "status": 403, "description": "API key scope excludes this tenant or workspace" },
    "permission_denied": { "status": 403, "description": "Database role denied the operation" },
    "not_found":         { "status": 404, "description": "Resource does not exist" },
    "conflict":          { "status": 409, "description": "Already exists or operation in progress" },
    "rate_limited":      { "status": 429, "description": "Too many requests" },
    "internal_error":    { "status": 500, "description": "Server error" }
  }
}

{
  "success": true,
  "http_status": 201,
  "code": "created",
  "api_key": "tdb_sk_a91de156...",
  "project_id": "tdb_2abf90d3"
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "session_token": "tdb_sess_a91de156...",
  "projects": [
    {
      "project_id": "tdb_2abf90d3",
      "name": "Healthcare SaaS",
      "api_key": "tdb_sk_a91de156..."
    }
  ]
}

{
  "success": true,
  "message": "Logged out"
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "count": 2,
  "projects": [
    {
      "project_id": "tdb_2abf90d3",
      "name": "Healthcare SaaS",
      "api_key": "tdb_sk_a91de156...",
      "api_key_count": 2,
      "workspaces": 3,
      "tenants": 45,
      "database_types": ["PostgreSQL", "MongoDB"],
      "created_at": "2026-01-17T20:12:06Z"
    },
    {
      "project_id": "tdb_43cd4942",
      "name": "E-commerce Platform",
      "api_key": "tdb_sk_42d5be1a...",
      "api_key_count": 1,
      "workspaces": 1,
      "tenants": 0,
      "database_types": ["PostgreSQL"],
      "created_at": "2026-01-17T20:12:24Z"
    }
  ]
}

{
  "success": true,
  "http_status": 201,
  "code": "created",
  "project_id": "tdb_43cd4942",
  "name": "E-commerce Platform",
  "api_key": "tdb_sk_42d5be1a...",
  "proxy_password": "tdb_a9b55759ef905535",
  "message": "Project created. Save your API key - it won't be shown again!"
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "project_id": "tdb_43cd4942",
  "name": "E-commerce Platform",
  "api_key": "tdb_sk_42d5be1a...",
  "proxy_password": "tdb_a9b55759ef905535"
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "message": "Project 'tdb_43cd4942' deleted successfully"
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "count": 3,
  "api_keys": [
    {
      "id": 118,
      "key": "tdb_sk_1a28fba2...",
      "project_id": "tdb_701dc142",
      "project_name": "My Saas",
      "key_name": "Production",
      "tier": "scale",
      "is_active": true,
      "scope_type": "project",
      "scope_values": [],
      "role": "admin",
      "created_at": "2026-04-27T21:20:55Z",
      "last_used_at": "2026-04-28T09:14:02Z",
      "oauth_managed": false
    },
    {
      "id": 122,
      "key_name": "Reporting",
      "scope_type": "workspace",
      "scope_values": ["orders"],
      "role": "read",
      "oauth_managed": false
    },
    {
      "id": 125,
      "key_name": "OAuth: Claude",
      "scope_type": "project",
      "scope_values": [],
      "role": "mcp",
      "oauth_managed": true
    }
  ]
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "email": "[email protected]",
  "project_id": "tdb_701dc142",
  "project_name": "My Saas"
}

{
  "name": "Production",
  "role": "admin",
  "scope_type": "project",
  "scope_values": []
}

{
  "name": "Reporting",
  "role": "read",
  "scope_type": "workspace",
  "scope_values": ["orders"]
}

{
  "name": "Acme + Globex Sync",
  "role": "write",
  "scope_type": "tenant",
  "scope_values": ["acme", "globex"]
}

{
  "success": true,
  "http_status": 201,
  "code": "created",
  "api_key": "tdb_sk_1a28fba2a972b58c0d9051c658d18d5505b8f04cd8b8526ca61fa643f34e183b",
  "proxy_password": "tdb_646145765b597e4f",
  "project_id": "tdb_701dc142",
  "name": "Production",
  "scope_type": "project",
  "scope_values": [],
  "role": "admin",
  "note": "Use api_key for HTTP API, proxy_password for database connections"
}

{
  "success": false,
  "code": "bad_request",
  "error": "Failed to generate API key: invalid scope: scope_values must be empty for scope_type=project"
}

{
  "success": false,
  "code": "bad_request",
  "error": "role \"mcp\" is reserved for OAuth integrations and cannot be created manually"
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "message": "API key successfully revoked"
}

{
  "success": false,
  "code": "oauth_managed",
  "error": "This key is managed by an OAuth connection. Revoke the connection in Connected Apps to delete it."
}

{
  "workspaces": [
    {
      "id": "ws_abc123",
      "name": "main",
      "mode": "tenant",
      "database": "postgresql",
      "created_at": "2025-01-15T10:30:00Z",
      "version": 3
    },
    {
      "id": "ws_def456",
      "name": "control-plane",
      "mode": "control",
      "database": "postgresql",
      "created_at": "2025-01-15T11:00:00Z"
    }
  ],
  "count": 2
}

{
  "success": true,
  "http_status": 201,
  "code": "created",
  "id": "myapp",
  "mode": "tenant",
  "blueprint": "myapp",
  "database": "PostgreSQL",
  "connection": {
    "host": "pg.tenantsdb.com",
    "port": 5432,
    "database": "myapp_workspace",
    "user": "tdb_2abf90d3",
    "password": "tdb_d2bf66ed7898c448"
  },
  "connection_string": "postgresql://tdb_2abf90d3:[email protected]:5432/myapp_workspace?sslmode=require"
}

{
  "success": true,
  "http_status": 201,
  "code": "created",
  "id": "controlplane",
  "mode": "control",
  "database": "PostgreSQL",
  "connection": {
    "host": "pg.tenantsdb.com",
    "port": 5432,
    "database": "controlplane_workspace",
    "user": "tdb_2abf90d3",
    "password": "tdb_d2bf66ed7898c448"
  },
  "connection_string": "postgresql://tdb_2abf90d3:[email protected]:5432/controlplane_workspace?sslmode=require"
}

{
  "id": "ws_abc123",
  "name": "main",
  "mode": "tenant",
  "database": "postgresql",
  "schema": ["CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT NOT NULL)"],
  "schema_error": null,
  "undeployed_changes": 2,
  "connection": {
    "host": "proxy.tenantsdb.com",
    "port": 5432,
    "database": "ws_abc123",
    "username": "ws_abc123",
    "password": "••••••••"
  },
  "connection_string": "postgresql://ws_abc123:••••••••@proxy.tenantsdb.com:5432/ws_abc123?sslmode=require",
  "settings": {
    "query_timeout_ms": 30000,
    "max_rows_per_query": 1000,
    "max_connections": 10
  },
  "version": 3
}

{
  "message": "workspace deleted",
  "details": {
    "workspace": "main",
    "mode": "tenant",
    "versions_deleted": 3,
    "deletion_type": "full",
    "physical_db": true
  }
}

{
  "message": "cannot delete workspace with deployed tenants",
  "reason": "tenants_deployed",
  "deployed_to": ["acme", "globex"],
  "action_required": "Delete all tenants first or use a different workspace"
}

{
  "columns": ["id", "name", "email"],
  "rows": [
    [1, "Alice", "[email protected]"]
  ],
  "row_count": 1,
  "execution_time": "8ms"
}

{
  "source": "template",
  "template": "fintech"
}

{
  "source": "database",
  "connection": {
    "type": "postgresql",
    "host": "db.example.com",
    "port": 5432,
    "database": "mydb",
    "user": "admin",
    "password": "secret"
  }
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "message": "Schema imported to workspace 'myapp'",
  "source": "template",
  "created": ["users", "accounts", "transactions"],
  "skipped": [],
  "errors": [],
  "details": {
    "workspace": "myapp",
    "database_type": "PostgreSQL",
    "statements_executed": 3,
    "statements_skipped": 0,
    "statements_failed": 0,
    "statements_total": 3
  }
}

{
  "tables": [
    {
      "name": "users",
      "columns": [
        { "name": "id", "type": "SERIAL", "nullable": false },
        { "name": "name", "type": "TEXT", "nullable": false }
      ],
      "indexes": ["users_pkey"]
    }
  ]
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "message": "DDL 42 removed from deploy queue"
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "message": "Reverted: DROP TABLE IF EXISTS users;"
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "database_type": "PostgreSQL",
  "settings": {
    "query_timeout_ms": 30000,
    "max_rows_per_query": 10000,
    "max_connections": 100
  },
  "available_fields": ["query_timeout_ms", "max_rows_per_query", "max_connections"]
}

{
  "query_timeout_ms": 30000,
  "max_rows_per_query": 10000,
  "max_connections": 100
}

{
  "default_ttl": 3600,
  "max_keys": 50000,
  "patterns": {
    "cache:*": { "ttl": 300 },
    "session:*": { "ttl": 86400 }
  }
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "settings": { ... },
  "message": "Settings saved. Deploy to apply to tenants.",
  "pending_deploy": true,
  "database_type": "PostgreSQL"
}

{
  "blueprints": [
    {
      "name": "main",
      "database": "postgresql",
      "workspace_id": "ws_abc123",
      "current_version": 3,
      "tenant_count": 12
    }
  ],
  "count": 1
}

{
  "name": "main",
  "database": "postgresql",
  "workspace_id": "ws_abc123",
  "current_version": 3,
  "schema": [
    "CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT NOT NULL)"
  ],
  "tenant_count": 12
}

{
  "versions": [
    {
      "version": 3,
      "ddl_count": 2,
      "deployed_at": "2025-02-01T10:00:00Z"
    },
    {
      "version": 2,
      "ddl_count": 1,
      "deployed_at": "2025-01-20T14:30:00Z"
    }
  ],
  "count": 2
}

{
  "tenants": [
    {
      "tenant_id": "acme",
      "status": "active",
      "databases": [
        {
          "blueprint": "main",
          "database_type": "postgresql",
          "isolation_level": "L1"
        }
      ],
      "created_at": "2025-01-20T14:00:00Z"
    }
  ],
  "count": 1
}

{
  "success": true,
  "http_status": 201,
  "code": "created",
  "tenant_id": "acme",
  "status": "ready",
  "databases": [
    {
      "blueprint": "fintech",
      "database_type": "PostgreSQL",
      "isolation_level": 1,
      "connection": {
        "database": "fintech__acme",
        "connection_string": "postgresql://tdb_2abf90d3:[email protected]:5432/fintech__acme?sslmode=require"
      }
    }
  ]
}

"postgresql://tdb_2abf90d3:[email protected]:5432/fintech__acme?sslmode=require"

"mysql://tdb_2abf90d3:[email protected]:3306/fintech__acme"

"mongodb://tdb_2abf90d3:[email protected]:27017/fintech__acme?authMechanism=PLAIN&directConnection=true&tls=true"

"rediss://acme:[email protected]:6379/0"

{
  "success": true,
  "http_status": 201,
  "code": "created",
  "tenant_id": "acme",
  "status": "provisioning",
  "databases": [
    {
      "blueprint": "fintech",
      "database_type": "PostgreSQL",
      "isolation_level": 2,
      "region": "eu-central"
    }
  ]
}

{
  "tenant_id": "acme",
  "status": "active",
  "databases": [
    {
      "blueprint": "main",
      "database_type": "postgresql",
      "isolation_level": "L1",
      "connection": {
        "host": "proxy.tenantsdb.com",
        "port": 5432,
        "database": "acme",
        "username": "acme",
        "password": "••••••••"
      },
      "connection_string": "postgresql://acme:••••••••@proxy.tenantsdb.com:5432/acme?sslmode=require",
      "version": 3
    }
  ],
  "recovery_undo": {
    "available": true,
    "original_host": "vm-pg-01",
    "expires_at": "2025-02-01T14:00:00Z",
    "expires_in": "23h 45m",
    "command": "tdb tenants recover-undo acme"
  },
  "created_at": "2025-01-20T14:00:00Z"
}

curl -X POST https://api.tenantsdb.com/tenants/acme/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blueprint": "fintech",
    "query": "SELECT id, name, balance FROM accounts WHERE balance > 1000"
  }'

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "tenant": "acme",
  "result": {
    "count": 2,
    "rows": [
      { "id": 1, "name": "Alice", "balance": 5000 },
      { "id": 2, "name": "Bob", "balance": 2500 }
    ]
  }
}

{
  "success": false,
  "http_status": 403,
  "code": "permission_denied",
  "error": "query failed: pq: permission denied for table users"
}

{
  "success": false,
  "code": "scope_denied",
  "error": "credential scoped to tenants [planbtest1], attempted \"acme\""
}

{
  "success": false,
  "http_status": 400,
  "code": "bad_request",
  "error": "DDL not allowed on tenant databases. Deploy schema through blueprints."
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "message": "Tenant 'acme' restored successfully",
  "tenant": {
    "tenant_id": "acme",
    "status": "ready"
  }
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "tenant_id": "acme",
  "blueprint": "fintech",
  "status": "migrating",
  "from": 1,
  "to": 2,
  "message": "Migration in progress for 'fintech'. Check tenant status for completion."
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "tenant_id": "acme",
  "blueprint": "fintech",
  "status": "migrating",
  "from": 2,
  "to": 2,
  "change": "region",
  "from_region": "eu-central",
  "to_region": "us-east",
  "message": "Migration in progress for 'fintech'. Check tenant status for completion."
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "message": "Backup scheduled for tenant: acme",
  "tenant_id": "acme",
  "type": "manual",
  "timestamp": "2026-02-15T14-30-00",
  "paths": ["postgresql/manual/2026-02-15T14-30-00/tdb_2abf90d3_tenant_acme.sql.gz"]
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "tenant_id": "acme",
  "count": 3,
  "backups": [
    {
      "type": "manual",
      "date": "2026-02-15T14-30-00",
      "database_type": "postgresql",
      "storage_path": "postgresql/manual/2026-02-15T14-30-00/tdb_2abf90d3_tenant_acme.sql.gz",
      "size_bytes": 524288,
      "created_at": "2026-02-14T03:00:00Z"
    }
  ]
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "message": "Rollback scheduled for tenant: acme",
  "tenant_id": "acme",
  "status": "restoring",
  "paths": ["postgresql/manual/2026-02-15T14-30-00/tdb_2abf90d3_tenant_acme.sql.gz"]
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "message": "Recovery initiated for tenant 'acme' to 2026-02-03T17:10:59Z. Original VM preserved for 24h.",
  "tenant": {
    "tenant_id": "acme",
    "status": "recovering",
    "target_timestamp": "2026-02-03T17:10:59Z"
  }
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "message": "Recovery undone for tenant 'acme'. Original VM restored.",
  "tenant": {
    "tenant_id": "acme",
    "status": "ready"
  }
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "tenant_id": "acme",
  "count": 3,
  "deployments": [ ... ]
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "tenant_id": "acme",
  "logs": [
    {
      "query": "SELECT * FROM users WHERE active = true",
      "source": "proxy",
      "success": true,
      "duration_ms": 4.2,
      "created_at": "2026-02-15T14:30:00Z"
    }
  ],
  "count": 50,
  "has_more": true
}

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "tenant_id": "acme",
  "total_queries": 48230,
  "successful": 47891,
  "failed": 339,
  "by_source": {
    "proxy": 45000,
    "api": 3230
  },
  "avg_duration_ms": 12.4,
  "slow_queries": 18
}

{
  "deployments": [
    {
      "id": "dep_abc123",
      "blueprint_name": "main",
      "version": 3,
      "status": "completed",
      "tenants_total": 12,
      "tenants_completed": 12,
      "created_at": "2025-02-01T10:00:00Z"
    }
  ],
  "count": 1
}

{
  "id": "dep_abc123",
  "blueprint_name": "main",
  "version": 3,
  "status": "in_progress",
  "tenants_total": 12,
  "tenants_completed": 8,
  "tenants_failed": 0,
  "results": [
    { "tenant_id": "acme", "status": "completed", "duration": "120ms" },
    { "tenant_id": "globex", "status": "pending" }
  ],
  "created_at": "2025-02-01T10:00:00Z"
}

{
  "tenant_id": "acme",
  "columns": ["id", "name", "email"],
  "rows": [
    [1, "Alice", "[email protected]"]
  ],
  "row_count": 1,
  "execution_time": "12ms"
}

{
  "results": [
    {
      "tenant_id": "acme",
      "columns": ["id", "name"],
      "rows": [[1, "Alice"]],
      "row_count": 1
    }
  ],
  "total_tenants": 1,
  "execution_time": "45ms"
}

{
  "success": false,
  "http_status": 403,
  "code": "role_required",
  "error": "this endpoint requires one of the following roles: admin",
  "required_roles": ["admin"],
  "current_role": "read"
}

{
  "success": false,
  "http_status": 400,
  "code": "bad_request",
  "error": "DDL not allowed on tenant databases. Deploy schema through blueprints."
}