Programmatic access (API)

Drive the labeling loop over HTTP — create a project and dataset, load items, bring a pipeline, run it, and export — with the beta Pipeline API, plus how to connect, the working model, and its sharp edges.

You can drive the full labeling loop over HTTP: create a project and a dataset, load items, bring a pipeline, run it, and export the results. The reference the API serves contains the endpoint schemas. To reconcile the same project from TypeScript source, use the CLI.

Before you start

You need:

Membership on a Toloka team. A key acts as your user, and access follows the teams you belong to.
An API key. You generate it yourself in the Business Console, the application the platform’s Top up and Billing history buttons open (see Manage your team and balance). Open your company there, switch to its API keys tab, and click Generate API key. The same tab lists your existing keys and deletes one.

Connect

The API is served at:

https://platform.toloka.ai/api/v2-beta

Authenticate every request with your API key in the Authorization header:

Authorization: ApiKey <your-api-key>

The endpoint reference

These two public references match the deployed version:

Browsable API reference, with every endpoint, its parameters, and its response shape in a browser.
OpenAPI 3.1 document, with the same surface as JSON for generating a client.

Your first call

List your projects to check the connection. The call needs only a key and does not modify data:

curl -H 'Authorization: ApiKey <your-api-key>' \
  https://platform.toloka.ai/api/v2-beta/projects

A working key returns your projects across your teams — an empty list if you have none. A 401 with Unauthenticated means the key or the header is wrong; see Troubleshooting.

How the API works

Uploading items, running a pipeline, and exporting results are long-running jobs. Create the job, then poll the matching GET endpoint until it reports succeeded or failed.
Post rows directly to a dataset, up to 2 MB and 10,000 rows per call. For larger data, start an upload with a format of json or csv and declare the file size, which the upload holds you to. PUT the file to the returned link, finalize, and poll. Files run up to 1024 MB.
No endpoint assembles or edits a pipeline’s nodes. Import a .pipeline file — the API can produce one from an existing pipeline — or copy a pipeline outright. Then attach a dataset and start a run. The attach call takes the same itemLimit and itemFilter as the Start node’s controls. See Start and End nodes.
No endpoint reads dataset rows. Start an export job and fetch the result from the download link it returns.
The rate limit is 60 requests per minute, per endpoint. Every response carries the standard RateLimit-* headers. Going over returns 429.

Sharp edges

After you cancel a run, GET /runs/:runId returns a failed status with the error Run canceled. Treat that as the expected cancellation outcome. Cancel works only once the run is deployed. Canceling during the deploy phase or canceling twice returns 409.
An export job that fails currently stays in running. Poll it with your own timeout rather than waiting for a terminal status; the export status field carries only running and succeeded.
Deploying through the API skips the lint gate that blocks a UI deploy when a built-in check has not run. Configuration errors and failed checks still block.
A dataset export over the API returns the dataset’s own fields, not the per-item run export documented in Export format.
State-changing requests (POST, PUT, PATCH, DELETE) must carry Content-Type: application/json and a JSON body, {} when the endpoint takes none. A request without a content type is treated as a cross-site form submission and rejected with 403 Forbidden: the request looks like a cross-site form submission. Non-browser clients must send Content-Type: application/json with a JSON body on state-changing requests.
Every response carries X-Request-Id: the value you sent when it is 1-128 characters of letters, digits, ., _ or -, otherwise a generated UUID. Error responses carry it too. Quote it when you report a problem; it is the key our logs are searched by.
The UI caps apply to the API too. A run processes at most 10,000 items. A dataset holds at most 150,000 items, and each field value can be up to 1 MiB. See labeling in batches and managing datasets.

Permissions

A team that has not completed identity or business verification is on a trial: it may hold one project and one pipeline, and it cannot start a run. All three refusals come back as 403. Trial and verification explains how to lift them.

An API key acts as the user it belongs to. Access follows that user’s team membership: a key reads and writes only in the teams its user belongs to. A key whose every team is read-only gets 403 with You do not have access to this resource on a write. Otherwise a write against a read-only or foreign team is masked as 404 <Resource> not found — naming a foreign team explicitly, as when creating a project, is the one case that answers 403. A “not found” on an id you know exists usually means the wrong team.

Troubleshooting

Match the exact text your call returns:

Response	Cause	What to do
`401` `Unauthenticated`	The key is missing or invalid.	Send `Authorization: ApiKey <your-api-key>`.
`403` `You do not have access to this resource`	The key’s user has no team with write access (a read-only key), or the call names a team the user is not on. Also returned when starting a run on a team that has not completed verification.	Use a key for a user with write access on that team. If the team is on a trial, complete verification in the web app — see Trial and verification.
`403` `Your trial allows a single project. Verify your account to unlock full access.`	The team is on an unverified trial and already holds a project.	Reuse the existing project, or complete verification to lift the limit.
`403` `Your trial allows a single pipeline. Verify your account to unlock full access.`	The team is on an unverified trial and already holds a pipeline.	Build inside the existing pipeline, or complete verification to lift the limit.
`429` `Too many requests, please try again later.`	Over 60 requests in a minute on one endpoint.	Wait `RateLimit-Reset` seconds, then retry.
`400` `Payload too large for an inline upload (max 2 MB); use the file upload endpoint for large data.`	An inline items body over 2 MB.	Switch to the upload flow: start an upload, `PUT` the file, then finalize.
`400` `Cannot deploy pipeline (<n> validation error<s>): <messages>`	The pipeline failed validation when the run tried to deploy.	Open it in the builder and fix the listed issues.
`403` `Forbidden: the request looks like a cross-site form submission. …`	A state-changing request without `Content-Type: application/json`.	Send `Content-Type: application/json` and a JSON body, `{}` if the endpoint takes none.
`400` `deliveryOrderId is required for internal teams. …`	`POST /projects` for a team that is internal, without a Sunday delivery order.	Pick an id from `GET /delivery-orders` and pass it as `deliveryOrderId`.
`400` `deliveryOrderId can only be set for internal teams.`	`POST /projects` passed a delivery order for a team that is not internal.	Omit `deliveryOrderId` for that team.

For every other message, search Errors and how to fix them.

Create and manage datasets — the data contract the API’s items and uploads follow
Label a large dataset in batches — the per-run and dataset caps the API shares
CLI — the same loop from TypeScript source
Errors and how to fix them — every customer-visible error, quoted verbatim