Projects API

Manage Supabase projects through the REST API.

Endpoints Overview

List Projects

GET /api/v1/projects

Permission: projects:read

Response:

[
  {
    "id": "my-project",
    "name": "My Project",
    "description": "Development environment",
    "directory": "/var/supascale/projects/my-project",
    "status": "running",
    "ports": {
      "api": 8000,
      "db": 5432,
      "studio": 3001
    },
    "domain": "api.example.com",
    "createdAt": "2026-01-19T10:00:00Z",
    "updatedAt": "2026-01-19T12:00:00Z"
  }
]

Create Project

POST /api/v1/projects

Permission: projects:write

Request:

{
  "id": "my-project",
  "name": "My Project",
  "description": "Development environment",
  "postgresVersion": "15"
}

Request Parameters:

Response:

{
  "id": "my-project",
  "name": "My Project",
  "directory": "/var/supascale/projects/my-project",
  "ports": { "api": 8000, "db": 5432, "studio": 3001 },
  "postgresVersion": "15",
  "externalDbAccess": false,
  "status": "running",
  "createdAt": "2026-01-19T12:00:00Z"
}

Create Project (Streaming)

POST /api/v1/projects/create

Returns Server-Sent Events with progress updates.

Request:

{
  "id": "my-project",
  "name": "My Project",
  "services": ["realtime", "storage"],
  "postgresVersion": "17"
}

Request Parameters:

Response (SSE):

event: progress
data: {"step": 1, "total": 7, "status": "running", "message": "Validating..."}

event: progress
data: {"step": 2, "total": 7, "status": "running", "message": "Generating config..."}

event: progress
data: {"step": 6, "total": 7, "status": "completed", "detail": "7 services configured (PostgreSQL 17)"}

event: complete
data: {"project": {...}}

Get Project

GET /api/v1/projects/:id

Query Parameters:

• credentials=true - Include decrypted credentials

Response:

{
  "id": "my-project",
  "name": "My Project",
  "description": "Development environment",
  "directory": "/var/supascale/projects/my-project",
  "status": "running",
  "ports": { "api": 8000, "db": 5432, "studio": 3001 },
  "domain": null,
  "enabledServices": ["db", "rest", "auth", "kong", "studio", "meta", "realtime"],
  "postgresVersion": "15",
  "externalDbAccess": false,
  "autoStart": true,
  "createdAt": "2026-01-19T10:00:00Z"
}

With credentials=true:

{
  "...": "...",
  "credentials": {
    "dbPassword": "secure-password",
    "jwtSecret": "jwt-secret-key",
    "anonKey": "eyJhbGciOiJIUzI1NiIs...",
    "serviceRoleKey": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Delete Project

DELETE /api/v1/projects/:id

Query Parameters:

• removeFiles=true - Delete project files

Response:

{
  "success": true,
  "message": "Project deleted"
}

Get Project Status

GET /api/v1/projects/:id/status

Response:

{
  "status": "running",
  "lastChecked": "2026-01-19T12:00:00Z",
  "containers": {
    "total": 8,
    "running": 8,
    "stopped": 0
  }
}

Start Project

POST /api/v1/projects/:id/start

Returns SSE with startup logs.

Response:

event: log
data: {"message": "Starting containers..."}

event: log
data: {"message": "Container db started"}

event: complete
data: {"success": true}

Stop Project

POST /api/v1/projects/:id/stop

Returns SSE with shutdown logs.

Get Project Logs

GET /api/v1/projects/:id/logs

Query Parameters:

• service - Filter by service name
• tail - Number of lines (default: 200)

Response:

{
  "logs": [
    {
      "timestamp": "2026-01-19T12:00:00Z",
      "service": "db",
      "level": "info",
      "message": "database system is ready"
    }
  ]
}

Get Containers

GET /api/v1/projects/:id/containers

Query Parameters:

• stats=true - Include CPU/memory stats

Response:

{
  "containers": [
    {
      "name": "my-project-db",
      "service": "db",
      "status": "running",
      "state": "Up 2 hours"
    }
  ]
}

With stats=true:

{
  "containers": [
    {
      "name": "my-project-db",
      "service": "db",
      "status": "running",
      "stats": {
        "cpu": "2.5%",
        "memory": "256MB / 1GB"
      }
    }
  ]
}

Get/Update Services

GET /api/v1/projects/:id/services
PUT /api/v1/projects/:id/services

GET Response:

{
  "services": ["db", "rest", "auth", "kong", "studio", "meta", "realtime"],
  "enabledServices": {
    "db": true,
    "rest": true,
    "auth": true,
    "kong": true,
    "studio": true,
    "meta": true,
    "realtime": true,
    "storage": false,
    "functions": false,
    "inbucket": false
  }
}

PUT Request:

{
  "services": ["db", "rest", "auth", "kong", "studio", "meta", "realtime", "storage"]
}

Domain Configuration

GET /api/v1/projects/:id/domain
POST /api/v1/projects/:id/domain
DELETE /api/v1/projects/:id/domain

POST Request:

{
  "name": "api.example.com",
  "sslEnabled": true,
  "webServer": "nginx"
}

POST Response:

{
  "success": true,
  "data": {
    "name": "api.example.com",
    "sslEnabled": true,
    "webServer": "nginx"
  },
  "message": "Domain configured successfully. nginx configuration generated. Restart the project for Studio to use the new domain.",
  "requiresRestart": true
}

When a domain is configured, the project's API_EXTERNAL_URL is automatically updated. You must restart the project for Supabase Studio to use the new domain for API calls.

Project Settings

GET /api/v1/projects/:id/settings
PUT /api/v1/projects/:id/settings

GET Query Parameters:

• category - storage, smtp, auth, pooler, api, database

Categories:

SMTP Settings Example

PUT Request:

{
  "category": "smtp",
  "settings": {
    "host": "smtp.example.com",
    "port": 587,
    "user": "apikey",
    "password": "your-api-key"
  }
}

Database Settings

Configure PostgreSQL version and external database access.

GET Response:

{
  "success": true,
  "data": {
    "externalAccess": false,
    "postgresVersion": "15",
    "port": 5432
  }
}

PUT Request - Enable External Access:

{
  "category": "database",
  "settings": {
    "externalAccess": true
  }
}

PUT Request - Change PostgreSQL Version:

{
  "category": "database",
  "settings": {
    "postgresVersion": "17"
  }
}

Response:

{
  "success": true,
  "message": "Database settings updated. External PostgreSQL access enabled on port 5432. Restart the project for changes to take effect.",
  "requiresRestart": true
}

External PostgreSQL Access: Enabling external access exposes your PostgreSQL port to the network. Ensure your firewall is properly configured and use strong database passwords.

PostgreSQL Version Changes: Changing the PostgreSQL version requires a full project restart. Data is preserved during the upgrade.

Inbucket Settings

Inbucket is a local email testing server that captures all outgoing emails for development and testing.

GET Response:

{
  "success": true,
  "data": {
    "enabled": true,
    "externalAccess": false
  }
}

PUT Request - Enable Inbucket:

{
  "category": "inbucket",
  "settings": {
    "enabled": true
  }
}

PUT Request - Enable External Access:

{
  "category": "inbucket",
  "settings": {
    "externalAccess": true
  }
}

Response:

{
  "success": true,
  "message": "Inbucket settings updated. External access enabled on port 54324. Restart the project for changes to take effect.",
  "requiresRestart": true
}

About Inbucket: When Inbucket is enabled, Supabase Auth is automatically configured to send emails to the local Inbucket SMTP server instead of external providers. This allows you to test email flows (signup confirmations, password resets, magic links) without sending real emails.

External Access: Enabling external access allows anyone on your network to view captured emails. This is safe for development but should not be enabled in production environments.

Auth Providers

GET /api/v1/projects/:id/auth-providers
PUT /api/v1/projects/:id/auth-providers

PUT Request:

{
  "providers": [
    {
      "provider": "google",
      "enabled": true,
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret"
    }
  ]
}