client.datasets.createField()

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);

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);

{
  "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"
}

[
  {
    "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"
  }
]

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);

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);

{
  "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"
}

[
  {
    "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"
  }
]

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:

createField(args: {
  datasetId: string;
  name: string;
  jsonSchema: JsonSchema;
}): Promise<DatasetField>;

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

Parameters

createField()

string

required

Dataset ID with prefix ds..

string

required

Name of the new dataset field.

JsonSchema

required

JSON Schema that values in the new field must satisfy.See the HTTP endpoint for the supported JSON Schema fields.

createFields()

string

required

Dataset ID with prefix ds..

{ name: string; jsonSchema: JsonSchema }[]

required

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

Show Fields

string

required

Name of the new dataset field.

JsonSchema

required

JSON Schema that values in the new field must satisfy.See the HTTP endpoint for the supported JSON Schema fields.

Returns

createField() result

Promise<DatasetField> A field of a dataset.

DatasetFieldId

required

Dataset field ID with prefix df..

string

required

Name of the dataset field.

string | null

required

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

JsonSchema

required

JSON Schema that values in this field must satisfy.See the HTTP endpoint for the supported JSON Schema fields.

boolean

required

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

object | null

required

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

Show Fields

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 for the complete schema.

object | null

required

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

Show Fields

object[]

required

Target proportion of rows for each split part.See the HTTP endpoint for the complete schema.

string | null

required

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

number

required

Seed used to make the part assignments repeatable.

"filling" | "ready" | "failed"

required

A slice cannot be taken while the field is filling.

object | null

required

Rows placed so far while the field is filling.

Show Fields

number

required

Number of previously unassigned rows placed so far.

number

required

Number of rows to place in this fill.

object | null

required

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

Show Fields

number

required

Number of previously unassigned rows placed by the last fill.

number

required

Number of rows whose existing part assignments were kept.

object

required

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

object | null

required

Why the last fill failed.

Show Fields

"too_many_labels" | "slice_failed"

required

Machine-readable reason the split fill failed.

string

required

Explanation of the split fill failure.

DatasetFieldOperation[]

required

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

Show type: "copy"

"copy"

required

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

DatasetFieldId

required

The field the values are copied from.

boolean

required

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

Show type: "split_fill"

"split_fill"

required

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

boolean

required

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

Show type: "write"

"write"

required

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

string

required

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

object | null

required

The number of rows written and the total number expected, when known.See the HTTP endpoint for the complete schema.

boolean

required

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

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:

DatasetFieldId

required

Dataset field ID with prefix df..

string

required

Name of the dataset field.

string | null

required

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

JsonSchema

required

JSON Schema that values in this field must satisfy.See the HTTP endpoint for the supported JSON Schema fields.

boolean

required

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

object | null

required

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

Show Fields

object[]

required

object | null

required

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

Show Fields

object[]

required

Target proportion of rows for each split part.See the HTTP endpoint for the complete schema.

string | null

required

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

number

required

Seed used to make the part assignments repeatable.

"filling" | "ready" | "failed"

required

A slice cannot be taken while the field is filling.

object | null

required

Rows placed so far while the field is filling.

Show Fields

number

required

Number of previously unassigned rows placed so far.

number

required

Number of rows to place in this fill.

object | null

required

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

Show Fields

number

required

Number of previously unassigned rows placed by the last fill.

number

required

Number of rows whose existing part assignments were kept.

object

required

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

object | null

required

Why the last fill failed.

Show Fields

"too_many_labels" | "slice_failed"

required

Machine-readable reason the split fill failed.

string

required

Explanation of the split fill failure.

DatasetFieldOperation[]

required

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

Show type: "copy"

"copy"

required

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

DatasetFieldId

required

The field the values are copied from.

boolean

required

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

Show type: "split_fill"

"split_fill"

required

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

boolean

required

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

Show type: "write"

"write"

required

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

string

required

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

object | null

required

The number of rows written and the total number expected, when known.See the HTTP endpoint for the complete schema.

boolean

required

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

string

required

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

Errors

HTTP errors throw PotatoApiError. The endpoint documents these error responses:

Status	Description
404	Dataset not found
429	Rate limit exceeded

HTTP endpoint: POST /datasets/{datasetId}/fields.

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);

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);

{
  "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"
}

[
  {
    "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"
  }
]

Reference

TypeScript SDK

CLI

HTTP API

client.datasets.createField()

Signature

Parameters

createField()

createFields()

Returns

createField() result

createFields() result

Errors

​Signature

​Parameters

​createField()

​createFields()

​Returns

​createField() result

​createFields() result

​Errors

Signature

Parameters

createField()

createFields()

Returns

createField() result

createFields() result

Errors