API Overview

The Supascale API provides programmatic access to all platform features, enabling automation, integrations, and custom tooling for infrastructure management.

API Fundamentals

Base URL

Production: https://api.supascale.io/v1
Staging: https://api-staging.supascale.io/v1

Authentication

All API requests require authentication using API keys:

# Include API key in Authorization header
curl -H "Authorization: Bearer sk_live_abc123..." \
     https://api.supascale.io/v1/servers

API Key Types:

• Live Keys (sk_live_...): Production environment
• Test Keys (sk_test_...): Development and testing
• Read-only Keys (sk_readonly_...): Limited to GET operations

Request Format

Content Type: application/json Character Encoding: UTF-8

curl -X POST \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "production-server"}' \
  https://api.supascale.io/v1/servers

Response Format

All responses are JSON with consistent structure:

Success Response:

{
  "success": true,
  "data": {
    "id": "srv_abc123",
    "name": "production-server",
    "status": "online"
  },
  "meta": {
    "timestamp": "2025-08-02T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Server name is required",
    "details": {
      "field": "name",
      "reason": "missing_required_field"
    }
  },
  "meta": {
    "timestamp": "2025-08-02T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Rate Limiting

Rate Limits:

• Standard Plan: 1,000 requests per hour
• Professional Plan: 5,000 requests per hour
• Enterprise Plan: Custom limits

Rate Limit Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1641024000
X-RateLimit-Window: 3600

Rate Limit Exceeded:

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "API rate limit exceeded",
    "details": {
      "limit": 1000,
      "window": 3600,
      "retry_after": 1800
    }
  }
}

Pagination

Large result sets are paginated using cursor-based pagination:

Request Parameters:

GET /v1/servers?limit=50&cursor=eyJpZCI6InNydl9hYmMxMjMifQ

Response Structure:

{
  "success": true,
  "data": [
    {
      "id": "srv_abc123",
      "name": "server-1"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6InNydl94eXo3ODkifQ",
    "limit": 50,
    "total_count": 150
  }
}

Error Handling

HTTP Status Codes

• 200 OK: Successful GET, PUT, or PATCH
• 201 Created: Successful POST
• 204 No Content: Successful DELETE
• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource not found
• 409 Conflict: Resource already exists or conflict
• 422 Unprocessable Entity: Validation errors
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error
• 503 Service Unavailable: Temporary service issues

Error Codes

Authentication Errors:

• invalid_api_key: API key is invalid or expired
• insufficient_permissions: Operation not allowed for this key
• account_suspended: Account access suspended

Validation Errors:

• validation_error: Request data validation failed
• invalid_parameter: Specific parameter is invalid
• missing_required_field: Required field not provided

Resource Errors:

• resource_not_found: Requested resource doesn't exist
• resource_already_exists: Resource already exists
• resource_conflict: Operation conflicts with current state

System Errors:

• rate_limit_exceeded: API rate limit exceeded
• server_error: Internal server error
• service_unavailable: Service temporarily unavailable

Common Patterns

Filtering

Filter results using query parameters:

# Filter servers by status
GET /v1/servers?status=online

# Filter instances by server
GET /v1/instances?server_id=srv_abc123

# Multiple filters
GET /v1/backups?instance_id=inst_abc123&status=completed&created_after=2025-01-01

Sorting

Sort results using the sort parameter:

# Sort by creation date (newest first)
GET /v1/servers?sort=-created_at

# Sort by name (ascending)
GET /v1/instances?sort=name

# Multiple sort fields
GET /v1/backups?sort=-created_at,name

Field Selection

Request specific fields using the fields parameter:

# Only return id and name
GET /v1/servers?fields=id,name

# Include related data
GET /v1/instances?fields=id,name,server.name,status

Async Operations

Long-running operations return operation objects:

Initial Request:

POST /v1/instances

Response:

{
  "success": true,
  "data": {
    "operation_id": "op_abc123",
    "status": "pending",
    "resource_type": "instance",
    "estimated_duration": 300
  }
}

Check Operation Status:

GET /v1/operations/op_abc123

Operation Complete:

{
  "success": true,
  "data": {
    "operation_id": "op_abc123",
    "status": "completed",
    "result": {
      "instance_id": "inst_abc123",
      "instance_url": "https://abc123.supascale.io"
    }
  }
}

Webhooks

Subscribe to events using webhooks:

Webhook Configuration:

{
  "url": "https://your-app.com/webhook",
  "events": [
    "server.created",
    "instance.deployed",
    "backup.completed",
    "alert.triggered"
  ],
  "secret": "your-webhook-secret"
}

Webhook Payload:

{
  "event": "instance.deployed",
  "timestamp": "2025-08-02T10:30:00Z",
  "data": {
    "instance_id": "inst_abc123",
    "server_id": "srv_abc123",
    "status": "running"
  },
  "signature": "sha256=abc123..."
}

SDK and Libraries

Official SDKs

Node.js/TypeScript:

npm install @supascale/node

import { Supascale } from '@supascale/node';

const supascale = new Supascale('sk_live_abc123...');

// List servers
const servers = await supascale.servers.list();

// Create instance
const instance = await supascale.instances.create({
  server_id: 'srv_abc123',
  project_name: 'my-app'
});

Python:

pip install supascale

import supascale

client = supascale.Client('sk_live_abc123...')

# List servers
servers = client.servers.list()

# Create instance
instance = client.instances.create(
    server_id='srv_abc123',
    project_name='my-app'
)

Go:

go get github.com/supascale/supascale-go

import "github.com/supascale/supascale-go"

client := supascale.NewClient("sk_live_abc123...")

// List servers
servers, err := client.Servers.List(ctx, nil)

// Create instance
instance, err := client.Instances.Create(ctx, &supascale.InstanceCreateParams{
    ServerID:    "srv_abc123",
    ProjectName: "my-app",
})

Community Libraries

• PHP: supascale/supascale-php
• Ruby: supascale-ruby
• Java: com.supascale:supascale-java
• C#/.NET: Supascale.NET

API Resources

Core Resources

• Servers: Manage server registration and monitoring
• Instances: Deploy and manage Supabase instances
• Backups: Configure and manage backup operations
• Monitoring: Access metrics and configure alerts
• Logs: Retrieve and search log data

Management Resources

• Operations: Track long-running operations
• Webhooks: Configure event notifications
• API Keys: Manage API access credentials
• Usage: Access billing and usage information

Testing and Development

Test Environment

Use test API keys for development:

# Test environment
curl -H "Authorization: Bearer sk_test_abc123..." \
     https://api-staging.supascale.io/v1/servers

API Explorer

Interactive API documentation available at:

• https://docs.supascale.io/api

Postman Collection

Import our Postman collection:

curl -o supascale-api.json \
  https://docs.supascale.io/postman/collection.json

Best Practices

Error Handling

Implement robust error handling:

try {
  const instance = await supascale.instances.create(params);
  console.log('Instance created:', instance.id);
} catch (error) {
  if (error.code === 'validation_error') {
    console.error('Validation failed:', error.details);
  } else if (error.code === 'rate_limit_exceeded') {
    console.log('Rate limited, retrying in:', error.retry_after);
    // Implement exponential backoff
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Idempotency

Use idempotency keys for safe retries:

curl -X POST \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Idempotency-Key: unique-operation-id" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-server"}' \
  https://api.supascale.io/v1/servers

Performance Optimization

• Use field selection to reduce payload size
• Implement proper caching for frequently accessed data
• Use pagination for large datasets
• Leverage webhooks instead of polling

Security

• Store API keys securely (environment variables)
• Use read-only keys when write access isn't needed
• Rotate API keys regularly
• Validate webhook signatures
• Use HTTPS for all requests

Next: Explore Server API endpoints for detailed server management operations.