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")