> ## 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.

# SDK quickstart

> Create a script that authenticates, adds dataset rows, and exports them.

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](https://docs.platform.toloka.ai/docs/api-reference.md#before-you-start), then create a local project:

```sh theme={null}
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:

```dotenv .env theme={null}
TOLOKA_API_KEY=your-api-key
TOLOKA_BASE_URL=https://platform.toloka.ai
```

## 2. Create a client

Save this as `client.ts`. [`createClient()`](https://docs.platform.toloka.ai/docs/sdk/reference/create-client) takes explicit configuration; this module reads the environment variables for it.

```ts client.ts theme={null}
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](https://docs.platform.toloka.ai/docs/sdk/client.md) 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()`](https://docs.platform.toloka.ai/docs/sdk/reference/account/me) and iterate through projects with [`projects.listAll()`](https://docs.platform.toloka.ai/docs/sdk/reference/projects/list):

```ts main.ts theme={null}
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:

```sh theme={null}
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](https://docs.platform.toloka.ai/docs/core/projects.md#create-or-select-a-project) first.

## 4. Create fields and append rows

Append this code to `main.ts`. It [creates a dataset](https://docs.platform.toloka.ai/docs/sdk/reference/datasets/create.md), [defines its fields](https://docs.platform.toloka.ai/docs/sdk/reference/datasets/create-field.md), and [appends two rows](https://docs.platform.toloka.ai/docs/sdk/reference/datasets/append-items.md):

```ts theme={null}
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](https://docs.platform.toloka.ai/docs/api-reference/dataset-uploads/create-dataset-upload.md) for larger files.

## 5. Export and read the download link

Append this code to the same script to [start an export](https://docs.platform.toloka.ai/docs/sdk/reference/datasets/start-export.md) and poll for completion with [`waitFor()`](https://docs.platform.toloka.ai/docs/sdk/reference/wait-for):

```ts theme={null}
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](https://docs.platform.toloka.ai/docs/sdk/long-running-jobs.md) and [errors](https://docs.platform.toloka.ai/docs/sdk/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.