OverSkill API

The OverSkill API supports two authentication methods:

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

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

API requests are rate limited based on your plan:

Rate limit headers are included in every response:

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

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

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

Returns a paginated list of all apps in your workspace.

Endpoint

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

Query Parameters

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

Retrieve detailed information about a specific app by its ID.

Endpoint

GET https://www.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-5",
    "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"
  }
}

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

Endpoint

POST https://www.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-5",
  "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"
}

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

Endpoint

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

Response (202 Accepted)

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

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

Endpoint

POST https://www.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://www.overskill.com/api/v1/generation_queue/jid_abc123"
}

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

Endpoint

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

Status Values

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
}

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

Endpoint

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

Query Parameters

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

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

Endpoint

POST https://www.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

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"
}

Immediately revoke a user's access to an app.

Endpoint

POST https://www.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"
}

Retrieve all webhook subscriptions configured for your workspace.

Endpoint

GET https://www.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 }
}

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

Endpoint

POST https://www.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...

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

Endpoint

GET https://www.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

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

Endpoint

POST https://www.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."
}