API Overview & Authentication

The Skillett API is a REST API served over HTTPS. All requests require authentication via an API key. Responses are JSON.

Base URL

https://api.skillett.dev

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer sk_a1b2c3d4e5f6...

API keys are created on the Skillett dashboard or via the CLI after login.

Key format

Keys follow the format sk_ followed by a hex string. The first 8 characters after sk_ form the key prefix (visible in the dashboard). The full key is shown once at creation and cannot be retrieved again.

Key scopes

Keys can be scoped to specific integrations:

Scope	Access
* (default)	All integrations
github	Only GitHub endpoints
github,gmail	GitHub and Gmail only

Request format

• Content-Type: application/json for POST/PATCH requests
• Parameters: Passed in the JSON body under a params key for skill execution
• Query strings: Used for pagination and filtering on list endpoints

Response format

Success:

{
  "status": 200,
  "data": { ... }
}

Error:

{
  "error": "error_code",
  "message": "Human and agent-readable description of the error.",
  "action_url": "https://app.skillett.dev/..."
}

Tip

The action_url field in error responses provides a direct link to resolve the issue (e.g., connect an integration, upgrade a plan). Agents can surface this URL to users.

Rate limits

Plan	Rate limit	Daily limit
Free	30 req/min	10,000/day
Pro	Higher	Higher
Unlimited	Highest	Highest

When rate limited, the API returns HTTP 429:

{
  "error": "daily_limit_reached",
  "message": "Daily API call limit reached (10000). Resets at midnight UTC.",
  "action_url": "https://app.skillett.dev/billing"
}

Endpoints

Method	Path	Description
GET	/v1/skills	List integrations
GET	/v1/skills/:integration	List endpoints for integration
GET	/v1/skills/:integration/:endpoint	Endpoint documentation
POST	/v1/:integration/:endpoint	Execute an endpoint
POST	/v1/connect	Start integration connection
GET	/v1/connect/:connectionId	Poll connection status
GET	/v1/:slug/download	Download skill files
POST	/auth/device/code	Request device authorization code
POST	/auth/device/authorize	Authorize device code
POST	/auth/device/token	Poll for device token
GET	/api-keys	List API keys
POST	/api-keys	Create API key
DELETE	/api-keys/:id	Revoke API key