Docs
API 1.40
Status

Kaabist documentation

Kaabist runs versioned web automation programs as an API, with typed results, human-in-the-loop parking, self-healing locators and side-effect safety.

Kaabist is a web automation API: you describe what to do on a website as a versioned program, and every run of it is a job that returns typed data in one envelope. When a site moves an element, asks for a one-time code or puts a dialog in the way, the job heals, parks for a person or dismisses the obstacle instead of returning a wrong answer.

#Connect your coding agent

Kaabist's hosted MCP server lets Claude Code, Codex, Cursor or any MCP client open a real Kaabist browser, try extracts on the live page and turn what it did into a program you review. In Claude Code:

claude mcp add --transport http kaab https://mcp.kaab.ist/mcp

The first connection opens a consent page where you choose the organisation, test or live mode and what the agent may do. The coding agents guide has the settings for Codex and Cursor, the scopes and the tools.

#Run your first job

One request with a test key (sk_test_) reads a product page and waits for the result:

curl
response=$(curl -sS --fail-with-body "${KAAB_BASE_URL:-https://api.kaab.ist/v1}/jobs" \
  -H "Authorization: Bearer $KAAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=30" \
  -d '{
    "url": "'"${SITE_URL:-https://shop.example.com}"'/p/1",
    "extract": {
      "title": "h1",
      "price": { "selector": ".price", "type": "money", "locale": "tr", "currency": "TRY" }
    }
  }')
echo "$response"
TypeScript
// One call: create the job and hold the request up to 30 s for its result (`Prefer: wait`).
const job = await kaab.jobs.create({
  url: `${site}/p/1`,
  extract: {
    title: "h1",
    price: { selector: ".price", type: "money", locale: "tr", currency: "TRY" },
  },
  wait: 30,
});
if (job.status !== "succeeded") throw new Error(`job ${job.id} is ${job.status}`);
console.log(`${job.id}: ${JSON.stringify(job.data)}`);
Python
# One call: create the job and hold the request up to 30 s for its result (Prefer: wait).
job = kaab.jobs.create(
    url=f"{site}/p/1",
    extract={"title": "h1", "price": {"selector": ".price", "type": "money", "locale": "tr", "currency": "TRY"}},
    wait=30,
)
if job.status != "succeeded":
    raise SystemExit(f"job {job.id} is {job.status}")
print(f"{job.id}: {job.data.to_dict() if job.data else None}")
Go
// One call: create the job and hold the request up to 30 s for its result (Prefer: wait).
body, err := kaab.Body[client.CreateJobJSONBody](map[string]any{
    "url": site + "/p/1",
    "extract": map[string]any{
        "title": "h1",
        "price": map[string]any{"selector": ".price", "type": "money", "locale": "tr", "currency": "TRY"},
    },
})
if err != nil {
    log.Fatal(err)
}
job, err := c.Jobs.Create(ctx, body, kaab.WithWait(30))
if err != nil {
    log.Fatal(err)
}
if job.Status != "succeeded" {
    log.Fatalf("job %s is %s", job.ID, job.Status)
}
fmt.Printf("%s: %v\n", job.ID, *job.Data)
CLI
data=$(kaab jobs run \
  --url "${SITE_URL:-https://shop.example.com}/p/1" \
  --extract '{"title": "h1", "price": {"selector": ".price", "type": "money", "locale": "tr", "currency": "TRY"}}' \
  --wait 30)
echo "$data"

The answer is the job's envelope: its status, the typed data and what it cost. Your first job walks through it, and keys and modes explains test and live keys.

#Call Kaabist from your code

The SDKs for TypeScript, Python and Go, and the kaab CLI, wrap the same API: they create jobs, wait for them while answering inputs, page through lists and verify webhook signatures.

#Go further

  • Concepts: programs and versions, tiers, sessions, parking and resuming, healing, obstacles, validation, credits, limits and what Kaabist stores.
  • Documents and PDFs: the security gate every PDF passes, and the read_pdf step that returns a PDF's tables as data.
  • Guides: authenticated flows, hosted resolve pages, lists and pagination, schedules, webhooks, testing and side-effect safety.
  • The panel: the builder, picking and recording, and taking over a parked job.
  • Reference: every API operation, every DSL action and condition, the closed sets of codes, webhook events, CLI commands and plans.
  • Changelog: what changed in the API, the SDKs and the CLI.

Was this page helpful?