Building with the API

While the CLI is the recommended interface, you can also use the Skillett REST API directly from custom agent frameworks, scripts, or applications.

Authentication

All requests require an API key:

Authorization: Bearer sk_a1b2c3d4e5f6...

Integration pattern

1. Discover available integrations

   GET /v1/skills

   Check which integrations are connected and available.

2. Get endpoint documentation

   GET /v1/skills/github/create_issue

   Returns parameter schemas, descriptions, and examples.

3. Execute the endpoint

   POST /v1/github/create_issue
   Content-Type: application/json
   
   {"params": {"repo": "acme/webapp", "title": "Bug report"}}

   Returns the upstream API response.

Example: Python agent

import httpx

SKILLETT_API_KEY = "sk_a1b2c3d4e5f6..."
BASE_URL = "https://api.skillett.dev"

headers = {"Authorization": f"Bearer {SKILLETT_API_KEY}"}

# Discover integrations
response = httpx.get(f"{BASE_URL}/v1/skills", headers=headers)
integrations = response.json()["integrations"]

# Execute a skill
response = httpx.post(
    f"{BASE_URL}/v1/github/create_issue",
    headers=headers,
    json={"params": {"repo": "acme/webapp", "title": "Bug report"}},
)
result = response.json()
print(result["data"]["html_url"])

Example: JavaScript/TypeScript agent

const API_KEY = "sk_a1b2c3d4e5f6...";
const BASE = "https://api.skillett.dev";

const headers = { Authorization: `Bearer ${API_KEY}` };

// Discover integrations
const skills = await fetch(`${BASE}/v1/skills`, { headers });
const { integrations } = await skills.json();

// Execute a skill
const result = await fetch(`${BASE}/v1/github/create_issue`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    params: { repo: "acme/webapp", title: "Bug report" },
  }),
});
const { data } = await result.json();
console.log(data.html_url);

Error handling

Always check for error responses:

const response = await fetch(`${BASE}/v1/github/create_issue`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ params }),
});

const body = await response.json();

if (body.error) {
  // Skillett-level error (auth, plan limit, not connected)
  console.error(body.message);
  if (body.action_url) {
    console.error(`Fix: ${body.action_url}`);
  }
} else if (body.status >= 400) {
  // Upstream API error (GitHub returned 404, etc.)
  console.error(body.data);
} else {
  // Success
  console.log(body.data);
}

Tip

The action_url in error responses can be surfaced to users directly — it points to the exact dashboard page needed to resolve the issue (connect integration, upgrade plan, etc.).

Connection management via API

To connect integrations programmatically:

# Start connection (returns OAuth URL)
POST /v1/connect
{"integration": "github"}

# Poll for completion
GET /v1/connect/{connectionId}

The OAuth URL must be opened in a browser — OAuth consent screens require user interaction. Your application should open this URL and poll for completion.

Rate limits

See Pricing & Limits for per-plan rate limits. When rate limited, the API returns HTTP 429 with a descriptive error message.