> ## 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. # 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. ## OpenAPI ````yaml /api-reference/openapi.json post /datasets/{datasetId}/fields openapi: 3.1.0 info: description: >- Manage projects, datasets, labeling pipelines, and model training. **Beta:** endpoints, request and response shapes, and error contracts can change without notice or a backward-compatibility promise. title: Toloka Platform API version: 2.0.0 servers: - url: https://platform.toloka.ai/api/v2-beta security: - apiKeyAuth: [] - scopedTokenAuth: [] tags: - description: The authenticated API key owner. name: Account - description: A project is the container for pipelines, datasets, and files. name: Projects - description: Rows and typed fields. Field schemas are immutable once created. name: Datasets - description: Append rows to a dataset from a file. name: Dataset uploads - description: Read a dataset out as a file. name: Dataset exports - description: A pipeline is a graph of nodes that processes each dataset item. name: Pipelines - description: The nodes, connections, fields, and version of a pipeline graph. name: Pipeline graph - description: Execute a pipeline over a dataset and inspect each item. name: Runs - description: Per-node checks that a pipeline must pass before deployment. name: Checks - description: Named credentials available to pipeline code. name: Secrets - description: Project files available to pipeline code and labeling interfaces. name: Files - description: >- Global, read-only catalog of the models a synthetic generation node can use, with their budget bounds. name: Generation models - description: >- Global, read-only catalog of the expert audience: the values a node `audience` filter can use. name: Audience - description: >- Project lists of experts a node can take its workforce from with `audienceMode: service`. Available only to teams with the audience service enabled. name: Expert lists - description: >- Experts banned in a project: they cannot be invited and are removed from the work they are in. Available only to teams with expert bans enabled. name: Expert ban list - description: Global, read-only base model catalog. name: Base models - description: Project-owned mutable model-training drafts. name: Trainings - description: Project-owned Models and immutable Model Versions. name: Models - name: Batch inference paths: /datasets/{datasetId}/fields: post: tags: - Datasets summary: Create dataset fields description: >- 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. operationId: createDatasetField parameters: - in: path name: datasetId required: true schema: $ref: '#/components/schemas/DatasetId' requestBody: content: application/json: schema: anyOf: - properties: jsonSchema: $ref: '#/components/schemas/JsonSchema' description: JSON Schema that values in the new field must satisfy. name: description: Name of the new dataset field. maxLength: 128 minLength: 1 pattern: ^[a-z]([a-z0-9_]*[a-z0-9])?$ type: string required: - name - jsonSchema type: object - properties: fields: description: >- Dataset fields to create, with unique names and their JSON Schemas. items: properties: jsonSchema: $ref: '#/components/schemas/JsonSchema' description: >- JSON Schema that values in the new field must satisfy. name: description: Name of the new dataset field. maxLength: 128 minLength: 1 pattern: ^[a-z]([a-z0-9_]*[a-z0-9])?$ type: string required: - name - jsonSchema type: object maxItems: 500 minItems: 1 type: array required: - fields type: object responses: '200': content: application/json: schema: anyOf: - $ref: '#/components/schemas/DatasetField' - $ref: '#/components/schemas/CreatedDatasetFields' description: Created field, or created fields when the request listed several headers: RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' X-Request-Id: $ref: '#/components/headers/X-Request-Id' '404': description: Dataset not found headers: RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' X-Request-Id: $ref: '#/components/headers/X-Request-Id' '429': description: Rate limit exceeded headers: RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' X-Request-Id: $ref: '#/components/headers/X-Request-Id' x-codeSamples: - label: TypeScript SDK · single lang: typescript source: | 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); - label: TypeScript SDK · batch lang: typescript source: | 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); components: schemas: DatasetId: description: Dataset ID with prefix `ds.`. pattern: >- ^ds\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string JsonSchema: additionalProperties: false description: JSON Schema defining the accepted values for a field. properties: additionalProperties: anyOf: - description: >- Whether extra object properties are allowed, or the schema they must satisfy; omitted means allowed. type: boolean - $ref: '#/components/schemas/JsonSchema' description: >- Whether extra object properties are allowed, or the schema they must satisfy; omitted means allowed. description: >- Whether extra object properties are allowed, or the schema they must satisfy; omitted means allowed. allOf: description: Combined schemas; a value must satisfy every schema when supplied. items: $ref: '#/components/schemas/JsonSchema' description: JSON Schema defining the accepted values for a field. minItems: 1 type: array anyOf: description: >- Alternative schemas; a value must satisfy at least one when supplied. items: $ref: '#/components/schemas/JsonSchema' description: JSON Schema defining the accepted values for a field. minItems: 1 type: array const: $ref: '#/components/schemas/JsonValue' description: Single required JSON value; omit when no exact value is required. default: $ref: '#/components/schemas/JsonValue' description: Suggested default JSON value; omit when none is specified. description: description: Optional explanation of the values accepted by this schema. type: string enum: description: >- Allowed JSON values; omit to allow any value satisfying the other constraints. items: $ref: '#/components/schemas/JsonValue' minItems: 1 type: array examples: description: Example JSON values for this schema; omit when none are supplied. items: $ref: '#/components/schemas/JsonValue' type: array exclusiveMaximum: description: Exclusive upper bound for a number; omit when none is required. type: number exclusiveMinimum: description: Exclusive lower bound for a number; omit when none is required. type: number format: description: >- String format, such as `date-time`, `email`, or `uri`; omit when no format is required. type: string items: $ref: '#/components/schemas/JsonSchema' description: >- Schema that every array item must satisfy; omit to leave items unrestricted. maxItems: description: Maximum number of array items; omit for no upper bound. maximum: 9007199254740991 minimum: 0 type: integer maxLength: description: >- Maximum string length in Unicode characters; omit for no upper bound. maximum: 9007199254740991 minimum: 0 type: integer maximum: description: Inclusive upper bound for a number; omit for no upper bound. type: number minItems: description: Minimum number of array items; omit for no lower bound. maximum: 9007199254740991 minimum: 0 type: integer minLength: description: >- Minimum string length in Unicode characters; omit for no lower bound. maximum: 9007199254740991 minimum: 0 type: integer minimum: description: Inclusive lower bound for a number; omit for no lower bound. type: number oneOf: description: Alternative schemas; a value must satisfy exactly one when supplied. items: $ref: '#/components/schemas/JsonSchema' description: JSON Schema defining the accepted values for a field. minItems: 1 type: array pattern: description: >- Regular expression a string must match; omit for no pattern constraint. type: string properties: $ref: '#/components/schemas/JsonSchemaProperties' description: Schemas for named object properties; omit when none are specified. required: description: >- Object property names that must be present; omit when none are required. items: type: string type: array title: description: Optional display title for this schema. type: string type: anyOf: - description: Accepted JSON type or types; omit to allow any type. enum: - string - number - integer - boolean - object - array - 'null' type: string - description: Accepted JSON type or types; omit to allow any type. items: enum: - string - number - integer - boolean - object - array - 'null' type: string minItems: 1 type: array description: Accepted JSON type or types; omit to allow any type. uniqueItems: description: >- Whether array items must be unique; omitted means duplicates are allowed. type: boolean type: object DatasetField: description: A field of a dataset. properties: createdAt: description: Time the field was created, as an ISO 8601 timestamp. format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ type: string description: description: Description of the field, or null when none is set. type: - string - 'null' id: $ref: '#/components/schemas/DatasetFieldId' description: Dataset field ID with prefix `df.`. internal: description: >- True when this field is excluded from pipeline input bindings. The field is still included in dataset field responses. type: boolean jsonSchema: $ref: '#/components/schemas/JsonSchema' description: JSON Schema that values in this field must satisfy. name: description: Name of the dataset field. type: string operations: description: >- Operations currently writing to this field. A split or slice that reads the field is rejected while a blocking operation runs. items: $ref: '#/components/schemas/DatasetFieldOperation' type: array split: anyOf: - properties: error: anyOf: - properties: code: description: Machine-readable reason the split fill failed. enum: - too_many_labels - slice_failed type: string message: description: Explanation of the split fill failure. type: string required: - code - message type: object - type: 'null' description: Why the last fill failed. lastFill: anyOf: - properties: kept: description: >- Number of rows whose existing part assignments were kept. maximum: 9007199254740991 minimum: 0 type: integer parts: additionalProperties: maximum: 9007199254740991 minimum: 0 type: integer description: >- Row counts for each part after the last fill, keyed by part name. propertyNames: type: string type: object placed: description: >- Number of previously unassigned rows placed by the last fill. maximum: 9007199254740991 minimum: 0 type: integer required: - placed - kept - parts type: object - type: 'null' description: >- The last fill: rows it placed, rows that already had a part, and the rows each part held after it. parts: description: >- 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. items: properties: name: description: >- Name stored in this field for rows assigned to this part. maxLength: 64 pattern: ^[A-Za-z0-9_]+(?:[.-][A-Za-z0-9_]+)*$ type: string roles: description: >- Uses of this part: `train` for training, `validate` for validation, and `test` for held-out evaluation; an empty array assigns no role. items: enum: - train - validate - test type: string type: array required: - name - roles type: object type: array progress: anyOf: - properties: placed: description: Number of previously unassigned rows placed so far. maximum: 9007199254740991 minimum: 0 type: integer total: description: Number of rows to place in this fill. maximum: 9007199254740991 minimum: 0 type: integer required: - placed - total type: object - type: 'null' description: Rows placed so far while the field is filling. recipe: anyOf: - properties: balanceByFieldId: anyOf: - pattern: >- ^df\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string - type: 'null' description: >- Field ID with prefix `df.` used to balance labels, or null when balancing is disabled. seed: description: Seed used to make the part assignments repeatable. maximum: 2147483647 minimum: 0 type: integer shares: description: Target proportion of rows for each split part. items: properties: name: description: Name of the split part. maxLength: 64 pattern: ^[A-Za-z0-9_]+(?:[.-][A-Za-z0-9_]+)*$ type: string share: description: >- Target fraction of rows assigned to this part, between 0 and 1. type: number required: - name - share type: object type: array required: - shares - balanceByFieldId - seed type: object - type: 'null' description: >- How the next fill samples parts; null for an adopted field until a fill gives it shares. status: description: A slice cannot be taken while the field is filling. enum: - filling - ready - failed type: string required: - parts - recipe - status - progress - lastFill - error type: object - type: 'null' description: 'Set when this is a split field: each row''s value names its part.' required: - id - name - description - jsonSchema - internal - split - operations - createdAt type: object CreatedDatasetFields: description: Dataset fields created in one request. properties: fields: description: Dataset fields created by this request. items: $ref: '#/components/schemas/DatasetField' type: array required: - fields type: object JsonValue: anyOf: - type: string - type: number - type: boolean - type: 'null' - items: $ref: '#/components/schemas/JsonValue' type: array - additionalProperties: $ref: '#/components/schemas/JsonValue' propertyNames: type: string type: object JsonSchemaProperties: additionalProperties: $ref: '#/components/schemas/JsonSchema' propertyNames: type: string type: object DatasetFieldId: description: Dataset field ID with prefix `df.`. pattern: >- ^df\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string DatasetFieldOperation: description: A background operation writing into a dataset field. oneOf: - $ref: '#/components/schemas/DatasetFieldCopyOperation' - $ref: '#/components/schemas/DatasetFieldSplitFillOperation' - $ref: '#/components/schemas/DatasetFieldWriteOperation' DatasetFieldCopyOperation: description: Values are being copied into this field from another dataset field. properties: blocking: description: >- True when splits and slices that read this field must wait for the operation to finish. type: boolean sourceFieldId: $ref: '#/components/schemas/DatasetFieldId' description: The field the values are copied from. type: const: copy description: >- Operation kind: `copy` copies field values, `split_fill` assigns split parts, and `write` writes new field revisions. type: string required: - type - sourceFieldId - blocking type: object DatasetFieldSplitFillOperation: description: Part names are being assigned to rows in this split field. properties: blocking: description: >- True when splits and slices that read this field must wait for the operation to finish. type: boolean type: const: split_fill description: >- Operation kind: `copy` copies field values, `split_fill` assigns split parts, and `write` writes new field revisions. type: string required: - type - blocking type: object DatasetFieldWriteOperation: description: >- New values are being written to this field, such as batch inference results. properties: blocking: description: >- True when splits and slices that read this field must wait for the operation to finish. type: boolean progress: anyOf: - properties: done: description: Number of rows written so far. maximum: 9007199254740991 minimum: 0 type: integer total: description: Total number of rows expected to be written. maximum: 9007199254740991 minimum: 0 type: integer required: - done - total type: object - type: 'null' description: >- The number of rows written and the total number expected, when known. type: const: write description: >- Operation kind: `copy` copies field values, `split_fill` assigns split parts, and `write` writes new field revisions. type: string writer: description: >- The source of the new field revisions. For a batch inference run, this is `batch-inference-run:`. type: string required: - type - writer - progress - blocking type: object headers: RateLimit-Limit: description: The maximum number of requests allowed in the current window. schema: type: integer RateLimit-Policy: description: The rate limit policy (e.g., "60;w=60"). schema: type: string RateLimit-Remaining: description: The number of requests remaining in the current window. schema: type: integer RateLimit-Reset: description: The number of seconds until the current window resets. schema: type: integer X-Request-Id: description: >- The request id: the X-Request-Id you sent when it is 1-128 characters of letters, digits, ".", "_" or "-", otherwise a generated UUID. Present on every response, including errors; quote it when reporting a problem. schema: type: string securitySchemes: apiKeyAuth: description: >- Enter `ApiKey ` in Authorization, including the `ApiKey ` prefix. In cURL and Python samples, `` means this full value. The TypeScript SDK adds the prefix for you. in: header name: Authorization type: apiKey scopedTokenAuth: description: >- Enter the project-scoped token as `pst_...` in X-Scoped-Token, without an `ApiKey ` prefix. Create a token with POST /projects/{projectId}/tokens. in: header name: X-Scoped-Token type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.