OverSkill Developer Docs

Hosted MCP server

AI agents connect to https://mcp.overskill.com/mcp (Streamable HTTP, OAuth sign-in). Host-by-host setup is on /connect. Tools marked changes data need the apps:write grant.

Tool	What it does
`create_app`changes data	Build a full-stack web app from a plain-language description.
`create_landing_page`changes data	Build a single-page website from a plain-language description — a landing page, marketing page, or simple site for a business, product, event, service, or person, with sections such as a hero, features, testimonials, and contact.
`create_presentation`changes data	Build a slide presentation as a web page the user presents from a URL — full-screen slides with keyboard and click navigation.
`create_internal_tool`changes data	Build an internal tool from a plain-language description — a dashboard, admin panel, CRUD screen, tracker, or small team utility.
`get_build`	Check the status of an Overskill build on the signed-in account.
`render_build_widget`	Show an interactive build-progress card for a build started with one of the create tools: live status, a screenshot when ready, and preview and editor links.
`list_apps`	List the apps on the connected Overskill team that the user can see, newest first.
`list_generation_models`	List the generation models the signed-in account can use for create_app and update_app, including each model's thinking levels (or that it has none).
`get_app`	Get one app on the connected team: status, description, preview and live URLs, when it was published, the editor link, and the same screenshot_url / generation.ready / files fields as get_build.
`update_app`changes data	Send a follow-up prompt to an app on the connected Overskill team.
`publish_app`changes data	Publish an app on the connected team to its live production URL.
`get_balance`	Report the Overskill account balance on the connected team: how much is left to spend on builds, the plan the team is effectively on, and the named packs that can add to that balance.
`fetch_credit_purchase_link`changes data	Fetch a URL the user opens themselves to add to their Overskill account balance.
`add_auth`changes data	Set who may open an app on the connected Overskill team: access "signed_in" (people sign in with email or Google before they see it), "email_domain" (only people whose sign-in email is at one of allowed_email_domains, for an internal tool) or "anyone" (no sign-in).
`connect_integration`	Look up one integration from the Overskill catalog (Slack, Google Sheets, HubSpot, Notion and about 1,450 more) by slug, and say whether the connected team already has it connected.
`submit_feedback`	Report friction with a Overskill tool so the team can fix it: a confusing input schema, a missing capability, a wrong result, an error, or a gap in the docs.

Authentication

The Overskill API supports two authentication methods:

API Key Authentication

Include your API key in the X-API-Key header:

curl -H "X-API-Key: os_your_api_key_here" \
  https://overskill.com/api/v1/managed_apps

OAuth 2.0 Bearer Token

For OAuth integrations (like Zapier), use Bearer token authentication:

curl -H "Authorization: Bearer your_oauth_token" \
  https://overskill.com/api/v1/managed_apps

Rate Limiting

API requests are rate limited based on your plan:

Plan	Requests/Minute
Free	60
Pro	300
Enterprise	1,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1703332800

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent format:

{
  "error": "Unauthorized",
  "message": "Invalid or expired API key"
}

Status Code	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing authentication
`403`	Forbidden - Insufficient permissions
`404`	Not Found
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

GET List Apps

Returns a paginated list of all apps in your workspace.

Endpoint

GET https://overskill.com/api/v1/managed_apps

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (max: 100, default: 25)
`status`	string	Filter by status (draft, generating, published)
`name`	string	Filter by name (partial match)

Response

{
  "apps": [
    {
      "id": "abc123",
      "name": "Task Manager",
      "status": "published",
      "visibility": "public",
      "preview_url": "https://preview-abc123.overskill.app",
      "production_url": "https://abc123.overskill.app",
      "created_at": "2025-12-23T10:00:00Z",
      "updated_at": "2025-12-23T12:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 125,
    "per_page": 25
  }
}

GET Get App

Retrieve detailed information about a specific app by its ID.

Endpoint

GET https://overskill.com/api/v1/managed_apps/:id

Response

{
  "app": {
    "id": "abc123",
    "name": "Task Manager",
    "description": "A task management app",
    "status": "published",
    "visibility": "public",
    "ai_model": "claude-sonnet-4-6",
    "preview_url": "https://preview-abc123.overskill.app",
    "production_url": "https://abc123.overskill.app",
    "published_at": "2025-12-23T12:00:00Z",
    "creator": {
      "id": 42,
      "email": "[email protected]"
    },
    "versions_count": 5,
    "files_count": 24,
    "users_count": 89,
    "urls": {
      "editor": "https://overskill.com/account/apps/abc123/edit",
      "preview": "https://preview-abc123.overskill.app",
      "production": "https://abc123.overskill.app"
    },
    "created_at": "2025-12-20T10:00:00Z",
    "updated_at": "2025-12-23T12:00:00Z"
  }
}

POST Create App

Create a new app. Optionally provide a prompt to immediately queue generation.

Endpoint

POST https://overskill.com/api/v1/managed_apps

Request Body

{
  "name": "My Task Manager",
  "prompt": "Create a task management app with projects, tasks, due dates, and team collaboration",
  "visibility": "public",
  "ai_model": "claude-sonnet-4-6",
  "auto_generate": true
}

Response (201 Created)

{
  "app": {
    "id": "xyz789",
    "name": "My Task Manager",
    "status": "generating",
    "preview_url": null,
    "created_at": "2025-12-23T14:00:00Z"
  },
  "message": "App created and generation queued"
}

POST Deploy App

Trigger a production deployment for an app. The deployment runs asynchronously.

Endpoint

POST https://overskill.com/api/v1/managed_apps/:id/deploy

Response (202 Accepted)

{
  "deployment_id": 42,
  "status": "queued",
  "message": "Production deployment queued"
}

POST Queue Generation

Queue a new app generation or edit with a prompt. Receive webhook updates as the generation progresses.

Endpoint

POST https://overskill.com/api/v1/generation_queue

Request Body

{
  "prompt": "Add a dark mode toggle to the settings page",
  "app_id": "abc123",
  "callback_url": "https://your-server.com/webhook"
}

Response (202 Accepted)

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

GET Check Generation Status

Check the status of a queued generation job. Poll this endpoint after queuing a generation.

Endpoint

GET https://overskill.com/api/v1/generation_queue/:id

Status Values

Status	Description
`queued`	Waiting to start
`processing`	Generation in progress
`completed`	Successfully finished
`failed`	Error occurred

Response

{
  "job_id": "jid_abc123",
  "app_id": "abc123",
  "status": "processing",
  "progress": 65,
  "message": "Generating components...",
  "started_at": "2025-12-23T12:05:15Z",
  "completed_at": null
}

GET List App Users

List users who have access to your apps. Filter by app, tier, or email.

Endpoint

GET https://overskill.com/api/v1/managed_users

Query Parameters

Parameter	Type	Description
`app_id`	string	Filter by app
`tier`	string	Filter by access tier
`email`	string	Search by email (partial match)
`page`, `per_page`	integer	Pagination

Response

{
  "app_users": [
    {
      "id": 789,
      "app_id": "abc123",
      "email": "[email protected]",
      "access_tier": "pro",
      "tier_granted_at": "2025-12-20T10:00:00Z",
      "tier_expires_at": "2026-12-20T10:00:00Z",
      "revoked": false,
      "first_accessed_at": "2025-12-20T10:05:00Z",
      "last_accessed_at": "2025-12-23T15:30:00Z",
      "access_count": 47
    }
  ],
  "meta": { "current_page": 1, "total_pages": 3, "total_count": 64, "per_page": 25 }
}

POST Grant User Access

Grant a user access to an app with a specific access tier.

Endpoint

POST https://overskill.com/api/v1/managed_users/grant_access

Request Body

{
  "app_id": "abc123",
  "email": "[email protected]",
  "tier": "pro",
  "expires_at": "2026-12-23T00:00:00Z"
}

Access Tiers

Tier	Description
`free`	Basic access (default)
`basic`	Standard paid tier
`pro`	Professional tier
`premium`	Premium tier
`enterprise`	Enterprise tier

Response (201 Created)

{
  "app_user": {
    "id": 789,
    "app_id": "abc123",
    "email": "[email protected]",
    "access_tier": "pro",
    "tier_granted_at": "2025-12-23T14:00:00Z",
    "tier_expires_at": "2026-12-23T00:00:00Z"
  },
  "message": "Access granted successfully"
}

POST Revoke User Access

Immediately revoke a user's access to an app.

Endpoint

POST https://overskill.com/api/v1/managed_users/:id/revoke

Response

{
  "app_user": {
    "id": 789,
    "app_id": "abc123",
    "email": "[email protected]",
    "access_tier": "pro",
    "revoked": true,
    "revoked_at": "2025-12-23T16:00:00Z"
  },
  "message": "Access revoked"
}

GET List Webhooks

Retrieve all webhook subscriptions configured for your workspace.

Endpoint

GET https://overskill.com/api/v1/webhooks

Response

{
  "webhooks": [
    {
      "id": 1,
      "url": "https://your-server.com/webhook",
      "name": "My Webhook",
      "events": ["app.created", "app.generation.completed"],
      "enabled": true,
      "source": "api",
      "created_at": "2025-12-20T10:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "total_pages": 1, "total_count": 1, "per_page": 25 }
}

POST Create Webhook

Subscribe to webhook events. Your endpoint will receive POST requests when events occur.

Endpoint

POST https://overskill.com/api/v1/webhooks

Request Body

{
  "url": "https://your-server.com/overskill-webhook",
  "name": "My Integration Webhook",
  "events": [
    "app.created",
    "app.generation.completed",
    "app.user.created"
  ]
}

Available Events

app.created - New app created
app.updated - App updated
app.deleted - App deleted
app.generation.started - Generation started
app.generation.progress - Generation progress update
app.generation.completed - Generation completed
app.generation.failed - Generation failed
app.deployment.completed - Deployment completed
app.user.created - New user accessed app
app.user.access_granted - User granted access
app.user.access_revoked - User access revoked

Webhook Signature Verification

Verify webhook authenticity using the X-Overskill-Signature header:

# Header format: t=timestamp,v1=signature
# Verify: HMAC-SHA256(timestamp + "." + payload, signing_secret)

X-Overskill-Signature: t=1703332800,v1=abc123...

GET List API Keys

List all API keys for your workspace. Keys are returned with masked values for security.

Endpoint

GET https://overskill.com/api/v1/api_keys

Response

{
  "api_keys": [
    {
      "id": 1,
      "name": "Production Key",
      "key_prefix": "os_a1b2c3d4e",
      "masked_key": "os_a1b2c3d4e...d4e",
      "scope": "read_write",
      "scope_description": "Read and write access to apps",
      "active": true,
      "expired": false,
      "expires_at": null,
      "last_used_at": "2025-12-23T15:00:00Z",
      "request_count": 1547,
      "created_at": "2025-12-01T10:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "total_pages": 1, "total_count": 1, "per_page": 25 }
}

Scope Types

Scope	Permissions
`read_only`	List and view apps, users, analytics
`read_write`	Create/update apps, grant/revoke access, queue generation
`full_access`	All permissions including delete and admin operations

POST Create API Key

Generate a new API key. The raw key is returned only once — save it immediately.

Endpoint

POST https://overskill.com/api/v1/api_keys

Request Body

{
  "name": "Production Key",
  "scope": "read_write",
  "expires_in_days": 365
}

Response (201 Created)

{
  "raw_key": "os_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4",
  "api_key": {
    "id": 2,
    "name": "Production Key",
    "key_prefix": "os_a1b2c3d4e",
    "scope": "read_write",
    "active": true,
    "expires_at": "2026-12-23T15:00:00Z",
    "created_at": "2025-12-23T15:00:00Z"
  },
  "warning": "Save this key now! It will not be shown again."
}

SDKs & Libraries

Coming soon! We're working on official SDKs for popular languages.

🐍

Python

Coming Soon

📦

Node.js

Coming Soon

💎

Ruby

Coming Soon

🔷

Go

Coming Soon

Need Help?

Have questions about the API or need help with your integration?

Contact Support Join Discord