API Reference

Introduction

The TOSE API is a RESTful API that allows you to manage workspaces, projects, deployments, databases, and more programmatically.

Base URL

https://api-v2.tose.sh

Response Format

All responses return JSON with this structure:

{
  "success": true,
  "data": { ... }
}

Error responses:

{
  "success": false,
  "error": "Error message"
}

Authentication

All API requests require an API key passed via the X-API-Key header.

curl https://api-v2.tose.sh/api/workspaces \
  -H "X-API-Key: tose_sk_your_key_here"

Getting an API Key

Create API keys from the dashboard or via the API:

POST /api/workspaces/:slug/api-keys
{
  "name": "My CLI Key",
  "expires_in_days": 90
}

The full API key is only returned once on creation. Store it securely.

API key format: tose_sk_ followed by 40 hex characters.

Error Handling

Workspaces

Create a new workspace.

// Request
{ "name": "My Workspace", "slug": "my-workspace" }

// Response
{ "id": "...", "name": "My Workspace", "slug": "my-workspace", "namespace": "..." }

List all workspaces you have access to.

Get workspace details.

Update workspace name or settings.

Delete a workspace and all its resources.

Members

{ "user_id": "...", "role": "admin" }  // Roles: owner, admin, member

Invitations

{ "email": "user@example.com", "role": "member" }

API Keys

// Request
{ "name": "Production Key", "expires_in_days": 90 }

// Response (key shown only once!)
{
  "id": "...",
  "name": "Production Key",
  "key": "tose_sk_abcdef...",
  "key_prefix": "tose_sk_abcd...",
  "expires_at": "2026-06-15T00:00:00Z"
}

Projects

// Request
{
  "name": "My App",
  "port": 3000,
  "replicas": 1,
  "cpu": "0.5",
  "ram": "0.5"
}

// Response
{
  "id": "...",
  "name": "My App",
  "slug": "my-app",
  "status": "pending",
  "port": 3000,
  "replicas": 1,
  "cpu": "0.5",
  "ram": "0.5",
  "created_at": "..."
}

List all projects in a workspace.

Get project details.

Update project settings (name, port, replicas, cpu, ram, etc.).

Delete project and all associated resources.

Status & Control

// Response
{
  "project": { "slug": "my-app", "status": "running" },
  "pods": {
    "ready": 1, "total": 1,
    "items": [{ "name": "...", "status": "Running", "restarts": 0, "age": "2h" }]
  },
  "resources": {
    "cpu": { "used": "50m", "limit": "500m" },
    "memory": { "used": "128Mi", "limit": "512Mi" }
  },
  "latestDeployment": { "id": "...", "status": "running", "created_at": "..." }
}

Git Connection

{
  "repo_full_name": "owner/repo",
  "branch": "main",
  "installation_id": 12345,
  "auto_deploy": true
}

Environment Variables

{ "key": "DATABASE_URL", "value": "postgres://...", "is_secret": true }

Bulk Update

// Request
{
  "variables": {
    "DB_HOST": "localhost",
    "DB_PORT": "5432",
    "API_KEY": "secret"
  },
  "merge": true  // false = replace all
}

// Response
{ "created": 2, "updated": 1, "deleted": 0 }

Deployments

Query params: page (default: 1), limit (1-50, default: 20)

// Response
{
  "deployments": [...],
  "total": 42,
  "page": 1,
  "limit": 20
}

Trigger a new deployment (builds from Git).

Redeploy using existing image (no rebuild).

Stop a specific deployment.

Rollback to a previous deployment.

Domains

{ "domain": "app.example.com" }

Databases

// Request
{ "name": "my-postgres", "type": "postgresql" }
// Types: postgresql, mysql, redis, mongo

// Response
{
  "id": "...",
  "name": "my-postgres",
  "type": "postgresql",
  "status": "running",
  "host": "...",
  "port": 5432,
  "username": "...",
  "password": "...",
  "database_name": "...",
  "connection_string": "postgresql://..."
}

Templates

List available pre-built templates (catalog).

// Response
[{
  "name": "Goclaw",
  "key": "goclaw",
  "description": "AI-powered development platform",
  "source": "https://github.com/...",
  "default_port": "3000",
  "default_cpu": "2",
  "default_ram": "4",
  "required_envs": [
    { "key": "GOCLAW_POSTGRES_DSN", "placeholder": "postgresql://..." },
    { "key": "GOCLAW_ENCRYPTION_KEY", "placeholder": "32-char hex" },
    { "key": "GOCLAW_GATEWAY_TOKEN", "placeholder": "token" }
  ]
}]

{ "name": "My App", "template_name": "goclaw" }

{ "mode": "image" }  // or "build"

Template Environment Variables

// Request (array of key-value pairs)
[
  { "key": "DATABASE_URL", "value": "postgres://..." },
  { "key": "API_KEY", "value": "secret", "is_secret": true }
]

Template Domains

{ "domain": "app.example.com" }

Template Deployments

Wallet & Billing

Get wallet balance and currency.

// Response
{ "balance": 50000, "currency": "VND" }

List billing transactions (paginated).

Get current usage statistics.

List payment history.

{ "amount": 100000 }

{ "amount": 10 }

{ "threshold": 10000 }

Logs

Query params: limit, direction (asc/desc), start, end

Download logs as gzipped file.

Get log storage usage statistics.

AI-powered log analysis.

{ "logs": "error log content here..." }

Uptime Monitoring

// Response
{
  "enabled": true,
  "check_interval_sec": 60,
  "check_url": "https://my-app.tose.sh/health",
  "discord_webhook_url": "...",
  "notify_email": "admin@example.com",
  "status": "up",
  "last_checked_at": "...",
  "last_response_ms": 120
}

{
  "enabled": true,
  "check_interval_sec": 60,
  "discord_webhook_url": "https://discord.com/api/webhooks/...",
  "notify_email": "admin@example.com"
}

WebSocket Endpoints

Real-time log streaming via WebSocket. Pass API key via the X-API-Key header.

Project Build Logs

Project Live Logs

Template Build Logs

Template Live Logs

Connection Example

// Using WebSocket with headers (via ws library)
const WebSocket = require('ws');
const ws = new WebSocket(
  'wss://api-v2.tose.sh/api/workspaces/my-ws/projects/my-app/live-logs',
  { headers: { 'X-API-Key': 'tose_sk_...' } }
);

ws.onmessage = (event) => {
  const data = event.data;
  if (data === '[END]') {
    ws.close();
    return;
  }
  if (data.startsWith('[ERROR]')) {
    console.error(data);
    ws.close();
    return;
  }
  console.log(data);
};

Note: Browser WebSocket does not support custom headers. Use the ws npm package or pass the API key as a query parameter ?api_key=tose_sk_... as a fallback for browser clients.

Special Messages