Tài liệu API

Giới thiệu

TOSE API là RESTful API cho phép quản lý workspaces, projects, deployments, databases và nhiều hơn nữa.

Base URL

https://api-v2.tose.sh

Định dạng Response

// Thành công
{ "success": true, "data": { ... } }

// Lỗi
{ "success": false, "error": "Thông báo lỗi" }

Xác thực

Tất cả requests cần API key qua header X-API-Key.

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

Tạo API Key

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

// Response (key chỉ hiển thị MỘT lần!)
{
  "id": "...",
  "key": "tose_sk_abcdef...",
  "key_prefix": "tose_sk_abcd..."
}

Xử lý lỗi

Workspaces

Tạo workspace mới.

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

Liệt kê tất cả workspaces.

Thành viên

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

API Keys

Projects

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

Trạng thái & Điều khiển

// Response
{
  "project": { "slug": "my-app", "status": "running" },
  "pods": { "ready": 1, "total": 1, "items": [...] },
  "resources": {
    "cpu": { "used": "50m", "limit": "500m" },
    "memory": { "used": "128Mi", "limit": "512Mi" }
  }
}

Git Connection

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

Biến môi trường

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

Cập nhật hàng loạt

{
  "variables": { "DB_HOST": "localhost", "API_KEY": "secret" },
  "merge": true
}
// Response: { "created": 2, "updated": 1, "deleted": 0 }

Deployments

Query params: page, limit (1-50)

Tạo deployment mới (build từ Git).

Deploy lại với image hiện tại (không build lại).

Tên miền

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

Databases

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

Templates

Danh sách templates có sẵn.

// Response
[{
  "name": "Goclaw",
  "key": "goclaw",
  "description": "AI-powered development platform",
  "default_port": "3000",
  "default_cpu": "2",
  "default_ram": "4",
  "required_envs": [
    { "key": "GOCLAW_POSTGRES_DSN", "placeholder": "postgresql://..." }
  ]
}]

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

{ "mode": "image" }  // hoặc "build"

Template Env Vars

[
  { "key": "DATABASE_URL", "value": "postgres://..." },
  { "key": "API_KEY", "value": "secret", "is_secret": true }
]

Template Domains

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

Template Deployments

Ví & Thanh toán

Xem số dư ví.

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

Lịch sử giao dịch.

Thống kê sử dụng.

{ "amount": 100000 }

{ "amount": 10 }

{ "threshold": 10000 }

Logs

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

Tải logs dạng file gzip.

Thống kê dung lượng log.

Phân tích logs bằng AI.

{ "logs": "nội dung log lỗi..." }

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

Stream logs real-time qua WebSocket. Truyền API key qua header X-API-Key.

Project Build Logs

Project Live Logs

Template Build Logs

Template Live Logs

Ví dụ kết nối

// Sử dụng WebSocket với headers (thư viện ws)
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) => {
  if (event.data === '[END]') { ws.close(); return; }
  if (event.data.startsWith('[ERROR]')) { console.error(event.data); return; }
  console.log(event.data);
};

Lưu ý: Browser WebSocket không hỗ trợ custom headers. Sử dụng thư viện ws npm hoặc truyền API key qua query parameter ?api_key=tose_sk_... cho browser clients.

Tin nhắn đặc biệt