# 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:

```bash
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](https://docs.kaab.ist/guides/mcp) 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

```bash
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

```ts
// 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

```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

```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

```bash
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](https://docs.kaab.ist/getting-started/first-job) walks through it, and [keys and modes](https://docs.kaab.ist/getting-started/keys-and-modes) explains test and live keys.

## Call Kaabist from your code

The [SDKs](https://docs.kaab.ist/guides/sdks) for TypeScript, Python and Go, and the [`kaab` CLI](https://docs.kaab.ist/guides/cli), wrap the same API: they create jobs, wait for them while answering inputs, page through lists and verify webhook signatures.

## Go further

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