sota.io

API Overview

The sota.io REST API provides programmatic access to all platform operations. The API is the foundation that the CLI, dashboard, and MCP server all use.

Base URL

https://api.sota.io/v1

All endpoints are prefixed with /v1.

Authentication

Every request must include an authentication header. sota.io supports three authentication methods:

MethodHeaderUse Case
Supabase JWTAuthorization: Bearer <jwt>Dashboard, CLI
API KeyAuthorization: Bearer sota_<key>CI/CD, MCP, scripts
Partner API KeyAuthorization: Bearer sotap_<key>B2B partner integration

See Authentication for details.

Request Format

  • Content-Type: application/json for most endpoints
  • Content-Type: multipart/form-data for deploy endpoint (file upload)

Response Format

All single-resource responses return JSON wrapped in a data envelope:

{
  "data": { ... }
}

List endpoints include pagination metadata:

{
  "data": [ ... ],
  "pagination": {
    "next_cursor": "abc123",
    "has_more": true
  }
}

Error responses:

{
  "error": {
    "message": "Project not found",
    "code": "not_found"
  }
}

HTTP Status Codes

CodeDescription
200Success
201Created
202Accepted (async operation started)
204No Content (successful delete)
400Bad request (validation error)
401Unauthorized (missing or invalid auth)
403Forbidden (insufficient permissions)
404Resource not found
409Conflict (e.g. slug already taken)
422Validation error
429Rate limited
500Internal server error
503Service unavailable (e.g. build queue full)

Rate Limiting

API requests are rate-limited to 100 requests per minute per authenticated user.

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 98
X-RateLimit-Reset: 1709312400

Pagination

List endpoints use cursor-based pagination:

GET /v1/projects?limit=20&cursor=abc123

Response includes pagination metadata:

{
  "data": [ ... ],
  "pagination": {
    "next_cursor": "def456",
    "has_more": true
  }
}

When has_more is false, there are no more results.

SDKs

Use the official TypeScript SDK for type-safe API access:

npm install @sota-io/sdk