API Reference

Coming Soon

Programmatic access to SKYCOT for creating projects, triggering builds, and downloading generated code. Available on Pro plans and above.

Authentication

All API requests are authenticated using API keys. Each key is scoped to a single account and inherits the account's subscription tier and token allowance.

# Include your API key in the Authorization header
curl https://api.skycot.com/api/v1/projects \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json"

Key Management

Generate keys in Settings → API Keys in the dashboard
Each account can have up to 5 active API keys
Keys can be revoked individually without affecting others
Key prefixes: sk_live_ for production, sk_test_ for sandbox

Rate Limits

Pro: 60 requests per minute
Business: 120 requests per minute
Enterprise: Custom rate limits
Rate limit headers included in every response (X-RateLimit-Remaining, X-RateLimit-Reset)

Base URL

All API endpoints use the following base URL. Self-hosted Enterprise deployments use your configured domain instead.

https://api.skycot.com/api/v1

Planned Endpoints

The following endpoints are planned for the initial API release. All responses return JSON with consistent error shapes validated by Zod schemas.

Method	Endpoint	Description	Min Tier
POST	/api/v1/projects	Create a new project with name, description, and archetype hint	Pro+
GET	/api/v1/projects	List all projects for the authenticated account	Pro+
GET	/api/v1/projects/:id	Retrieve project details including build history and status	Pro+
POST	/api/v1/projects/:id/builds	Trigger a new build with requirements and configuration options	Pro+
GET	/api/v1/builds/:id	Get build status, progress, session breakdown, and token usage	Pro+
GET	/api/v1/builds/:id/files	List all generated files with paths, sizes, and types	Pro+
GET	/api/v1/builds/:id/files/:path	Download a single generated file by path	Pro+
GET	/api/v1/builds/:id/download	Download the complete build output as a ZIP archive	Pro+
POST	/api/v1/builds/:id/deploy	Trigger one-click deployment to Vercel + Supabase	Business+
GET	/api/v1/usage	Retrieve current billing period token usage and remaining allowance	Pro+

Example: Create Project

The following shows the planned request and response format for creating a new project via the API.

Request

POST /api/v1/projects
Authorization: Bearer sk_live_your_api_key_here
Content-Type: application/json

{
  "name": "My SaaS Dashboard",
  "description": "A project management tool with kanban boards, team collaboration, and time tracking",
  "archetype_hint": "project-management"
}

Response (201 Created)

{
  "id": "proj_abc123def456",
  "name": "My SaaS Dashboard",
  "description": "A project management tool with kanban boards...",
  "archetype": "project-management",
  "status": "created",
  "created_at": "2026-03-15T10:30:00Z"
}

Example: Trigger Build

Once a project exists, trigger a build by providing requirements and configuration. The response includes a build ID for polling status.

Request

POST /api/v1/projects/proj_abc123def456/builds
Authorization: Bearer sk_live_your_api_key_here
Content-Type: application/json

{
  "requirements": "Add kanban board with drag-and-drop, team member assignment, and due date tracking",
  "model_preference": "balanced",
  "integrations": ["slack"]
}

Response (202 Accepted)

{
  "build_id": "bld_xyz789ghi012",
  "status": "compiling",
  "estimated_tokens": 45000,
  "estimated_sessions": 8,
  "poll_url": "/api/v1/builds/bld_xyz789ghi012"
}

Error Handling

All error responses follow a consistent shape with a machine-readable error code, a human-readable message, and optional details.

{
  "error": {
    "code": "token_limit_exceeded",
    "message": "Monthly token allowance exhausted. Upgrade your plan or wait for the next billing cycle.",
    "details": {
      "tokens_used": 10250000,
      "tokens_limit": 10000000,
      "overage_rate": "8.00 per 1M tokens"
    }
  }
}

HTTP Status	Meaning
400	Invalid request body or parameters (Zod validation failure)
401	Missing or invalid API key
403	Insufficient plan tier for the requested resource
404	Project or build not found
429	Rate limit exceeded (check X-RateLimit-Reset header)
500	Internal server error (retry with exponential backoff)

SDKs & Webhooks

Official SDKs and webhook support are planned alongside the API release. These will provide typed clients and event-driven notifications for build lifecycle events.

Planned SDKs

TypeScript / JavaScript (npm package)
Python (PyPI package)
Go module

Webhook Events

build.started — Build compilation has begun
build.completed — All sessions finished and verification passed
build.failed — Build failed after recovery attempts exhausted
deploy.completed — Application successfully deployed to production

API Access

The REST API is currently in development. Pro and Business subscribers will receive early access when the beta launches. To join the API waitlist or discuss Enterprise API requirements, contact api@skycot.com.