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

# client.datasets.createField()

> Create dataset fields.

Send a field name and JSON Schema, or a `fields` array for several fields. Returns the created field or fields. Names and schemas cannot be changed through this API.

## Signature

Method signatures on `client.datasets`:

```ts theme={null}
createField(args: {
  datasetId: string;
  name: string;
  jsonSchema: JsonSchema;
}): Promise<DatasetField>;

createFields(args: {
  datasetId: string;
  fields: { name: string; jsonSchema: JsonSchema }[];
}): Promise<DatasetField[]>;
```

## Parameters

### createField()

**datasetId** `string` *required*

Dataset ID with prefix `ds.`.

**name** `string` *required*

Name of the new dataset field.

**jsonSchema** `JsonSchema` *required*

JSON Schema that values in the new field must satisfy.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-field.md) for the supported JSON Schema fields.

### createFields()

**datasetId** `string` *required*

Dataset ID with prefix `ds.`.

**fields** `\{ name: string; jsonSchema: JsonSchema \}[]` *required*

Dataset fields to create, with unique names and their JSON Schemas.

**Fields**

**name** `string` *required*

Name of the new dataset field.

**jsonSchema** `JsonSchema` *required*

JSON Schema that values in the new field must satisfy.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-field.md) for the supported JSON Schema fields.

## Returns

### createField() result

`Promise<DatasetField>`

A field of a dataset.

**id** `DatasetFieldId` *required*

Dataset field ID with prefix `df.`.

**name** `string` *required*

Name of the dataset field.

**description** `string | null` *required*

Description of the field, or null when none is set.

**jsonSchema** `JsonSchema` *required*

JSON Schema that values in this field must satisfy.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-field.md) for the supported JSON Schema fields.

**internal** `boolean` *required*

True when this field is excluded from pipeline input bindings. The field is still included in dataset field responses.

**split** `object | null` *required*

Set when this is a split field: each row's value names its part.

**Fields**

**parts** `object[]` *required*

The parts, with their roles: trainings learn on train parts and validate on validate parts. Test parts are held out for evaluations: no training learns on them, and only a training on this field validates on a part that has both the validate and test roles.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-field.md) for the complete schema.

**recipe** `object | null` *required*

How the next fill samples parts; null for an adopted field until a fill gives it shares.

**Fields**

**shares** `object[]` *required*

Target proportion of rows for each split part.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-field.md) for the complete schema.

**balanceByFieldId** `string | null` *required*

Field ID with prefix `df.` used to balance labels, or null when balancing is disabled.

**seed** `number` *required*

Seed used to make the part assignments repeatable.

**status** `"filling" | "ready" | "failed"` *required*

A slice cannot be taken while the field is filling.

**progress** `object | null` *required*

Rows placed so far while the field is filling.

**Fields**

**placed** `number` *required*

Number of previously unassigned rows placed so far.

**total** `number` *required*

Number of rows to place in this fill.

**lastFill** `object | null` *required*

The last fill: rows it placed, rows that already had a part, and the rows each part held after it.

**Fields**

**placed** `number` *required*

Number of previously unassigned rows placed by the last fill.

**kept** `number` *required*

Number of rows whose existing part assignments were kept.

**parts** `object` *required*

Row counts for each part after the last fill, keyed by part name.

**error** `object | null` *required*

Why the last fill failed.

**Fields**

**code** `"too_many_labels" | "slice_failed"` *required*

Machine-readable reason the split fill failed.

**message** `string` *required*

Explanation of the split fill failure.

**operations** `DatasetFieldOperation[]` *required*

Operations currently writing to this field. A split or slice that reads the field is rejected while a blocking operation runs.

**type: "copy"**

**type** `"copy"` *required*

Operation kind: `copy` copies field values, `split_fill` assigns split parts, and `write` writes new field revisions.

**sourceFieldId** `DatasetFieldId` *required*

The field the values are copied from.

**blocking** `boolean` *required*

True when splits and slices that read this field must wait for the operation to finish.

**type: "split\_fill"**

**type** `"split_fill"` *required*

Operation kind: `copy` copies field values, `split_fill` assigns split parts, and `write` writes new field revisions.

**blocking** `boolean` *required*

True when splits and slices that read this field must wait for the operation to finish.

**type: "write"**

**type** `"write"` *required*

Operation kind: `copy` copies field values, `split_fill` assigns split parts, and `write` writes new field revisions.

**writer** `string` *required*

The source of the new field revisions. For a batch inference run, this is `batch-inference-run:<id>`.

**progress** `object | null` *required*

The number of rows written and the total number expected, when known.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-field.md) for the complete schema.

**blocking** `boolean` *required*

True when splits and slices that read this field must wait for the operation to finish.

**createdAt** `string` *required*

Time the field was created, as an ISO 8601 timestamp.

### createFields() result

`Promise<DatasetField[]>`

Dataset fields created by this request.

Returns an array. Each item has these fields:

**id** `DatasetFieldId` *required*

Dataset field ID with prefix `df.`.

**name** `string` *required*

Name of the dataset field.

**description** `string | null` *required*

Description of the field, or null when none is set.

**jsonSchema** `JsonSchema` *required*

JSON Schema that values in this field must satisfy.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-field.md) for the supported JSON Schema fields.

**internal** `boolean` *required*

True when this field is excluded from pipeline input bindings. The field is still included in dataset field responses.

**split** `object | null` *required*

Set when this is a split field: each row's value names its part.

**Fields**

**parts** `object[]` *required*

The parts, with their roles: trainings learn on train parts and validate on validate parts. Test parts are held out for evaluations: no training learns on them, and only a training on this field validates on a part that has both the validate and test roles.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-field.md) for the complete schema.

**recipe** `object | null` *required*

How the next fill samples parts; null for an adopted field until a fill gives it shares.

**Fields**

**shares** `object[]` *required*

Target proportion of rows for each split part.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-field.md) for the complete schema.

**balanceByFieldId** `string | null` *required*

Field ID with prefix `df.` used to balance labels, or null when balancing is disabled.

**seed** `number` *required*

Seed used to make the part assignments repeatable.

**status** `"filling" | "ready" | "failed"` *required*

A slice cannot be taken while the field is filling.

**progress** `object | null` *required*

Rows placed so far while the field is filling.

**Fields**

**placed** `number` *required*

Number of previously unassigned rows placed so far.

**total** `number` *required*

Number of rows to place in this fill.

**lastFill** `object | null` *required*

The last fill: rows it placed, rows that already had a part, and the rows each part held after it.

**Fields**

**placed** `number` *required*

Number of previously unassigned rows placed by the last fill.

**kept** `number` *required*

Number of rows whose existing part assignments were kept.

**parts** `object` *required*

Row counts for each part after the last fill, keyed by part name.

**error** `object | null` *required*

Why the last fill failed.

**Fields**

**code** `"too_many_labels" | "slice_failed"` *required*

Machine-readable reason the split fill failed.

**message** `string` *required*

Explanation of the split fill failure.

**operations** `DatasetFieldOperation[]` *required*

Operations currently writing to this field. A split or slice that reads the field is rejected while a blocking operation runs.

**type: "copy"**

**type** `"copy"` *required*

Operation kind: `copy` copies field values, `split_fill` assigns split parts, and `write` writes new field revisions.

**sourceFieldId** `DatasetFieldId` *required*

The field the values are copied from.

**blocking** `boolean` *required*

True when splits and slices that read this field must wait for the operation to finish.

**type: "split\_fill"**

**type** `"split_fill"` *required*

Operation kind: `copy` copies field values, `split_fill` assigns split parts, and `write` writes new field revisions.

**blocking** `boolean` *required*

True when splits and slices that read this field must wait for the operation to finish.

**type: "write"**

**type** `"write"` *required*

Operation kind: `copy` copies field values, `split_fill` assigns split parts, and `write` writes new field revisions.

**writer** `string` *required*

The source of the new field revisions. For a batch inference run, this is `batch-inference-run:<id>`.

**progress** `object | null` *required*

The number of rows written and the total number expected, when known.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-field.md) for the complete schema.

**blocking** `boolean` *required*

True when splits and slices that read this field must wait for the operation to finish.

**createdAt** `string` *required*

Time the field was created, as an ISO 8601 timestamp.

## Errors

HTTP errors throw [`PotatoApiError`](https://docs.platform.toloka.ai/docs/sdk/errors). The endpoint documents these error responses:

| Status | Description |
| - | - |
| 404 | Dataset not found |
| 429 | Rate limit exceeded |

HTTP endpoint: [`POST /datasets/{datasetId}/fields`](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-field).

```ts createField() theme={null}
import { createClient } from "@toloka-platform/sdk";

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

const field = await client.datasets.createField({
  datasetId: "ds.019a0000-0000-7000-8000-000000000001",
  name: "text",
  jsonSchema: {
    type: "string"
  }
});
console.log(field);
```

```ts createFields() theme={null}
import { createClient } from "@toloka-platform/sdk";

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

const fields = await client.datasets.createFields({
  datasetId: "ds.019a0000-0000-7000-8000-000000000001",
  fields: [
    {
      name: "text",
      jsonSchema: {
        type: "string"
      }
    },
    {
      name: "label",
      jsonSchema: {
        type: "string"
      }
    }
  ]
});
console.log(fields);
```

```json createField() theme={null}
{
  "id": "df.019a0000-0000-7000-8000-000000000001",
  "name": "<string>",
  "description": null,
  "jsonSchema": {},
  "internal": false,
  "split": null,
  "operations": [
    {
      "type": "copy",
      "sourceFieldId": "df.019a0000-0000-7000-8000-000000000001",
      "blocking": false
    }
  ],
  "createdAt": "2026-01-01T00:00:00Z"
}
```

```json createFields() theme={null}
[
  {
    "id": "df.019a0000-0000-7000-8000-000000000001",
    "name": "<string>",
    "description": null,
    "jsonSchema": {},
    "internal": false,
    "split": null,
    "operations": [
      {
        "type": "copy",
        "sourceFieldId": "df.019a0000-0000-7000-8000-000000000001",
        "blocking": false
      }
    ],
    "createdAt": "2026-01-01T00:00:00Z"
  }
]
```


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