Getting started with the OverSkill partner API

Generate, manage, and deploy apps programmatically. Auth, the core call sequence, and working code in Node, Python, and curl.

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