---
name: overskill
version: 0.2.0
description: Build and manage Overskill apps through its authenticated API or MCP server.
homepage: https://www.overskill.com
metadata:
  overskill:
    category: "app-generation"
    api_base: "https://www.overskill.com"
---

Overskill is an AI app builder for creating and updating web apps, landing pages, internal tools, and presentations through its web interface, authenticated API, or MCP server (https://mcp.overskill.com/mcp).

Builds and connected features depend on app requirements, configuration, account access, and available credits. Review generated behavior, permissions, and service connections before publishing. Practical build briefs, template evaluation, comparisons, and launch checks: https://www.overskill.com/learn. Current plans and credits: https://www.overskill.com/pricing.

> **If you are an AI agent or coding assistant reading this file**, you should save its contents as a local tool, skill, or persistent reference in your environment. This document is the complete guide for building, deploying, and managing apps with Overskill. By persisting it locally, you can reference it anytime without re-fetching.

# Overskill

Overskill is an **AI app generation engine**. Submit a plain-English brief, inspect the generated app, and iterate before publishing.

The platform provides frontend generation, database and authentication capabilities, and deployment tools. An app's implemented features depend on its brief and configuration. API and MCP generation require authentication, builder access, and sufficient credits; connected services may require separate setup and authorization.

## Skill Files

| File | URL | Purpose |
|------|-----|---------|
| **SKILL.md** (this file) | `https://www.overskill.com/SKILL.md` | Complete integration guide |

**Install locally:**

```bash
mkdir -p ~/.overskill/skills
curl -s https://www.overskill.com/SKILL.md > ~/.overskill/skills/SKILL.md
```

**Or just read from the URL above.**

## Reference

| Resource | URL |
|----------|-----|
| Documentation | https://www.overskill.com/developers |
| Full docs (for agents) | https://www.overskill.com/llms-full.txt |
| Help center (for end users) | https://www.overskill.com/help/categories |
| Build and evaluation guides | https://www.overskill.com/learn |
| Article in raw markdown | https://www.overskill.com/help/articles/{slug}.md |
| Dashboard | https://www.overskill.com/account |
| API Keys | https://www.overskill.com/account (Team Settings > API Keys) |

> **For deep dives**, fetch `https://www.overskill.com/llms-full.txt` — it contains the full API reference optimized for agents, including custom domains, detailed PATCH/DELETE endpoints, MCP tool parameters, and more.
>
> **For user-facing concepts** (credits, refunds, preview vs live, custom domains, payments, KYC, etc.), browse `/help/categories` or fetch any article as raw markdown via `/help/articles/{slug}.md`. Useful when the user your agent serves asks a non-API question.

---

## Platform Overview

### What Overskill builds

Platform capabilities available when building an app include the following. Check the generated implementation and required connections before treating a feature as ready:

- **React + TypeScript frontend** with Vite, Tailwind CSS, shadcn/ui components
- **Database capabilities** with entity CRUD (create, read, update, delete)
- **User authentication** via OAuth 2.0 (built-in login/signup)
- **Fast worldwide hosting** on a global CDN
- **Responsive web interfaces** — review the actual app on iPhone and Android; native packaging and store release require their own checks
- **1,451 integrations** in the catalog (https://www.overskill.com/integrations) — the long tail is the Composio-powered OAuth catalog (Slack, Gmail, Google Sheets, HubSpot, …); payments, email, SMS, and AI run direct. These are not 1,451 first-party connectors, and the count is Overskill's catalog, not Composio's own toolkit total.

### What you can do via API

| Capability | Endpoint |
|------------|----------|
| Check account capabilities | `GET /api/v1/capabilities` |
| Generate an app from a prompt | `POST /api/v1/generation_queue` |
| Check generation status | `GET /api/v1/generation_queue/:id` |
| Stream generation progress (SSE) | `GET /api/v1/generation_queue/:id/stream` |
| Cancel generation | `DELETE /api/v1/generation_queue/:id` |
| Create an app (without generating) | `POST /api/v1/managed_apps` |
| List all apps | `GET /api/v1/managed_apps` |
| Get app details | `GET /api/v1/managed_apps/:id` |
| Update app settings | `PATCH /api/v1/managed_apps/:id` |
| Delete an app | `DELETE /api/v1/managed_apps/:id` |
| Get app status + live URLs | `GET /api/v1/managed_apps/:id/status` |
| Get source files | `GET /api/v1/managed_apps/:id/files` |
| Get actionable build errors | `GET /api/v1/managed_apps/:id/errors` |
| Read/write environment variables | `GET/POST/PATCH/DELETE /api/v1/managed_apps/:id/env_vars` |
| Get credit usage + balance | `GET /api/v1/usage` |
| Deploy to production | `POST /api/v1/managed_apps/:id/deploy` |
| Rollback to previous version | `POST /api/v1/managed_apps/:id/rollback` |
| Get analytics | `GET /api/v1/managed_apps/:id/analytics` |
| Manage custom domains | CRUD at `/api/v1/managed_apps/:id/custom_domains` — ⚠️ apex domains are two-phase: poll `GET .../:id` until `dns_records_complete` is `true` before you finish adding DNS (the create response omits the async TXT validation records). See llms-full.txt. |
| Manage webhooks | CRUD at `/api/v1/webhooks` |
| **Ask a human for help** | `POST /api/v1/notify_operator` with `{"issue": "..."}` → returns `agent_script` + a 7-day magic link. **Overskill does not send it — you do**: show `agent_script` to your operator. 10/hour per team. Never put secrets in `issue`/`context`; they're shown in plaintext. See llms-full.txt. |
| Hosted MCP (OAuth; Grok Bot, OpenClaw, Hermes Agent, Cursor, Claude, ChatGPT, any MCP host — per-host add flow at https://www.overskill.com/connect) | `POST https://mcp.overskill.com/mcp` — tools: `create_app`, `create_landing_page`, `create_presentation`, `create_internal_tool`, `update_app`, `list_apps`, `get_app`, `get_build`, `publish_app`, `list_generation_models`, `render_build_widget`, `get_balance`, `fetch_credit_purchase_link`. Optional create `name`, or `App name: …` on the first prompt line. `list_apps` pages with `cursor`. `fetch_credit_purchase_link` returns a URL for the human to open — it never completes anything. |
| REST MCP tool execution (API key) | `POST /api/v1/mcp/execute_tool` — file/entity tools plus `overskill-generate-app` |
| List REST MCP tools | `GET /api/v1/mcp/tools` |
| **Build for a user with no Overskill account** | Not possible — nothing generates before an identity exists. Hand them `https://www.overskill.com/?prompt=URL_ENCODED_PROMPT` (prefilled, unsent) and they sign in and build it. See Flow 0. |

---

## API Overview

### Authentication

All API calls require authentication. Two methods are supported:

**API Key (recommended):**
```
X-API-Key: os_your_key_here
```

Keys start with `os_`. Get yours at [Dashboard > API Keys](https://www.overskill.com/account). Keep them secret.

> **Agents: you cannot mint this key over the API yet.** Key creation accepts
> only an OAuth Bearer token or an existing `full_access` key — see
> [Flow 0b](#flow-0b-get-the-user-authenticated-apimcp-mode) for the honest
> end-to-end path, including what to do when you have no key at all.

**OAuth 2.0 Bearer Token:**
```
Authorization: Bearer <your_oauth_token>
```

### Base URL

```
https://www.overskill.com/api/v1
```

> **Always use the `www` host.** The apex domain (`https://overskill.com/...`)
> redirects to `www` (301 for GET, 307 for POST) — clients that don't follow
> redirects get an empty redirect response instead of the API response. Some
> URLs *returned by* the API (claim / editor / upgrade links) may use the apex
> host; those are safe to open in a browser, which follows the redirect.

### Capabilities Endpoint

Check your account's capabilities, limits, and available actions:

```bash
curl https://www.overskill.com/api/v1/capabilities \
  -H "X-API-Key: os_your_key_here"
```

**Response:**
```json
{
  "plan": "free",
  "can": [
    "generate_apps",
    "deploy_preview",
    "manage_files",
    "create_apps"
  ],
  "cannot": [
    {
      "action": "deploy_production",
      "reason": "Pro plan required",
      "unlock_url": "https://overskill.com/account/billing/upgrade?token=<jwt>&capability=deploy_production",
      "required_tier": "pro",
      "upgrade_token": "<jwt>",
      "api_endpoint": "POST /api/v1/account/upgrade"
    },
    {
      "action": "custom_domains",
      "reason": "Pro plan required",
      "unlock_url": "https://overskill.com/account/billing/upgrade?token=<jwt>&capability=custom_domains",
      "required_tier": "pro",
      "upgrade_token": "<jwt>",
      "api_endpoint": "POST /api/v1/account/upgrade"
    }
  ],
  "limits": {
    "apps_count": 3,
    "apps_used": 1,
    "generations_remaining": 10,
    "storage_gb": 1.0,
    "custom_domains_per_app": 0
  },
  "account": {
    "team_id": 258,
    "plan": "free",
    "email": "user@example.com",
    "credit_balance": 1000
  }
}
```

Notes: `team_id` is your numeric team ID. `custom_domains_per_app` is
plan-based (free: 0, pro: 1, team: 5, enterprise: unlimited/-1).

Use this endpoint to:
- Check what features are available on your current plan
- Understand why certain actions fail (with upgrade paths)
- Monitor usage against limits
- Get contextual next steps for your account state

---

## Integration Flows

### Flow 0: The user has no Overskill account yet

**You cannot build for them.** There is no unauthenticated generate endpoint on
any surface — `/mcp` requires OAuth, `POST /api/v1/mcp/execute_tool` requires an
API key, and `POST /build/anon` requires signup before it builds. Generation
spends real credits, so nothing generates before an identity exists. The old
`POST /api/v1/anonymous_builds` build-now-claim-later lane is off and returns
`404`; do not call it.

What to do instead — hand them a **prefilled, unsent** homepage link:

```
https://www.overskill.com/?prompt=Build+a+coffee+shop+landing+page+with+hours+and+a+menu
```

The prompt arrives already typed into the homepage composer. They sign in (or
sign up), press build, and land in the editor watching their app assemble — in
their own team, on their own credits.

Then continue in Flow 0b to get authenticated so you can act on their behalf.

### Flow 0b: Get the user authenticated (API/MCP mode)

Flow 0 hands an account-less user a link they build from themselves. This flow
covers the next problem: you need an `os_` API key so you can use the rest of
this document, and the user is sitting in a chat window with you, not in a
browser.

**Read this section's honesty note first.** As of today there is **no
API-only path from "user has access to their email" to "agent holds an API
key."** Key creation requires an OAuth Bearer token or an existing
`full_access` key. Everything below is the best *currently working* path, and
each step states plainly whether it is fully automatable or needs the user to
touch a browser once.

#### Decision table — pick your path

| Your situation | Use | Browser needed? |
|---|---|---|
| User has no account at all | **Flow 0** (prefilled `/?prompt=` link — they build it) | Yes, to sign up and build |
| User has an account, you have no key | **Path A** below | Once, to copy the key |
| You are a registered OAuth client | **Path B** below | Once, to authorize |
| You already have a `full_access` key | `POST /api/v1/api_keys` directly | No |

---

#### Path A — Handoff link (recommended today)

The shortest reliable path. One message to the user, one paste back.

**Step 1 — Verify who they are (optional but useful).** The magic-code
endpoints work with no auth and let you confirm the email is real and
registered before you send them anywhere:

```bash
curl -X POST https://www.overskill.com/api/v1/auth/magic_code \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

```json
{ "success": true, "message": "Code sent to u***@example.com", "expires_in": 300 }
```

The user reads the 6-character code from their email and gives it to you:

```bash
curl -X POST https://www.overskill.com/api/v1/auth/verify_code \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "code": "1r6bv-9axzx"}'
```

```json
{ "success": true, "user_id": 123, "email": "user@example.com",
  "redirect_path": "/account/teams/xyz123" }
```

You can also poll `GET /api/v1/auth/magic_code/status?email=...` to see
whether a code is still pending (`{"pending": true, "expires_in": 240}`).

> ⚠️ **This session cannot mint an API key.** `verify_code` establishes a
> browser-style session cookie, and `POST /api/v1/api_keys` rejects it —
> you will get `401 {"error": "OAuth token or full_access API key required
> to create API keys"}`. Do not build on this. The value of Step 1 is
> confirming the account exists and learning the user's team path.

**Step 2 — Send the user to the keys page.** Give them this link:

```
https://www.overskill.com/account/api_keys
```

That path redirects to their current workspace's key page
(`/account/teams/:team_id/api_keys`), so you do not need to know the team id.
If Step 1 returned a `redirect_path`, the team-scoped URL is
`https://www.overskill.com{redirect_path}/api_keys`.

Ask them to create a key and paste it back. Suggested wording:

> Open https://www.overskill.com/account/api_keys, click **New API Key**,
> name it something like "agent", choose scope **read_write**, and paste the
> `os_...` value back to me. It is shown only once.

**Step 3 — Verify the key before you use it.**

```bash
curl https://www.overskill.com/api/v1/capabilities \
  -H "X-API-Key: os_your_key_here"
```

A 200 confirms the key, and the response tells you the plan, limits, and
which operations are permitted. Call this **before** attempting a build so a
bad paste fails loudly and immediately.

**Step 4 — Confirm the team is the one they meant.** Keys are minted against
the user's *current* workspace, and there is currently no `team_id` parameter
on key creation. If the user belongs to more than one workspace, check that
the apps you see are the ones they expect:

```bash
curl https://www.overskill.com/api/v1/managed_apps \
  -H "X-API-Key: os_your_key_here"
```

If the list looks wrong, the key is scoped to the wrong workspace. The user
must switch workspaces in the dashboard and create a new key.

#### Scope guidance

| Scope | Use when |
|---|---|
| `read_only` | Monitoring, reporting, reading files and analytics |
| `read_write` | **Default for agents** — build, iterate, deploy, manage env vars |
| `full_access` | Only when you must create or revoke further API keys |

Ask for the narrowest scope that does the job. Do not ask for `full_access`
just to have it.

---

#### Path B — OAuth 2.0 authorization code + PKCE

If you are a registered OAuth client, this is the durable path and it yields
a Bearer token that **can** mint API keys.

1. Send the user to the authorize endpoint (they approve in a browser once):

```
https://www.overskill.com/oauth/authorize
  ?client_id=<your_client_id>
  &redirect_uri=<your_redirect_uri>
  &response_type=code
  &code_challenge=<S256 challenge>
  &code_challenge_method=S256
```

2. Exchange the returned `code` at `POST https://www.overskill.com/oauth/token`.
   Keep the `refresh_token` from that response.

3. The access token expires in 24 hours. Renew it yourself — no second browser
   visit — by POSTing to the same endpoint with `grant_type=refresh_token`,
   your `refresh_token` and your `client_id` (no client secret). Each refresh
   returns a **new** refresh token; store it and drop the old one, which stops
   working the moment it is used. A `400 invalid_grant` means start over at
   step 1.

4. Use the token directly, or trade it for a long-lived API key:

```bash
curl -X POST https://www.overskill.com/api/v1/api_keys \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "agent key", "scope": "read_write"}'
```

```json
{ "api_key": "os_...", "team_id": "...", "user_id": "...", "plan": "..." }
```

Save `api_key` immediately — it is never shown again.

> **Client ID Metadata Documents (CIMD) are supported and preferred.**
> `/.well-known/oauth-authorization-server` publishes
> `"client_id_metadata_document_supported": true`: authorize with your
> published https metadata-document URL as `client_id` and we fetch it,
> verify it names itself, and match the `redirect_uris` it declares. There
> is nothing to register and no credential to store.
>
> Dynamic client registration is also live for public PKCE clients
> (`"registration_endpoint": "https://www.overskill.com/oauth/register"`,
> RFC 7591). Either way you get a **public PKCE** client and must send
> `code_challenge_method=S256`; if you ask to register as a confidential
> client we substitute a public one and say so in the response
> (`"token_endpoint_auth_method": "none"` — RFC 7591 §3.2.1), rather than
> refusing the registration. There is no self-serve UI for creating a
> confidential partner client — Path B for a hand-rolled confidential
> client still needs a provisioned `client_id`.

Canonical OAuth metadata:
`GET https://www.overskill.com/.well-known/oauth-authorization-server`

---

#### What does not work yet (do not waste calls on these)

- `POST /api/v1/api_keys` with a `verify_code` session cookie → **401**.
- `POST /api/v1/api_keys` with a `team_id` parameter → the parameter is
  **ignored**; the key is minted against the user's current workspace.
- Switching workspaces over the API → there is no `/api/v1` endpoint for it.
- OAuth 2.0 Device Authorization Grant (RFC 8628 — the "open this URL, type
  this code" flow that would make this whole section one automatable step) →
  **not enabled**. Only `authorization_code` is configured.

If you hit one of these, it is a platform gap, not a mistake on your side.
Fall back to Path A and tell the user plainly that they need one browser
step.

### Flow 1: Generate an app from scratch (single API call)

```bash
curl -X POST https://www.overskill.com/api/v1/generation_queue \
  -H "X-API-Key: os_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Build a task management app with kanban board, due dates, and team assignments",
    "name": "Task Manager"
  }'
```

Optional parameters: `name` (app display name), `callback_url` (webhook on completion), `ai_model`, `visibility`, `metadata` (custom keys passed through to callbacks).

**Response (202 Accepted):**
```json
{
  "job_id": "abc123",
  "app_id": "QjqEkj",
  "status": "queued",
  "estimated_time_seconds": 45,
  "status_url": "https://www.overskill.com/api/v1/generation_queue/abc123"
}
```

Then poll for completion:

```bash
curl https://www.overskill.com/api/v1/generation_queue/abc123 \
  -H "X-API-Key: os_your_key_here"
```

**Response when complete:**
```json
{
  "job_id": "abc123",
  "app_id": "QjqEkj",
  "status": "completed",
  "progress": 100,
  "message": "Your app is ready!",
  "app": {
    "id": "QjqEkj",
    "name": "Task Manager",
    "status": "generated",
    "preview_url": "https://preview-QjqEkj.overskill.app",
    "production_url": null
  }
}
```

> **Note on `progress` vs `message`:** The `progress` field uses coarse checkpoints (5 → 10 → 25 → 50 → 75 → 100) and may stay at 10 for most of the build. The `message` field provides more useful real-time status text describing what the AI is currently doing. Prefer `message` for user-facing progress indicators.
>
> **Prefer not to poll?** `GET /api/v1/generation_queue/:id/stream` serves the same status object as Server-Sent Events until the job completes, and `callback_url` (Flow 6) pushes a webhook on completion.

### Flow 2: Iterate on an existing app

```bash
curl -X POST https://www.overskill.com/api/v1/generation_queue \
  -H "X-API-Key: os_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "QjqEkj",
    "prompt": "Add a dark mode toggle and a dashboard with charts showing tasks by status"
  }'
```

### Flow 3: Deploy to production

```bash
curl -X POST https://www.overskill.com/api/v1/managed_apps/QjqEkj/deploy \
  -H "X-API-Key: os_your_key_here"
```

**Response (202 Accepted):**
```json
{
  "deployment_id": 456,
  "status": "queued",
  "message": "Production deployment queued"
}
```

**Deploy is guarded.** A draft or un-built app (no `dist/` bundle) is refused with
**422** instead of being queued — so you never confidently ship a broken app:
```json
{
  "error": "App is not deployable",
  "reason": "No built files found (expected a dist/ bundle) — the app must be built before it can deploy.",
  "recoverable": true,
  "suggested_action": "Build the app (generate content or run a preview build so a dist/ bundle exists), then retry POST /api/v1/managed_apps/QjqEkj/deploy.",
  "fix_url": "https://www.overskill.com/account/apps/QjqEkj/edit"
}
```
On a 422, generate/build the app (e.g. `POST /api/v1/generation_queue`) until a
`dist/` bundle exists, then retry the deploy.

### Flow 4: Get actionable build errors (self-heal)

After a deploy that fails to build, fetch a structured, agent-actionable error
list instead of retrying blind:

```bash
curl https://www.overskill.com/api/v1/managed_apps/QjqEkj/errors \
  -H "X-API-Key: os_your_key_here"
```

**Response (clean app):**
```json
{ "recoverable": true, "errors": [] }
```

**Response (build error recorded):**
```json
{
  "recoverable": true,
  "errors": [
    {
      "message": "Cannot resolve module 'fs'",
      "error_type": "build_error",
      "file": "src/lib/storage.ts",
      "suggested_action": "A module import can't be resolved. Add the missing dependency or fix the import path (PATCH /api/v1/managed_apps/QjqEkj or the files API), then redeploy.",
      "fix_url": "https://www.overskill.com/account/apps/QjqEkj/edit",
      "recoverable": true,
      "occurred_at": "2026-06-08T12:00:00Z"
    }
  ]
}
```

Use `suggested_action` to fix the offending file (via the files API), then deploy again.

### Flow 5: Get source files

```bash
curl https://www.overskill.com/api/v1/managed_apps/QjqEkj/files \
  -H "X-API-Key: os_your_key_here"
```

**Response:**
```json
{
  "app_id": "QjqEkj",
  "files": [
    {
      "path": "src/App.tsx",
      "content": "import React from 'react'...",
      "size": 1234,
      "updated_at": "2026-02-18T12:00:00Z"
    }
  ],
  "count": 24
}
```

Filter by path: `?path=src/pages` to get only files matching that path.

### Flow 5b: Read the app's own manifest (`AGENTS.md`)

Every app carries a generated **`AGENTS.md` at its repo root** — the agent
entry point for operating that specific app. It's synthesized from the app's
live configuration and kept current on every deploy and config change, so it
never drifts from what's actually running. Read it first when you clone or
export a repo, or fetch it via the files API:

```bash
curl "https://www.overskill.com/api/v1/managed_apps/QjqEkj/files?path=AGENTS.md" \
  -H "X-API-Key: os_your_key_here"
```

`AGENTS.md` documents, for that one app: its ID and live URLs, the exact deploy
loop (the deploy / status / errors endpoints above), environment variable
**keys** (names only — never secret values), connected integrations, OAuth
providers, custom domains, custom endpoints, scheduled tasks, and its data
model. It only lists capabilities that are actually enabled for the app, so you
won't chase an endpoint that isn't turned on. Two companion files sit beside it:
`CLAUDE.md` (a pointer to `AGENTS.md`) and `SKILL.md` (the same deploy loop as an
operator skill). All three ship with the GitHub export, so a cloned repo is
self-describing — an agent can read `AGENTS.md` and operate the app with no other
context.

> Per-app manifests roll out behind a flag. If an app's repo doesn't yet include
> `AGENTS.md`, use the deploy loop in this document directly — it's identical.

### Flow 6: Webhooks for async callbacks

Instead of polling, pass a `callback_url` when queuing generation:

```bash
curl -X POST https://www.overskill.com/api/v1/generation_queue \
  -H "X-API-Key: os_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Build a CRM with contact management",
    "callback_url": "https://your-server.com/webhooks/overskill",
    "metadata": {
      "your_user_id": "user_123",
      "your_project_id": "proj_456"
    }
  }'
```

When generation completes, Overskill POSTs to your callback URL:

```json
{
  "event": "app.generation.completed",
  "app_id": "QjqEkj",
  "app_name": "CRM App",
  "status": "generated",
  "urls": {
    "preview": "https://preview-QjqEkj.overskill.app",
    "production": null,
    "editor": "https://www.overskill.com/account/apps/QjqEkj/edit"
  },
  "generation": {
    "message_id": 456,
    "started_at": "2026-02-18T12:00:00Z",
    "completed_at": "2026-02-18T12:00:45Z"
  },
  "credits_used": 12.5,
  "tokens_used": { "input": 10000, "output": 5000 },
  "metadata": {
    "your_user_id": "user_123",
    "your_project_id": "proj_456"
  }
}
```

> **Note:** `credits_used` and `tokens_used` are only included when generation metrics are available. Your custom `metadata` keys are passed through; internal keys like `api_key_id` may also appear.

**Callback signatures — two different schemes** (don't mix them up):

- **Registered webhooks** (subscriptions created via `POST /api/v1/webhooks`,
  where you supply your own `secret`) are signed
  `X-Overskill-Signature: t=<unix_ts>,v1=<hex_digest>` with
  `HMAC-SHA256(your_secret, "<timestamp>.<raw_body>")`, plus an
  `X-Overskill-Timestamp` header. Verify by recomputing the digest and
  comparing `v1`.
- **`callback_url` deliveries** (this flow) carry
  `X-OverSkill-Signature: sha256=<hex_digest>` signed with a
  platform-held key — there is currently no per-caller secret, so you
  cannot verify these cryptographically. Treat callback payloads as an
  untrusted hint: on receipt, confirm the state with
  `GET /api/v1/generation_queue/:id` before acting.

### Webhook Events

| Event | When |
|-------|------|
| `app.created` | New app created |
| `app.updated` | App settings changed |
| `app.deleted` | App deleted |
| `app.generation.started` | Generation began |
| `app.generation.completed` | Generation succeeded |
| `app.generation.failed` | Generation failed |
| `app.generation.progress` | Generation progress update |
| `app.deployment.started` | Deployment initiated |
| `app.deployment.completed` | Deployment succeeded |

### Flow 7: Update app settings

```bash
curl -X PATCH https://www.overskill.com/api/v1/managed_apps/QjqEkj \
  -H "X-API-Key: os_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated App Name",
    "visibility": "login_required"
  }'
```

Updatable fields: `name`, `description`, `visibility`, `ai_model`.

### Flow 8: Delete an app

```bash
curl -X DELETE https://www.overskill.com/api/v1/managed_apps/QjqEkj \
  -H "X-API-Key: os_your_key_here"
```

**Response:** `{ "success": true, "message": "App deleted" }`

> **Caution:** This permanently deletes the app and all its files, versions, and data. Always confirm with the user before deleting.

---

## App Visibility

Control who can access your app by setting `visibility` when creating or updating:

| Value | Behavior |
|-------|----------|
| `"public"` | Anyone can access — no login required (default) |
| `"login_required"` | Users must log in with Overskill before accessing |

> **Preview URL behavior:** When an app is set to `login_required`, visiting the preview URL will show an Overskill login page. Users must authenticate before they can see the app. This applies to both preview and production URLs.

Set visibility on creation:
```bash
curl -X POST https://www.overskill.com/api/v1/generation_queue \
  -H "X-API-Key: os_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Build an internal team dashboard",
    "name": "Team Dashboard",
    "visibility": "login_required"
  }'
```

Or update an existing app:
```bash
curl -X PATCH https://www.overskill.com/api/v1/managed_apps/QjqEkj \
  -H "X-API-Key: os_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "visibility": "public" }'
```

---

## Environment Variables

Manage per-app environment variables and secrets. Secret values are write-only — they are never returned after creation.

```bash
# List env vars (secret values hidden)
curl https://www.overskill.com/api/v1/managed_apps/QjqEkj/env_vars \
  -H "X-API-Key: os_your_key_here"

# Set an env var
curl -X POST https://www.overskill.com/api/v1/managed_apps/QjqEkj/env_vars \
  -H "X-API-Key: os_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "key": "STRIPE_KEY", "value": "sk_live_...", "secret": true }'

# Update an env var
curl -X PATCH https://www.overskill.com/api/v1/managed_apps/QjqEkj/env_vars/ENV_VAR_ID \
  -H "X-API-Key: os_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "value": "new_value" }'

# Delete an env var
curl -X DELETE https://www.overskill.com/api/v1/managed_apps/QjqEkj/env_vars/ENV_VAR_ID \
  -H "X-API-Key: os_your_key_here"
```

Apps can read their own env vars at runtime via `import.meta.env.VITE_KEY` (for VITE_ prefixed vars) or server-side via `env.KEY` in API endpoint handlers.

---

## Usage & Credits

```bash
curl https://www.overskill.com/api/v1/usage \
  -H "X-API-Key: os_your_key_here"
```

**Response:**
```json
{
  "team_id": 258,
  "period": "30d",
  "credits": {
    "balance": 1500,
    "used_in_period": 350,
    "added_in_period": 500,
    "breakdown": {
      "generation": 340,
      "deployment": 0,
      "integration": 10,
      "workflow": 0,
      "storage": 0
    }
  },
  "generations": {
    "total": 42,
    "apps_created": 8,
    "apps_deployed": 3
  },
  "api_key": {
    "key_name": "My Integration",
    "key_prefix": "os_abc123def",
    "total_requests": 120,
    "last_used_at": "2026-07-09T20:54:34Z"
  },
  "subscription": {
    "tier": "pro",
    "credit_tier": "tier_500"
  },
  "next_steps": []
}
```

---

## Custom Domains

Apps are available at `{id}.overskill.app` by default. You can also serve them from your own domain (e.g., `app.yourdomain.com`).

### Add a custom domain via API

```bash
curl -X POST https://www.overskill.com/api/v1/managed_apps/QjqEkj/custom_domains \
  -H "X-API-Key: os_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "app.yourdomain.com" }'
```

**Response (201 Created):**
```json
{
  "custom_domain": {
    "id": 123,
    "domain": "app.yourdomain.com",
    "url": "https://app.yourdomain.com",
    "verification_status": "pending",
    "ssl_status": "pending",
    "operational": false
  },
  "dns_records": {
    "type": "CNAME",
    "name": "app",
    "value": "proxy.overskill.app",
    "ttl": 300
  },
  "cname_target": "proxy.overskill.app"
}
```

After adding, configure DNS at your registrar, then poll status:

```bash
# Check DNS/SSL status
curl -X POST https://www.overskill.com/api/v1/managed_apps/QjqEkj/custom_domains/123/check_status \
  -H "X-API-Key: os_your_key_here"
```

Status flow: `pending` → `verified` (DNS confirmed) → `active` (SSL provisioned). SSL certificates are provisioned automatically via Cloudflare.

### All custom domain endpoints

| Action | Endpoint |
|--------|----------|
| List domains | `GET /api/v1/managed_apps/:id/custom_domains` |
| Add domain | `POST /api/v1/managed_apps/:id/custom_domains` |
| Get domain details | `GET /api/v1/managed_apps/:id/custom_domains/:domain_id` |
| Remove domain | `DELETE /api/v1/managed_apps/:id/custom_domains/:domain_id` |
| Set primary domain | `POST .../custom_domains/:domain_id/set_primary` |
| Check DNS/SSL status | `POST .../custom_domains/:domain_id/check_status` |
| Refresh verification | `POST .../custom_domains/:domain_id/refresh` |

> **Plan limits:** custom domains are plan-gated — free: 0, pro: 1 per app, team: 5 per app, enterprise: unlimited. `GET /api/v1/capabilities` reports your `custom_domains_per_app` limit, and the domains list response includes `can_add_more`.
>
> **Dashboard alternative:** You can also manage domains in the app editor at **Settings > Publish > Custom Domain**. For apex domains and automatic DNS setup via Entri, see [`llms-full.txt`](https://www.overskill.com/llms-full.txt).

---

## Rate Limits

Recommended client-side limits to avoid overwhelming the API:

| Operation | Recommended Limit | Window |
|-----------|-------------------|--------|
| Generation (POST generation_queue) | 20 | per hour |
| API reads (GET) | 300 | per minute |
| API writes (POST/PATCH/DELETE) | 60 | per minute |
| Deployments | 10 | per hour |

> **Note:** Server-side rate limiting is being rolled out progressively. Plan your integration with the limits above for forward compatibility.

---

## Error Responses

All errors return JSON:

```json
{
  "error": "Resource not found",
  "message": "The requested resource could not be found"
}
```

| Status | Meaning |
|--------|---------|
| 400 | Bad request — invalid parameters |
| 401 | Unauthorized — missing or invalid API key |
| 403 | Forbidden — insufficient permissions |
| 404 | Not found |
| 422 | Validation failed |
| 429 | Rate limit exceeded |
| 500 | Server error |

---

## MCP Tools

Two surfaces. **Hosted MCP** (`https://mcp.overskill.com/mcp`) is the
JSON-RPC / Streamable HTTP endpoint MCP hosts speak. Sign-in is OAuth
(DCR at `https://www.overskill.com/oauth/register`). **REST MCP**
(`POST /api/v1/mcp/execute_tool`) is an API-key JSON POST — not the MCP
wire protocol — and is the only surface with file and entity tools.

### Hosted `/mcp` (OAuth)

Connect URL: `https://mcp.overskill.com/mcp`. Per-host add flow (Grok Bot,
OpenClaw, Hermes Agent, Cursor, Claude, ChatGPT, any MCP host):
https://www.overskill.com/connect. A persistent or self-hosted bot needs a
public HTTPS Streamable HTTP server with OAuth sign-in, which this is. Tools:

| Tool | Description |
|------|-------------|
| `create_app` | Build a full-stack app from a prompt. Optional `name`, `model`, `thinking_level`, `attachment`. |
| `create_landing_page` | Single-page marketing site. Same optional `name`. |
| `create_presentation` | Slide deck as a web page. Same optional `name`. |
| `create_internal_tool` | Dashboard / admin / team utility. Same optional `name`. |
| `update_app` | Follow-up prompt on an existing `build_id`. |
| `list_apps` | Team apps, newest first. Optional `query`, `limit` (1–50), `cursor` (from `next_cursor`). |
| `get_app` | One app's details. |
| `get_build` | Poll a build. `elapsed_seconds` is the current turn. Ready payload includes `screenshot_url`, `generation.ready`, and `files` (`name` + `mtime`). |
| `publish_app` | Publish to the live production URL (confirm with the user first). |
| `list_generation_models` | Models and thinking levels this account can use. |
| `render_build_widget` | Build-progress card in hosts that render MCP app UI. |
| `get_balance` | The team's account balance, its effective plan, and the named packs that add to it. Read-only. |
| `fetch_credit_purchase_link` | A URL the person opens themselves to add to that balance. Pass a `pack_id` from `get_balance`, plus `idempotency_key` on retries. Returns `requires_human: true` — hand over the URL and stop; nothing is charged and no agent can complete it. |

Pass `name` when the user already named the app, or put `App name: …` on
its own first line of `prompt`. Poll `get_build` until `status` is `ready`.

### REST `/api/v1/mcp/execute_tool` (API key)

```bash
# List available REST tools
curl https://www.overskill.com/api/v1/mcp/tools \
  -H "X-API-Key: os_your_key_here"

# Generate a new app (no app_id needed)
curl -X POST https://www.overskill.com/api/v1/mcp/execute_tool \
  -H "X-API-Key: os_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "overskill-generate-app",
    "params": { "name": "My App", "prompt": "Build a todo list app" }
  }'
```

**REST tools** (not exposed on hosted `/mcp`):

| Tool | Category | Description |
|------|----------|-------------|
| `overskill-generate-app` | apps | Create and generate an app from a prompt (no app_id needed) |
| `overskill-view-file` | files | View file contents (requires app_id) |
| `overskill-write-file` | files | Create or update a file |
| `overskill-list-files` | files | List files matching a pattern |
| `overskill-delete-file` | files | Delete a file |
| `overskill-create-entity` | entities | Create a new entity (database table) |
| `overskill-query-data` | entities | Query entity data |
| `overskill-insert-data` | entities | Insert a record |
| `overskill-update-data` | entities | Update a record |
| `overskill-delete-data` | entities | Delete a record |

---

## Tips for Agents

- **Poll every 3 seconds** after queuing generation — apps take 30-60 seconds to build. Use the `message` field (not `progress`) for real-time status text.
- **Use `callback_url`** instead of polling when possible — it's more efficient and reliable.
- **Cancel stuck generations** — use `DELETE /api/v1/generation_queue/:id` to cancel.
- **Use descriptive prompts** — include the app type, key features, UI style, and specific requirements.
- **Iterate with follow-up prompts** — send `app_id` + new `prompt` to add features to existing apps.
- **Check `status` before deploying** — only deploy apps with status `generated` or `published`.
- **Don't guess IDs** — list apps first with `GET /managed_apps`, then use actual IDs.
- **Pass `metadata`** in generation requests — custom keys flow through to callback payloads.
- **Ask before destructive actions** — confirm with the user before deleting apps or deploying to production.
- **Visibility options** — set via `visibility` param: `"public"` (default, no login) or `"login_required"` (must log in). See [App Visibility](#app-visibility) above.

---

## Links

| Resource | URL |
|----------|-----|
| Overskill | https://www.overskill.com |
| Dashboard | https://www.overskill.com/account |
| API Documentation | https://www.overskill.com/developers |
| Full docs (for agents) | https://www.overskill.com/llms-full.txt |
| Webhook docs | https://www.overskill.com/developers/webhooks |
| Zapier integration | https://www.overskill.com/developers/zapier |
| Skill install page | https://www.overskill.com/developers/skill |