Webskillet

Base URL: https://webskillet.ai

Pass your API key in the x-api-key header.

Start a run

POST /api/v1/runs/start

Starts a new run and returns immediately. Poll Get a run for the result.

Request body

Field	Type	Required	Description
`task`	string	✓	Natural-language instruction describing the task
`startUrl`	string		Where the agent should start; omit to let it decide
`parameters`	object		Structured inputs that vary between runs (for example, `{ "batch": "S24" }`)
`outputSchema`	object		JSON Schema (draft 2020-12) for the desired result shape; omit to let the agent infer one
`skilletId`	string		Reuse a saved skillet's code and knowledge instead of starting fresh
`model`	string		Agent model: `gpt-5.6-luna`, `haiku`, `sonnet`, or `opus`; defaults to `gpt-5.6-luna`
`proxy`	string		Proxy URL for the run
`auth`	string		ID of a recorded authentication session

{
  "task": "Extract the title and URL of the top story",
  "startUrl": "https://news.ycombinator.com",
  "outputSchema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "url": { "type": "string" }
    }
  },
  "model": "haiku",
  "skilletId": "hacker-news-top-story"
}

skilletId is optional. Reuse the same ID to run against the saved automation.

Response

{
  "id": "ru_7Km2pQr9Vx4Nz8Lc1Hd6B",
  "status": "pending"
}

Get a run

GET /api/v1/runs/{id}

Inline results are returned directly under result.

{
  "id": "ru_7Km2pQr9Vx4Nz8Lc1Hd6B",
  "status": "completed",
  "outcome": "success",
  "createdAt": "2026-07-13T08:14:22.417Z",
  "startedAt": "2026-07-13T08:14:24.031Z",
  "completedAt": "2026-07-13T08:14:48.692Z",
  "skillet": {
    "id": "hacker-news-top-story",
    "used": false,
    "created": true,
    "updated": false,
    "revisionId": "ru_7Km2pQr9Vx4Nz8Lc1Hd6B",
    "revisionTimestamp": "2026-07-13T08:14:48.692Z",
    "variantPrompt": "Extract the newest story instead",
    "variantSummary": "Try the newest story"
  },
  "result": {
    "title": "Show HN: Example project",
    "url": "https://example.com/project"
  }
}

Status values

Status	Description
`pending`	Run is queued, not yet executing
`started`	Agent is actively working
`completed`	Run has finished — check `outcome`
`canceled`	Run was canceled before it finished

Completed runs carry an outcome of success or failed. Failed runs never leave the referenced skillet in a worse state than before the run.

When Webskillet creates a skillet and suggests a related follow-up task, the optional skillet.variantPrompt and skillet.variantSummary fields describe that variant.

Result delivery

Inline output is returned directly under result. When an output is too large to inline, result contains a file descriptor with a signed, time-limited download URL:

"result": {
  "type": "file",
  "file": {
    "url": "https://files.webskillet.io/results/run_abc123.json?signature=...",
    "contentType": "application/json",
    "sizeBytes": 204800,
    "expiresAt": "2024-01-08T00:00:00Z"
  }
}

Failed runs

{
  "id": "run_abc123",
  "status": "completed",
  "outcome": "failed",
  "error": {
    "code": "rejected",
    "message": "Could not open the page. The website may be down."
  },
  "skillet": {
    "id": "skl_abc123",
    "used": true,
    "created": false,
    "updated": false
  }
}

Possible error.code values: workspace-rate-limited, unauthenticated, no-ai-credits-left, timeout, rejected, and internal-error.

Cost

Completed runs include cost metrics:

Field	Description
`cost.aiUsd`	AI/model cost in dollars
`cost.compute.amount`	Compute usage, in `cost.compute.unit` (hours)

List runs

GET /api/v1/runs?limit=100&offset=0

Returns an array using the same run shape as the detail endpoint, newest first.

Query param	Type	Description
`limit`	number	Max number of runs to return
`offset`	number	Number of runs to skip

Update a run

PATCH /api/v1/runs/{id}

Updates run metadata and returns the full run using the same shape as Get a run.

{
  "title": "Hacker News top story"
}

List skillets

GET /api/v1/skillets

[
  {
    "id": "hacker-news-top-story",
    "revisionId": "ru_7Km2pQr9Vx4Nz8Lc1Hd6B",
    "revisionTimestamp": "2026-07-13T08:14:48.692Z"
  }
]

revisionId is null for a seeded skillet that has not produced a run revision yet.

Skillets

A skillet is the saved automation behind one or more runs—generated code, learned knowledge about the site, and run notes—addressed by skilletId.

Pass skilletId when starting a run to reuse a skillet's saved code. A successful run updates the skillet with anything new it learned; a failed run leaves it untouched.
Omit skilletId and Webskillet creates a new skillet automatically, returning its ID as skillet.id in the result.
Use the same skilletId for the same reusable automation, even when startUrl or parameters vary. Use a different ID for a genuinely different task.
Runs that share a skilletId execute one at a time. Runs with different skillet IDs, or without one, can run in parallel.

List authentication sessions

GET /api/v1/authsessions

Returns an array of ready authentication sessions.

Get an authentication session

GET /api/v1/authsessions/{id}

The response includes startUrl, finishUrl, createdAt, and updatedAt in camel case.

Record an authentication session

POST /api/v1/authsessions/record

{
  "name": "GitHub account",
  "startUrl": "https://github.com/login"
}

{
  "url": "https://webskillet.ai/recorder/rs_9Tf4Wm7Qp2Lx8Nc5Jv1Kr",
  "recordingSessionId": "rs_9Tf4Wm7Qp2Lx8Nc5Jv1Kr"
}

API reference