> ## Documentation Index > Fetch the complete documentation index at: https://docs.platform.toloka.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # HTTP API > Authenticate once and use the beta HTTP API for shared projects and datasets, Data Labeling pipelines, and Train resources. The beta HTTP API covers shared projects and datasets, Data Labeling pipelines, and Train. Authenticate once, then use the same project IDs and team permissions across both products. The [typed endpoint reference](#the-endpoint-reference) is the canonical inventory of paths, parameters, and response shapes. > [!NOTE] > > The API is in beta: its request and response shapes can change without a backward-compatibility promise. Expect to revisit your integration as the platform changes. ## Before you start You need: * Access to a team in the Toloka platform. * 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](https://docs.platform.toloka.ai/docs/core/teams-and-balance.md#top-up)). 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 ``` Endpoint paths in the API reference are relative to this base URL. Authenticate every request with your API key in the `Authorization` header: ``` Authorization: ApiKey ``` ## The endpoint reference * [API reference](https://docs.platform.toloka.ai/docs/api-reference/account/get-current-user.md), with public endpoints, parameters, response shapes, and TypeScript SDK examples. * [OpenAPI 3.1 document](https://platform.toloka.ai/api/v2-beta/doc), served by the deployed API as JSON for generating a client. Use the [TypeScript SDK](https://docs.platform.toloka.ai/docs/sdk.md) as a typed client for these endpoints. ## 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 ' \ 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](#troubleshooting). ## Data Labeling The Data Labeling API can create projects and datasets, load items, import or copy pipelines, start pipeline runs, and export results: * 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`, `jsonl`, or `csv` and declare the file size, which the upload holds you to. JSON is an array of row objects; JSONL is one row object per nonempty line. `PUT` the file to the returned link, finalize, and poll. Files run up to 1024 MB. * Read or replace a pipeline's nodes and connections through its graph endpoints, import a `.pipeline` file, or copy a pipeline. 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](https://docs.platform.toloka.ai/docs/data/reference/nodes/start-and-end.md). * List item IDs and indexes with `GET /datasets/:datasetId/items`. To read field values, start an export job and fetch the result from its download link. ## Train * List and inspect the Base model catalog. * Split a dataset into train, validation, and test parts and freeze a dataset slice. * Create and list Trainings in a project, read or rename a Training, and replace its configuration. * Prepare cost-estimate inputs, calculate an estimate, and start or list Training Runs. * Read a Training Run, logs, current metrics, and metric history; resume or cancel when its state allows the operation. * Create, list, read, and archive Models; list Model Versions; inspect and download Model Version content. A Training configuration requires `sliceId` for a ready slice that freezes a split column. Set `splitFieldId` when the slice freezes more than one split column. Optional `trainParts` selects an array of part names with the `train` role; omitting it selects every train part. The platform derives validation rows from all parts with the `validate` role and keeps test rows out of learning. Creating a split column without specifying parts uses 80% train, 10% validation, and 10% test. If the slice supplies no validation rows, Training holds out 10% of the selected train rows. Rows added after a split have no part, so a new slice alone leaves them out of Training. To include them, send `POST /datasets/:datasetId/split` with the same `column` and no `parts`; rows that already have a part keep it. Wait until that column's split status in `GET /datasets/:datasetId/fields` is `ready`, create a slice with `POST /datasets/:datasetId/slices`, wait until `GET /slices/:sliceId` reports `ready`, then replace the Training configuration with the new `sliceId`. For changed values in frozen fields alone, the new slice is enough. See [Slices and split columns](https://docs.platform.toloka.ai/docs/train/reference/settings.md#slices-and-split-columns) for the matching CLI commands. For the resource lifecycle, see [How Training works](https://docs.platform.toloka.ai/docs/train/concepts/how-training-works.md); for the billing step, see [Training cost](https://docs.platform.toloka.ai/docs/train/concepts/cost.md). ## Shared request behavior The rate limit is 60 requests per minute per endpoint route and authenticated user. Responses processed by the rate limiter include `RateLimit-*` headers; earlier authentication or scope errors can omit them. Exceeding the limit returns `429`. 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. ## Data Labeling sharp edges After cancellation, `GET /runs/:runId` returns `failed` with the error `Run canceled`. Cancel works only once the run is deployed. Canceling during deployment, canceling twice, or canceling while the run is being finalized returns `409`. The cancel body accepts an optional `pendingHumanQa`: | Value | Result and charge | | - | - | | `wait_for_review` (default, including `{}`) | Wait for Human QA, even after the run reports `failed`. After 14 days on the node, eligible items still waiting are accepted without review and charged as completed items. | | `accept_without_review` | Accept eligible waiting items without review now and charge them as completed items. Items already rejected by LLM QA or being reviewed are not accepted by this option. | An unknown field or value returns `400`. See [Resume or cancel a run](https://docs.platform.toloka.ai/docs/data/guides/pause-resume-cancel.md#items-that-wait-for-human-qa). * Completed items return `state.output`. Canceled items can return `state.partialOutput` with the same shape, containing End-node fields that had values when cancellation occurred. This can include outputs accepted without review. It is `null` for other statuses and for canceled items where no node wrote an End-node field. * Dataset export status is `running`, `succeeded`, or `failed`. Stop polling on either terminal status. On `failed`, inspect `error` and correct the cause before creating another export. * API deploys use the same lint gate as the web app: unfinished built-in lints, configuration errors, and failed checks block the deploy. Resolve them before starting a run. * A dataset export over the API returns the dataset's own fields, not the per-item pipeline-run export documented in [Export format](https://docs.platform.toloka.ai/docs/data/reference/export-format.md). * A pipeline 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](https://docs.platform.toloka.ai/docs/data/guides/label-at-volume.md) and [managing datasets](https://docs.platform.toloka.ai/docs/core/datasets.md). ## Permissions A team that has not completed required identity or business verification can be restricted to one project and one pipeline and prevented from starting a pipeline run. These refusals return `403`. Complete the verification flow offered to the team in the web app. An API key acts as its owner and inherits that user's team permissions. Writes return: | Condition | Response | | - | - | | The user has no team with write access | `403` `You do not have access to this resource` | | The user has write access elsewhere, but the requested resource belongs to a read-only team or a team they have not joined | `404` ` not found` | | The request explicitly names a team the user cannot write to, such as during project creation | `403` `You do not have access to this resource` | If an existing resource returns `404`, check that your key belongs to the correct team. ## Shared and Data Labeling troubleshooting This table covers shared authentication and project errors plus Data Labeling pipeline and dataset errors. Train returns typed errors through the same API; interpret Training Run states with [How Training works](https://docs.platform.toloka.ai/docs/train/concepts/how-training-works.md) and use the served endpoint reference for each operation's response schema. | Response | Cause | What to do | | - | - | - | | `401` `Unauthenticated` | The key is missing or invalid. | Send `Authorization: ApiKey `. | | `403` `You do not have access to this resource` | The key's user has no team with write access, the call names a team the user is not on, or the team has not completed verification required to start a pipeline run. | Use a key for a user with write access on that team. If verification is required, complete the flow offered in the web app. | | `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 ( validation error): ` | The pipeline failed validation when the run tried to deploy. | Open it in the builder and fix the listed issues. | | `400` `Pipeline graph validation failed ( errors):` | `PUT /pipelines/:pipelineId/graph` or a pipeline import sent a graph that breaks a write-time rule. The body has one `- node , : ` line per error, up to 100, then `- …and more`. | Fix each listed node setting and send the graph again. With the CLI, `toloka check` reports the same rules as `platform-rules` warnings before you write. | | `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. | For every other Data Labeling message, search [Dataset and pipeline errors](https://docs.platform.toloka.ai/docs/data/reference/errors.md). ## Related * [Projects](https://docs.platform.toloka.ai/docs/core/projects.md) — understand the shared resource boundary * [Create and manage datasets](https://docs.platform.toloka.ai/docs/core/datasets.md) — use the row and upload contract shared by both products * [Pipeline pricing](https://docs.platform.toloka.ai/docs/data/concepts/pricing.md) — understand Data Labeling forecast and contract mechanics * [How Training works](https://docs.platform.toloka.ai/docs/train/concepts/how-training-works.md) — understand Training API resources and their lifecycle * [CLI](https://docs.platform.toloka.ai/docs/cli.md) — automate both products from a terminal This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.