What Kaabist is

Kaabist runs automation programs against websites and returns what they found as typed JSON, through one API. It is built for the flows that break ordinary scrapers: logins with a one-time code, pages that render in JavaScript, dialogs in the way, markup that changes overnight, and steps that place an order and must never run twice.

When to use it

Use Kaabist when a program has to keep working against a site you do not control: reading a price list every hour, exporting a report from a portal behind a login, filling a form on a schedule. Reading one public page is the entry-level case and costs one request; the same API carries the twenty-step flow behind a sign-in.

Kaabist is not a crawler. It runs the steps you describe on the pages you name; it does not discover links and follow them on its own.

The model

Programs and versions

A program is a JSON document: typed inputs, ordered steps (goto, fill, click, await_input, extract and so on), an extract schema that says what data to return, and policies. Each saved change is a new program version, and a version never changes once it is published. Aliases such as latest and production point at versions, so you can publish version 4 and keep production on version 3 until you are ready. See Programs and versions.

A request that sends a URL and an extract schema instead of a program name is the same thing: it compiles to a two-step program (goto, then extract) and runs through the same engine.

Jobs

A job is one run of one program version with one set of inputs. You create it with POST /v1/jobs and read it back as one envelope whose keys depend on its status: queued, running, awaiting_input, needs_attention, succeeded, failed or canceled. See Understanding the envelope.

Tiers

Kaabist fetches a page in one of three ways, cheapest first: http (one request, no browser), browser (a real Chromium) and stealth (a hardened browser on a residential address). A job starts as low as its program allows, moves up when the page needs more, and Kaabist remembers what each site needed. See Tiers and escalation.

Parking

When a job needs a person, it parks instead of failing. A planned park is awaiting_input: an await_input step asked for a one-time code. An unplanned park is needs_attention, with a reason such as drift, obstacle or session_expired, a screenshot and, where Kaabist has one, a proposed fix. You answer with the API, from the panel, or by sending your own end user a hosted page. See Human in the loop.

Healing

Every field in a program keeps several locators and a record of what it matched when you confirmed it. When the page changes and the locator stops matching, Kaabist looks for the element that took its place. A confident match is used for that job only; a change to your program is always a proposal you approve. See Self-healing.

Side-effect safety

A step marked side_effect: true (placing an order, sending a message) runs behind a fence: Kaabist records that it is about to run before acting and that it ran after its expect holds. A step that was started and never confirmed is never run again automatically; the job parks as side_effect_ambiguous for a person to decide. See Side-effect safety.

The sites in these docs

The worked examples in these docs target fictional sites under the reserved example.com domain, each standing for one kind of real-world behaviour: a server-rendered shop (https://shop.example.com), a single-page app that draws its content from a JSON API (https://app.example.com), a login with a one-time code (https://portal.example.com) and a non-idempotent order form (https://checkout.example.com). They show the shape of each request and result; to run one, point it at a site of your own.

Worked example

The smallest useful job reads one product page of a shop:

{
  "url": "https://shop.example.com/p/1",
  "extract": {
    "title": "h1",
    "price": { "selector": ".price", "type": "money", "locale": "tr", "currency": "TRY" }
  }
}

Kaabist compiles it to a program with a goto and an extract, runs it at the http tier because nothing in it needs a browser, and answers with status: "succeeded" and:

{ "title": "Kulaklık Klasik 101", "price": { "amount": 1337.4, "currency": "TRY" } }

The price arrives as a number and a currency, not as the string 1.337,40 TL, because the field declares its type and locale. Your first job runs this request in each language.

The path through Getting started

1. API keys and modes: create an sk_test_ key, and learn the conventions every endpoint shares.
2. Your first job: install an SDK or the CLI and run the request above.
3. Understanding the envelope: what each status carries, and how each SDK waits for a job to finish.

Then read the concepts in order, or go straight to a guide for your task.

Pitfalls

• Treating a parked job as a failure. awaiting_input and needs_attention are states you can act on. A client that switches only on succeeded and failed leaves parked jobs waiting until they expire.
• Building against live keys. Use an sk_test_ key while you develop: test jobs run for real, reserve no credits, and are capped by a daily count instead.
• Expecting a guess. When a value cannot be read, Kaabist returns null with a warning, or parks, rather than returning something plausible. Read warnings[] on every succeeded job.

Reference

• Create a job
• The job object
• Job statuses and attention reasons
• The DSL reference