SDK quickstart

Use Bun 1.4.0 or newer and a platform account with write access to a project. This walkthrough creates a dataset and adds two rows each time you run the finished script.

1. Get a key and install

Generate an API key, then create a local project:

mkdir toloka-sdk-example
cd toloka-sdk-example
bun init -y
bun add @toloka-platform/sdk@latest

Set TOLOKA_API_KEY through your shell or secret manager. You can also put it in a local .env file, which Bun loads. Keep that file out of version control:

.env

TOLOKA_API_KEY=your-api-key
TOLOKA_BASE_URL=https://platform.toloka.ai

2. Create a client

Save this as client.ts. createClient() takes explicit configuration; this module reads the environment variables for it.

client.ts

import { createClient } from "@toloka-platform/sdk";

const apiKey = process.env.TOLOKA_API_KEY;
if (!apiKey) throw new Error("Set TOLOKA_API_KEY");

export const client = createClient({
  baseUrl: process.env.TOLOKA_BASE_URL ?? "https://platform.toloka.ai",
  apiKey,
});

Use the platform origin for baseUrl; the SDK adds /api/v2-beta to requests. See client configuration for other credentials and custom fetch functions.

3. Check your identity and projects

Save this as main.ts to read your identity with client.me() and iterate through projects with projects.listAll():

main.ts

import { client } from "./client";

const me = await client.me();
console.log(me.id, me.email);

for await (const project of client.projects.listAll()) {
  console.log(project.id, project.name);
}

Run it:

bun run main.ts

Pick a project you can write to and add its ID to .env as TOLOKA_PROJECT_ID. If the list is empty, create a project first.

4. Create fields and append rows

Append this code to main.ts. It creates a dataset, defines its fields, and appends two rows:

const projectId = process.env.TOLOKA_PROJECT_ID;
if (!projectId) throw new Error("Set TOLOKA_PROJECT_ID");

const dataset = await client.datasets.create({
  projectId,
  name: "sdk-example",
});

const fields = [
  { name: "text", jsonSchema: { type: "string" as const } },
  { name: "label", jsonSchema: { type: "string" as const } },
];

await client.datasets.createFields({ datasetId: dataset.id, fields });

const appended = await client.datasets.appendItems({
  datasetId: dataset.id,
  fields,
  items: [
    { text: "The delivery arrived early.", label: "positive" },
    { text: "The package was damaged.", label: "negative" },
  ],
});

console.log("Rows added:", appended.created);

Pass fields on the append call to map each row’s keys into those fields. Omitting it stores each whole row under uploaded, even if other fields already exist. Inline appends accept up to 10,000 rows and a 2 MiB request body; use the dataset upload flow for larger files.

5. Export and read the download link

Append this code to the same script to start an export and poll for completion with waitFor():

const started = await client.datasets.startExport({
  datasetId: dataset.id,
  fields: ["text", "label"],
  format: "json-array",
});

const completed = await client.waitFor(
  { type: "datasetExport", exportId: started.id },
  { timeoutMs: 120_000, intervalMs: 2_000 },
);

if (completed.status === "failed") {
  throw new Error(completed.error?.message ?? "Export failed");
}

const downloadUrl = completed.result.downloadUrl;
if (!downloadUrl) throw new Error("The export has no download link");

console.log("Download link:", downloadUrl);

Run bun run main.ts again to execute the complete workflow. The download contains a JSON array with the selected dataset fields. For timeout and failure handling, see long-running jobs and errors.

TypeScript SDK

Pipelines as code

CLI

1. Get a key and install

2. Create a client

3. Check your identity and projects

4. Create fields and append rows

5. Export and read the download link

​1. Get a key and install

​2. Create a client

​3. Check your identity and projects

​4. Create fields and append rows

​5. Export and read the download link

1. Get a key and install

2. Create a client

3. Check your identity and projects

4. Create fields and append rows

5. Export and read the download link