---
name: overskill
version: 0.1.0
description: AI app generation engine. Build, deploy, and manage full-stack web apps from natural language prompts.
homepage: https://overskill.com
metadata:
  overskill:
    category: "app-generation"
    api_base: "https://overskill.com"
---

> **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**. Send a plain-English prompt and get back a live, deployed full-stack web app in seconds.

Every generated app includes: React + TypeScript frontend, secure database, user authentication, and fast worldwide hosting — all handled automatically.

## Skill Files

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

**Install locally:**

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

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

## Reference

| Resource | URL |
|----------|-----|
| Documentation | https://overskill.com/developers |
| Full docs (for agents) | https://overskill.com/llms-full.txt |
| Dashboard | https://overskill.com/account |
| API Keys | https://overskill.com/account (Settings > API Keys) |

> **For deep dives**, fetch `https://overskill.com/llms-full.txt` — it contains the full API reference optimized for agents.

---

## Platform Overview

### What OverSkill builds

Each generated app is a complete, production-ready web application:

- **React + TypeScript frontend** with Vite, Tailwind CSS, shadcn/ui components
- **Secure database** with entity CRUD (create, read, update, delete)
- **User authentication** via OAuth 2.0 (built-in login/signup)
- **Fast worldwide hosting** on a global CDN
- **Automatic mobile support** — works on iPhone and Android
- **850+ integrations** — Stripe, Gmail, Slack, Google Sheets, and more

### What you can do via API

| Capability | Endpoint |
|------------|----------|
| Generate an app from a prompt | `POST /api/v1/generation_queue` |
| Check generation status | `GET /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` |
| Get app status + live URLs | `GET /api/v1/managed_apps/:id/status` |
| Get source files | `GET /api/v1/managed_apps/:id/files` |
| 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 webhooks | CRUD at `/api/v1/webhooks` |
| MCP tool execution | `POST /api/v1/mcp/execute_tool` |

---

## API Overview

### Authentication

All API calls require the `X-API-Key` header. Keys are available at [Dashboard > API Keys](https://overskill.com/account).

```
X-API-Key: os_your_key_here
```

Keys start with `os_`. Keep them secret.

### Base URL

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

---

## Integration Flows

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

```bash
curl -X POST https://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"
  }'
```

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

Then poll for completion:

```bash
curl https://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,
  "app": {
    "id": "QjqEkj",
    "name": "Task Manager",
    "status": "generated",
    "preview_url": "https://preview-QjqEkj.overskill.app",
    "production_url": null
  }
}
```

### Flow 2: Iterate on an existing app

```bash
curl -X POST https://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://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"
}
```

### Flow 4: Get source files

```bash
curl https://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 5: Webhooks for async callbacks

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

```bash
curl -X POST https://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://overskill.com/account/apps/QjqEkj/edit"
  },
  "credits_used": 12.5,
  "tokens_used": { "input": 10000, "output": 5000 },
  "metadata": {
    "your_user_id": "user_123",
    "your_project_id": "proj_456"
  }
}
```

Verify callback authenticity with the `X-OverSkill-Signature` header (HMAC-SHA256).

### 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.deployment.started` | Deployment initiated |
| `app.deployment.completed` | Deployment succeeded |

---

## Rate Limits

| Operation | 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 |

Rate limit headers are returned on all API responses:
- `X-RateLimit-Limit` — max requests in window
- `X-RateLimit-Remaining` — remaining requests
- `X-RateLimit-Reset` — Unix timestamp when limit resets
- `Retry-After` — seconds until you can retry (on 429)

---

## 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 |

---

## Tips for Agents

- **Always use `--json` output** when processing responses programmatically.
- **Poll every 3 seconds** after queuing generation — apps take 30-60 seconds to build.
- **Use `callback_url`** instead of polling when possible — it's more efficient and reliable.
- **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 — it flows through to webhooks unchanged, great for tracking.
- **Ask before destructive actions** — confirm with the user before deleting apps or deploying to production.

---

## Links

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