Getting started with the Overskill partner API

The Overskill API lets you build apps programmatically — the same generation engine behind the Overskill editor, driven from your own product, backend, or AI agent.

Base URL: https://www.overskill.com/api/v1 Auth: X-API-Key header with a key that looks like os_…

⚠️ If you've seen api.overskill.app anywhere, don't use it — that host is retired and returns 410 Gone. Everything lives at www.overskill.com/api/v1.

1. Create an API key

Go to overskill.com → Account → Team Settings → API Keys and create a key. Choose a scope:

• read_only — read apps, users, analytics
• read_write — everything above plus creating/updating apps and queueing generations (the right choice for most integrations)
• full_access — adds delete and admin operations

The key is shown once at creation. Store it in a secrets manager, never in client-side code. You can also manage keys via the API itself (GET/POST/DELETE /api/v1/api_keys) — revocation takes effect immediately.

Rate limits depend on your key's tier: standard keys get 20 generations/hour and 300 reads/minute; partner keys get 100 generations/hour and 1,000 reads/minute. Contact us about partner-tier limits for high-volume integrations.

2. Start with capabilities

Before doing anything else, call:

GET /api/v1/capabilities

The response tells you exactly what your plan can and cannot do right now:

{
  "plan": "pro",
  "can": ["generate_apps", "deploy_preview", "view_analytics", "..."],
  "cannot": [
    {
      "action": "team_collaboration",
      "reason": "Team plan or higher required",
      "required_tier": "team",
      "unlock_url": "https://overskill.com/account/billing/upgrade?token=…"
    }
  ]
}

Every cannot entry includes a signed unlock_url — a one-click upgrade link you can surface to a human. Design your integration to check capabilities first instead of hard-coding plan assumptions.

3. Generate an app

POST /api/v1/generation_queue
Content-Type: application/json

{"prompt": "A habit tracker with daily streaks", "name": "Habit Tracker"}

Returns 202 Accepted immediately:

{
  "job_id": "abc123…",
  "app_id": "XyZaBc",
  "status": "queued",
  "estimated_time_seconds": 45,
  "status_url": "https://www.overskill.com/api/v1/generation_queue/abc123…",
  "webhook_events": ["app.generation.started", "app.generation.progress", "app.generation.completed", "app.generation.failed", "app.generation.blocked"]
}

Optional request fields: app_id (edit an existing app instead of creating one), callback_url (we POST status updates to you), and metadata (your own keys, echoed back in callbacks so you can correlate).

4. Track progress — three ways

1. Poll GET /api/v1/generation_queue/{job_id} every ~15 seconds until status is completed, failed, or cancelled.
2. Stream live updates over SSE: GET /api/v1/generation_queue/{job_id}/stream with Accept: text/event-stream.
3. Webhooks — register once and get pushed events (see Using Overskill API webhooks).

To cancel a queued job: DELETE /api/v1/generation_queue/{job_id}.

5. Get URLs and deploy

GET  /api/v1/managed_apps/{app_id}          → app details incl. preview_url, production_url
POST /api/v1/managed_apps/{app_id}/deploy   → publish to production

Also useful: GET /managed_apps/{id}/status (status + live URLs), /files (source files), /errors (actionable build errors), and GET /managed_apps to list every app on your team.

6. Watch your credits

GET /api/v1/usage

Returns your credit balance, a 30-day usage breakdown by category, per-key request stats, and your subscription tier. Generations consume credits — build balance checks into anything automated.

Working examples

Complete, runnable examples (Node, Python, curl) covering this whole flow — including webhook signature verification — ship in the Overskill repo under docs/api-examples/. The Node and Python examples are dependency-free (Node 18+ / requests) and mirror this article step for step.

Machine-readable references your tooling can consume directly:

• https://www.overskill.com/llms.txt — concise API reference
• https://www.overskill.com/llms-full.txt — the complete reference
• https://www.overskill.com/SKILL.md — installable skill for AI agents

Next steps

• Using Overskill API webhooks
• Overskill API errors and how to handle them
• Using Overskill from AI agents