Get started with the API

Copy-paste recipes for the `/api/v1` base path in TypeScript (klaaro SDK), Python (klaaro SDK), and Bash (curl). Set `KLAARO_API_KEY` and `KLAARO_DATASET_ID` once, then run any recipe. For the full endpoint and schema reference, see the API reference or download the OpenAPI spec.

Environment variables

Set once per session. Python: `pip install klaaro`. TypeScript: `npm install klaaro`, then run with `npx tsx script.ts` (Node 20+).

import { KlaaroClient } from "klaaro"const klaaro = new KlaaroClient({  apiKey: process.env.KLAARO_API_KEY!,})const KLAARO_DATASET_ID = process.env.KLAARO_DATASET_ID!// const KLAARO_DOCUMENT_ID = process.env.KLAARO_DOCUMENT_ID

List datasets

Returns your team's datasets. Response includes meta.nextCursor and meta.hasMore for cursor-based pagination.

import { KlaaroClient } from "klaaro"const klaaro = new KlaaroClient({  apiKey: process.env.KLAARO_API_KEY!,})const { data, meta } = await klaaro.listDatasets()for (const ds of data) {  console.log(ds.id, ds.name)}console.log("hasMore:", meta.hasMore, "nextCursor:", meta.nextCursor)

Upload document from URL

Creates a document and starts the pipeline. Response uses camelCase (id, currentStep, etc.). Use the ingest + poll recipe to wait for extraction.

import { KlaaroClient } from "klaaro"const klaaro = new KlaaroClient({  apiKey: process.env.KLAARO_API_KEY!,})const doc = await klaaro.uploadDocument({  datasetId: process.env.KLAARO_DATASET_ID!,  url: "https://example.com/sample.pdf",})console.log("id:", doc.id, "status:", doc.status, "step:", doc.currentStep)

Upload, wait for completion, fetch extracted data

Bash requires curl and jq. Python and TypeScript use the official klaaro SDK (`pip install klaaro` / `npm install klaaro`).

import { writeFileSync } from "node:fs"import { KlaaroClient } from "klaaro"const klaaro = new KlaaroClient({  apiKey: process.env.KLAARO_API_KEY!,})const doc = await klaaro.uploadDocument({  datasetId: process.env.KLAARO_DATASET_ID!,  url: "https://example.com/sample.pdf",})const docId = doc.idconsole.log("Document id:", docId)let wrote = falsefor (let i = 1; i <= 60; i++) {  const meta = await klaaro.getDocument(docId)  console.log(`[${i}] status=${meta.status} step=${meta.currentStep}`)  if (meta.status === "completed") {    const { records } = await klaaro.getDocumentRecords(docId)    writeFileSync(`extracted-${docId}.json`, JSON.stringify(records, null, 2))    console.log(`Wrote extracted-${docId}.json`)    wrote = true    break  }  if (meta.status === "failed") throw new Error(JSON.stringify(meta, null, 2))  await new Promise((r) => setTimeout(r, 5000))}if (!wrote) throw new Error("Timed out")

Export dataset as JSON

Downloads the full dataset export in JSON format (cURL). SDK tabs paginate all records and write JSON — add class filter via list_dataset_records / listDatasetRecords params.

import { writeFileSync } from "node:fs"import { KlaaroClient } from "klaaro"const klaaro = new KlaaroClient({  apiKey: process.env.KLAARO_API_KEY!,})const datasetId = process.env.KLAARO_DATASET_ID!const records: unknown[] = []let cursor: string | undefineddo {  const page = await klaaro.listDatasetRecords(datasetId, { cursor, limit: 200 })  records.push(...page.data)  cursor = page.meta.hasMore ? (page.meta.nextCursor ?? undefined) : undefined} while (cursor)writeFileSync("dataset-export.json", JSON.stringify(records, null, 2))console.log("Wrote dataset-export.json")

Tips: API keys live under Team → API keys. Dataset and document IDs appear in the dashboard URLs and in API responses. Install SDKs with `pip install klaaro` or `npm install klaaro`. Bash polling uses `jq`. Run TypeScript snippets with `npx tsx your-script.ts` (Node 20+) after `export KLAARO_API_KEY=…` in the same shell.

import { KlaaroClient } from "klaaro"const klaaro = new KlaaroClient({ apiKey: process.env.KLAARO_API_KEY!,})const KLAARO_DATASET_ID = process.env.KLAARO_DATASET_ID!// const KLAARO_DOCUMENT_ID = process.env.KLAARO_DOCUMENT_ID

import { KlaaroClient } from "klaaro"const klaaro = new KlaaroClient({ apiKey: process.env.KLAARO_API_KEY!,})const { data, meta } = await klaaro.listDatasets()for (const ds of data) { console.log(ds.id, ds.name)}console.log("hasMore:", meta.hasMore, "nextCursor:", meta.nextCursor)

import { KlaaroClient } from "klaaro"const klaaro = new KlaaroClient({ apiKey: process.env.KLAARO_API_KEY!,})const doc = await klaaro.uploadDocument({ datasetId: process.env.KLAARO_DATASET_ID!, url: "https://example.com/sample.pdf",})console.log("id:", doc.id, "status:", doc.status, "step:", doc.currentStep)

import { writeFileSync } from "node:fs"import { KlaaroClient } from "klaaro"const klaaro = new KlaaroClient({ apiKey: process.env.KLAARO_API_KEY!,})const doc = await klaaro.uploadDocument({ datasetId: process.env.KLAARO_DATASET_ID!, url: "https://example.com/sample.pdf",})const docId = doc.idconsole.log("Document id:", docId)let wrote = falsefor (let i = 1; i <= 60; i++) { const meta = await klaaro.getDocument(docId) console.log(`[${i}] status=${meta.status} step=${meta.currentStep}`) if (meta.status === "completed") { const { records } = await klaaro.getDocumentRecords(docId) writeFileSync(`extracted-${docId}.json`, JSON.stringify(records, null, 2)) console.log(`Wrote extracted-${docId}.json`) wrote = true break } if (meta.status === "failed") throw new Error(JSON.stringify(meta, null, 2)) await new Promise((r) => setTimeout(r, 5000))}if (!wrote) throw new Error("Timed out")

import { writeFileSync } from "node:fs"import { KlaaroClient } from "klaaro"const klaaro = new KlaaroClient({ apiKey: process.env.KLAARO_API_KEY!,})const datasetId = process.env.KLAARO_DATASET_ID!const records: unknown[] = []let cursor: string | undefineddo { const page = await klaaro.listDatasetRecords(datasetId, { cursor, limit: 200 }) records.push(...page.data) cursor = page.meta.hasMore ? (page.meta.nextCursor ?? undefined) : undefined} while (cursor)writeFileSync("dataset-export.json", JSON.stringify(records, null, 2))console.log("Wrote dataset-export.json")