Skip to content
Platform docsPlatform docsPlatform docs
Menu
Getting started
How the platform worksGet your first labeled datasetTrain your first model
Concepts
PipelinesFields and dataQuality controlSelf-checkPricing and billingTrainingSecurity and data handling
Cookbook
Start a project from a templateHave the agent build your project
How-to guides
Create and manage datasetsReview the labeling interfaceExport your labeled resultsLabel a large dataset in batchesResume or cancel a runLabel with an LLM instead of expertsManage your team and balanceTroubleshoot a runCompress a prompt with gistingFine-tune a model
Reference
Export formatErrors and how to fix them
Integrations
CLITypeScript SDKProgrammatic access (API)
Glossary
Glossary

TypeScript SDK

Define Toloka pipelines as typed TypeScript source that your team and coding agents can review and reuse.

Use @toloka-platform/sdk to define a Toloka pipeline as typed TypeScript source. Fields describe the data contract, nodes describe the work, and connections describe how data moves through the pipeline.

The SDK defines source. Use the CLI to authenticate, import an existing project, validate changes, preview a plan, and apply that source to the platform.

Install

Section titled “Install”

Use Bun as the SDK runtime and package manager. Add the SDK to every project that imports its authoring or testing entry points:

Terminal window
bun add @toloka-platform/sdk@latest

For an existing SDK project, run bun i to install its locked dependencies. latest currently resolves to stable 0.2.0; use bun add @toloka-platform/sdk@0.2.0 when the project needs a reproducible dependency.

The SDK remains a project dependency wherever source or tests import it. Install the standalone CLI separately. It includes its runtime, so CLI-only and Training workflows need neither Bun nor an SDK dependency.

Project tests can still require external tools and libraries. Python code-node tests need python3 and their imported packages; Task UI tests need Playwright and its Chromium download.

CLI updates are separate from SDK dependency updates. Rerun the installer for an immediate update; there is no toloka update command. See Updates and migration from Bun global installs for pins, PATH fixes, and migration.

Define fields and a pipeline

Section titled “Define fields and a pipeline”

Every pipeline lives in a file named pipeline.ts under pipelines/ and has a default export from definePipeline.

import { definePipeline, field, root } from "@toloka-platform/sdk";


const text = field("text", { type: "string" });
const startAndEnd = root({ started: [text], completed: [text] });


export default definePipeline({
  dataset: "example-items",
  fields: [text],
  nodes: [startAndEnd],
  connections: [],
});

dataset names the platform dataset. Each field() declares one column and its JSON Schema. The root() node defines which fields enter the pipeline and which fields must be complete when an item finishes. Unlike work-node constructors, root() has no name argument because a pipeline has exactly one boundary.

Use code, generation, quorum, and match for processing and labeling work. See Pipeline nodes for their settings and constraints.

Connect nodes

Section titled “Connect nodes”

Pass nodes to definePipeline and connect their ports with connect. TypeScript catches incompatible field wiring while you author the graph. Platform validation still runs before writes and checks constraints that depend on live project state.

Keep dataset rows, API keys, and secret values out of source. Pipeline source contains schemas, node settings, and secret names only.

Initialize agent guidance

Section titled “Initialize agent guidance”

From the project root, run:

Terminal window
toloka init

init installs the CLI’s bundled instructions for supported coding agents. It also records the selected project in toloka.json when one is available.

After updating the standalone CLI, run toloka init again so generated agent guidance matches its bundled skills. Updating only the project SDK dependency does not update the executable.

Validate and apply

Section titled “Validate and apply”

Use the CLI for the reconciliation loop:

Terminal window
toloka check
toloka validate
toloka plan
toloka apply
toloka plan

check needs no platform credentials. It runs project TypeScript, automatic Task UI typechecking, Vitest, and required typed node and pipeline-flow coverage. apply reruns the same gate before its first platform request.

A final No changes. confirms that local source and the platform agree. See CLI for command behavior, credentials, project selection, and failure handling.

Section titled “Related”