Webskillet

Webskillet provides typed clients for TypeScript and Python. Both clients can start a run, wait for its result, and manage runs and skillets.

You need a Webskillet API key. Copy yours from the Webskillet app sidebar and store it in the WEBSKILLET_API_KEY environment variable.

Install

npm install webskillet

The Python SDK requires Python 3.10 or later.

Run a task

Create a client and call runs.run() to start a run and wait for its result.

import { WebskilletClient } from "webskillet/client-sdk";

const client = new WebskilletClient({
  apiKey: process.env.WEBSKILLET_API_KEY!,
});

const run = await client.runs.run(
  {
    task: "Extract the title of the page",
    startUrl: "https://example.com",
    skilletId: "example-title",
  },
  { timeoutMs: 10 * 60_000 },
);

if (run.status === "completed") {
  console.log(run.result);
}

runs.run() polls every five seconds until the run is completed or canceled. It waits indefinitely unless you provide a timeout. A canceled run is returned to the caller; a run that completes with a failed outcome raises a language-specific run failure error.

Behavior	TypeScript	Python
Poll interval	`pollIntervalMs`	`poll_interval_seconds`
Overall deadline	`timeoutMs`	`timeout_seconds`
Deadline error	`WebskilletTimeoutError`	`TimeoutError`
Failed run error	`WebskilletRunFailedError`	`RunFailedError`

Manage runs directly

Use the individual run methods when you need fire-and-forget behavior or custom polling.

Operation	TypeScript	Python
Start a run	`client.runs.start(input)`	`client.runs.start(body=input)`
Get a run	`client.runs.get(runId)`	`client.runs.get(run_id=run_id)`
Update its title	`client.runs.update(runId, { title })`	`client.runs.update(run_id=run_id, body={"title": title})`
List recent runs	`client.runs.list({ limit, offset })`	`client.runs.list(limit=limit, offset=offset)`

The input fields and returned run states match the HTTP API reference. TypeScript uses the API's camel-case field names. Python accepts snake-case field names or their camel-case API aliases; model attributes use snake case.

Manage skillets

List the skillets available to your workspace.

const skillets = await client.skillets.list();

Authentication sessions (experimental)

Experimental: Authentication sessions may change without notice while this feature is in development.

Authentication sessions let a run access a website that requires login. You can list recorded sessions, retrieve one by ID, or start a new recording.

const sessions = await client.authSessions.list();
const session = await client.authSessions.get(sessions[0].id);
const recording = await client.authSessions.record({
  name: "GitHub",
  startUrl: "https://github.com/login",
});

Use the async Python client

AsyncWebskilletClient provides the same services and arguments as the synchronous Python client.

import os

from webskillet_client import AsyncWebskilletClient

async with AsyncWebskilletClient(
    api_key=os.environ["WEBSKILLET_API_KEY"],
) as client:
    run = await client.runs.run(
        body={"task": "Extract the title of the page"},
        timeout_seconds=600,
    )

Handle errors

All SDK errors inherit from a common base error. Catch the specific errors when your application needs different recovery behavior.

import {
  WebskilletError,
  WebskilletRunFailedError,
  WebskilletTimeoutError,
} from "webskillet/client-sdk";

try {
  const run = await client.runs.run({ task: "Extract the page title" });
  console.log(run.status);
} catch (error) {
  if (error instanceof WebskilletRunFailedError) {
    console.error(error.runId, error.runError);
  } else if (error instanceof WebskilletTimeoutError) {
    console.error(error.runId, error.lastStatus);
  } else if (error instanceof WebskilletError) {
    console.error(error.message);
  }
}

TypeScript also exports WebskilletApiError and WebskilletAuthError. Python exports AuthenticationError, NotFoundError, ValidationError, ServerError, and NetworkError; API errors include the response status_code and body.

Configure the client

TypeScript accepts a baseUrl override as the second constructor argument. It also supports an asynchronous access-token callback when API-key authentication is not appropriate.

const client = new WebskilletClient(
  { apiKey: process.env.WEBSKILLET_API_KEY! },
  { baseUrl: "https://webskillet.ai" },
);

Python accepts base_url, a per-request timeout in seconds, and an optional preconfigured httpx.Client or httpx.AsyncClient.

client = WebskilletClient(
    api_key=os.environ["WEBSKILLET_API_KEY"],
    base_url="https://webskillet.ai",
    timeout=30.0,
)

SDKs