Reference

API reference

Every endpoint of the Kaabist API v1.38.

Unbreakable web automation API. Every job is the execution of a program; clients switch on status.

Version 1.38 of the API, served under https://api.kaab.ist/v1. Authenticate with Authorization: Bearer <key> (see keys and modes); every answer is JSON, and every error uses the error envelope.

Prefer to explore? The interactive reference renders the same OpenAPI document, which you can also download.

Jobs

Run programs and act on parked jobs

Operation	Endpoint	Scope
Create a job from a program reference or the url + extract shorthand	`POST /jobs`	run
List jobs, newest first	`GET /jobs`	read
Create up to 1000 jobs from one program	`POST /jobs/batch`	run
Estimate the credit cost of a job without enqueuing it	`POST /jobs/estimate`	read
Read the job envelope; `Prefer: wait` long-polls for a state change	`GET /jobs/{id}`	read
Per-step records with timings, snapshots and healing information	`GET /jobs/{id}/steps`	read
Redirect to a presigned snapshot JSON URL	`GET /jobs/{id}/snapshot`	read
Redirect to a presigned screenshot URL	`GET /jobs/{id}/screenshot`	read
Redirect to a presigned artifact URL	`GET /jobs/{id}/artifacts/{name}`	read
Supply the value an `await_input` step is waiting for	`POST /jobs/{id}/input`	run
Apply a proposal, skip a step, retry from a checkpoint, continue or abort	`POST /jobs/{id}/resume`	run
Open a live browser session on a parked job	`POST /jobs/{id}/takeover`	run
Cancel a job and release its reserved credits	`POST /jobs/{id}/cancel`	run

Batches

Bulk job creation

Operation	Endpoint	Scope
Read batch counters	`GET /batches/{id}`	read
List the jobs of a batch	`GET /batches/{id}/jobs`	read

Programs

Programs, versions and aliases

Operation	Endpoint	Scope
Create a program and its first version	`POST /programs`	run
List programs	`GET /programs`	read
Lint a program definition and return the normalized document	`POST /programs/lint`	read
Read a program by id or name	`GET /programs/{id}`	read
Rename a program or change its description and canary settings	`PATCH /programs/{id}`	run
Soft-delete a program	`DELETE /programs/{id}`	admin
List the versions of a program	`GET /programs/{id}/versions`	read
Add a version to a program	`POST /programs/{id}/versions`	run
Replace a draft version's definition in place; published versions are immutable	`PUT /programs/{id}/versions/{n}`	run
Delete a draft version (it is archived); published versions are immutable	`DELETE /programs/{id}/versions/{n}`	run
Read one version including its definition	`GET /programs/{id}/versions/{n}`	read
Publish a draft version and move the `latest` alias	`POST /programs/{id}/versions/{n}/publish`	run
RFC 6902 JSON Patch between two versions	`GET /programs/{id}/versions/{n}/diff`	read
Run extraction against a stored snapshot without fetching	`POST /programs/{id}/versions/{n}/replay`	run
Point an alias at a version	`PUT /programs/{id}/aliases/{alias}`	run
Remove an alias	`DELETE /programs/{id}/aliases/{alias}`	run

Sessions

Stored browser sessions

Operation	Endpoint	Scope
Store a browser storage state as a reusable session	`POST /sessions`	run
List sessions	`GET /sessions`	read
Read a session by id or name	`GET /sessions/{id}`	read
Rename a session or replace its storage state	`PATCH /sessions/{id}`	run
Delete a session	`DELETE /sessions/{id}`	run
Run the validity probe	`POST /sessions/{id}/verify`	run
Enqueue the session's refresh program	`POST /sessions/{id}/refresh`	run

Proposals

Machine-generated changes awaiting approval

Operation	Endpoint	Scope
List proposals	`GET /proposals`	read
Read a proposal	`GET /proposals/{id}`	read
Approve a proposal, optionally promoting it to a new version	`POST /proposals/{id}/approve`	run
Reject a proposal	`POST /proposals/{id}/reject`	run
Replace the proposed change before approval	`POST /proposals/{id}/edit`	run

Schedules

Cron schedules and change detection

Operation	Endpoint	Scope
Create a cron schedule for a program	`POST /schedules`	run
List schedules	`GET /schedules`	read
Read a schedule	`GET /schedules/{id}`	read
Change a schedule	`PATCH /schedules/{id}`	run
Delete a schedule	`DELETE /schedules/{id}`	run
Pause a schedule	`POST /schedules/{id}/pause`	run
Resume a paused schedule	`POST /schedules/{id}/resume`	run
List the runs of a schedule	`GET /schedules/{id}/runs`	read
Redirect to a presigned URL of a run's JSON Patch against the previous run	`GET /schedules/{id}/runs/{job_id}/diff`	read

Webhooks

Event delivery

Operation	Endpoint	Scope
Register a webhook endpoint; the secret is shown once	`POST /webhooks`	admin
List webhook endpoints	`GET /webhooks`	admin
Read a webhook endpoint	`GET /webhooks/{id}`	admin
Change a webhook endpoint	`PATCH /webhooks/{id}`	admin
Delete a webhook endpoint	`DELETE /webhooks/{id}`	admin
Rotate the signing secret	`POST /webhooks/{id}/rotate-secret`	admin
List delivery attempts	`GET /webhooks/{id}/deliveries`	admin
Resend one delivery as a new attempt row; the original is never changed	`POST /webhooks/{id}/deliveries/{delivery_id}/resend`	admin
Send a `ping` event to the endpoint and wait up to 10 s for its answer	`POST /webhooks/{id}/test`	admin

Organisation

Organisation, credits, keys and providers

Operation	Endpoint	Scope
Rotate the secret ad-hoc `webhook_url` deliveries are signed with; shown once	`POST /org/webhook-secret/rotate`	admin
Read the calling organisation	`GET /org`	read
Purge the organisation's data within 24 hours	`POST /org/data-deletion`	admin

Research

Find, read and extract sourced data from the web

Operation	Endpoint	Scope
Start a research: find pages, read them and return sourced data	`POST /research`	run
List research, newest first	`GET /research`	read
Estimate the credits a research may use without starting it	`POST /research/estimate`	read
Read a research; `Prefer: wait` long-polls, `?format=md` or `Accept: text/markdown` renders it	`GET /research/{id}`	read
Cancel a research; it finishes with the data it has and releases the rest	`POST /research/{id}/cancel`	run

Search

Web search, as a research of kind search

Operation	Endpoint	Scope
Search the web: a research of kind `search`, waiting 30 s unless `Prefer` says	`POST /search`	run

Credits

Operation	Endpoint	Scope
Read credit balance and pools	`GET /credits`	read

Ledger

Operation	Endpoint	Scope
List ledger entries	`GET /ledger`	read

Usage

Operation	Endpoint	Scope
Aggregated usage over a period	`GET /usage`	read

API keys

Operation	Endpoint	Scope
List API keys	`GET /api-keys`	admin
Create an API key; the secret is shown once	`POST /api-keys`	admin
Rotate an API key with an optional grace period	`POST /api-keys/{id}/rotate`	admin
Revoke an API key	`DELETE /api-keys/{id}`	admin

BYO providers

Operation	Endpoint	Scope
List bring-your-own providers	`GET /byo-providers`	admin
Register a bring-your-own provider	`POST /byo-providers`	admin
Read a bring-your-own provider	`GET /byo-providers/{id}`	admin
Change a bring-your-own provider	`PATCH /byo-providers/{id}`	admin
Delete a bring-your-own provider	`DELETE /byo-providers/{id}`	admin
Health-check a bring-your-own provider	`POST /byo-providers/{id}/test`	admin

Sites

Operation	Endpoint	Scope
Read the learned site profile visible to the organisation	`GET /sites/{hostname}`	read

Objects

Object	Description
ApiKey
Batch
ByoProvider
Credits
ErrorResponse
ExtractSchema	A Kaabist extract schema. Full grammar: https://kaab.ist/schemas/program-1.json
Job
LedgerEntry
LintResult
Org
Program
ProgramDefinition	A Kaabist program definition. Full grammar: https://kaab.ist/schemas/program-1.json
ProgramVersion
Proposal
Research
Schedule
Session
SiteProfile
StepRecord
Webhook
WebhookDelivery
WebhookEvent

Was this page helpful?

Overview

Generated references for the API, the program DSL, codes, events, the CLI, the SDKs and plans.

Interactive reference

Browse the OpenAPI document of the Kaabist API with Scalar.