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"
}

Response:

{
  "id": "my-project",
  "name": "My Project",
  "directory": "/var/supascale/projects/my-project",
  "ports": { "api": 8000, "db": 5432, "studio": 3001 },
  "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"]
}

Response (SSE):

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

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

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"],
  "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
  }
}

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"
}

Project Settings

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

GET Query Parameters:

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

PUT Request:

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

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"
    }
  ]
}