Create a task suite

  1. Request
  2. Headers
  3. Query parameters
  4. Request body
  5. Response

Creates a task suite.

Restriction. You can add a maximum of 100,000 tasks per minute and a maximum of 2,000,000 tasks per day.

Request

POST https://toloka.yandex.com/api/v1/task-suites
Authorization: OAuth <OAuth token>
Content-Type: application/JSON

{task suite parameters}

Headers

Title Overview
authorization A token for account authorization. Add OAuth as a prefix.
content-type Specifies the data format in the request body.
Title Overview
authorization A token for account authorization. Add OAuth as a prefix.
content-type Specifies the data format in the request body.

Query parameters

Specified in the link after the question mark; separated by &.

Parameter Overview
async_mode

boolean

Mode for request processing:

  • true — Asynchronous. Creates an asynchronous operation that runs in the background. The response contains information about the operation (start and  completion time, status).

  • false — Synchronous. The response contains information about the created task suite.

The default value is false.

allow_defaults

boolean

Overlap settings:

The default value is false.

skip_invalid_items

boolean

Validation parameters for JSON objects:

  • true — Create a task suite that passed validation.

  • false — Stop the operation and don't create the task suite if it didn't pass validation.

The default value is false.

open_pool

boolean

Open the pool immediately after creating the task suite, if the pool is closed. The default value is false.

operation_id

string

Operation ID for asynchronous task suite loading (if async_mode=true).

We recommend sending the ID in the POST request to avoid accidental errors, such as creating the operation multiple times for the same task suite.

The ID should conform to the RFC4122 standard.

You can use this ID in the future to get information about the operation.

Parameter Overview
async_mode

boolean

Mode for request processing:

  • true — Asynchronous. Creates an asynchronous operation that runs in the background. The response contains information about the operation (start and  completion time, status).

  • false — Synchronous. The response contains information about the created task suite.

The default value is false.

allow_defaults

boolean

Overlap settings:

The default value is false.

skip_invalid_items

boolean

Validation parameters for JSON objects:

  • true — Create a task suite that passed validation.

  • false — Stop the operation and don't create the task suite if it didn't pass validation.

The default value is false.

open_pool

boolean

Open the pool immediately after creating the task suite, if the pool is closed. The default value is false.

operation_id

string

Operation ID for asynchronous task suite loading (if async_mode=true).

We recommend sending the ID in the POST request to avoid accidental errors, such as creating the operation multiple times for the same task suite.

The ID should conform to the RFC4122 standard.

You can use this ID in the future to get information about the operation.

Request body

{
    "id": "63614047-38c3-4ad4-8a86-99c5c651a9b8",
    "pool_id": "1",
    "tasks": [
        {"id": "49a333ea-2728-4c1c-ab1f-8ab1bfe4ee7e",
         "origin_task_id": "e3da7fe1-828d-4d9c-b49d-42c0eb5fcfde",
         "input_values": {
                "image_url": "www.image1.ru"
            },
            "known_solutions": [
                {
                    "correctness_weight": 0.95,
                    "output_values": {
                        "colour": "black"
                    }
                },
                {
                    "correctness_weight": 0.7,
                    "output_values": {
                        "colour": "gray"
                    }
                }
            ],
            "message_on_unknown_solution": "The elephant is black"
        },
        {
            "input_values": {
                "image_url": "www.image2.ru"
            },
            "known_solutions": [
                {
                    "correctness_weight": 1,
                    "output_values": {
                        "colour": "white"
                    }
                }
            ],
            "message_on_unknown_solution": "The elephant is white"
        }
    ],
    "overlap": 5,
    "infinite_overlap": false,
    "remaining_overlap": 3,
    "reserved_for": [],
    "unavailable_for": [],
    "issuing_order_override": 3,
    "mixed": true,
    "automerged": false,
    "created": "2016-04-18T12:43:04.988"
}
     
Copied to clipboard
Parameter Overview
pool_id

string | required

The ID of the pool that tasks are uploaded to.

tasks[]

array of object | required

Data for the tasks.

tasks[].input_values

object | required

Input data for a task. List of pairs:

"<ID of field 1>": "<value of field 1>",
"<ID of field 2>": "<value of field 2>",
...
"<ID of field N>": "<value of field N>"
overlap

integer | required if

Required if the parameter is not used when creating a task suite allow_defaults=true, and the overlap is not specified in the pool parameters (in the defaults.​default_​overlap_for_​new_task_suites key).

Task suite overlap.

longitude

float | required if

Required if tasks are selected on the map. Otherwise, not used.

The longitude of the point on the map for the task suite.

latitude

float | required if

Required if tasks are selected on the map. Otherwise, not used.

The latitude of the point on the map for the task suite.

tasks[].known_solutions

object

Responses and hints for control tasks and training tasks.

tasks[].known_solutions.output_values

object

Correct responses in a task (for control tasks). If multiple correct responses are possible, define output_values for each possible response and set the weight for the correct response (the correctness_weight key).

"<ID of field 1>": "<correct response>",
"<ID of field 2>": "<correct response>",
...
"<ID of field N>": "<correct response N>"
tasks[].known_solutions.correctness_weight

float

The weight of a correct response. Allows you to set multiple versions of correct responses and rank them by correctness. For example, if a correct response is weighted 0.5, it counts as half of a mistake for the user. The more correct the response in correctValues, the higher its weight.

tasks[].message_on_unknown_solution

string

Hint for the task (for training tasks).

infinite_overlap

boolean | required

Assigning a task suite with infinite overlap. This option is used, for instance, for suites of training tasks when you want to assign them to all users:
  • true — Use infinite overlap.

  • false — Use the overlap that is set for the task suite or pool.

reserved_for[]

array of integer

IDs of users who will have access to the task suites.

unavailable_for[]

array of integer

IDs of users who shouldn't have access to the task suite.

issuing_order_override

float

The priority of a task suite among other suites in the pool. Defines the order in which task suites are assigned to performers. The larger the parameter value, the higher the priority.

This parameter can be used if the pool has issue_task_suites_in_creation_order: true.

Allowed values: from -99999.99999 to 99999.99999.

The default value is 0.

mixed

boolean

Type of operation for creating a task suite:

  • true — Automatically with the “smart mixing” option (for more information, see the Requester's guide).

  • false — Manually.

Parameter Overview
pool_id

string | required

The ID of the pool that tasks are uploaded to.

tasks[]

array of object | required

Data for the tasks.

tasks[].input_values

object | required

Input data for a task. List of pairs:

"<ID of field 1>": "<value of field 1>",
"<ID of field 2>": "<value of field 2>",
...
"<ID of field N>": "<value of field N>"
overlap

integer | required if

Required if the parameter is not used when creating a task suite allow_defaults=true, and the overlap is not specified in the pool parameters (in the defaults.​default_​overlap_for_​new_task_suites key).

Task suite overlap.

longitude

float | required if

Required if tasks are selected on the map. Otherwise, not used.

The longitude of the point on the map for the task suite.

latitude

float | required if

Required if tasks are selected on the map. Otherwise, not used.

The latitude of the point on the map for the task suite.

tasks[].known_solutions

object

Responses and hints for control tasks and training tasks.

tasks[].known_solutions.output_values

object

Correct responses in a task (for control tasks). If multiple correct responses are possible, define output_values for each possible response and set the weight for the correct response (the correctness_weight key).

"<ID of field 1>": "<correct response>",
"<ID of field 2>": "<correct response>",
...
"<ID of field N>": "<correct response N>"
tasks[].known_solutions.correctness_weight

float

The weight of a correct response. Allows you to set multiple versions of correct responses and rank them by correctness. For example, if a correct response is weighted 0.5, it counts as half of a mistake for the user. The more correct the response in correctValues, the higher its weight.

tasks[].message_on_unknown_solution

string

Hint for the task (for training tasks).

infinite_overlap

boolean | required

Assigning a task suite with infinite overlap. This option is used, for instance, for suites of training tasks when you want to assign them to all users:
  • true — Use infinite overlap.

  • false — Use the overlap that is set for the task suite or pool.

reserved_for[]

array of integer

IDs of users who will have access to the task suites.

unavailable_for[]

array of integer

IDs of users who shouldn't have access to the task suite.

issuing_order_override

float

The priority of a task suite among other suites in the pool. Defines the order in which task suites are assigned to performers. The larger the parameter value, the higher the priority.

This parameter can be used if the pool has issue_task_suites_in_creation_order: true.

Allowed values: from -99999.99999 to 99999.99999.

The default value is 0.

mixed

boolean

Type of operation for creating a task suite:

  • true — Automatically with the “smart mixing” option (for more information, see the Requester's guide).

  • false — Manually.

Response

It includes:

  • Task suite data in JSON format.
  • Parameters that are assigned automatically.
Parameter Overview
id

string

ID of a task suite.

tasks[].id

string

Task ID if the task suite is created automatically with the “smart mixing” option (for more information, see the Requester's guide).

tasks[].origin_task_id

string

The ID of a task from another pool from which this task was copied for majority vote verification.

remaining_overlap

integer

The remaining overlap for each task. For example, if the task has an overlap of 5 but was completed by two  people, the remaining_overlap value is 3.

If the task is under review or active, the key is 0.

automerged

boolean

Flag for whether a task suite is created after merging tasks. Value:

  • true — The task suite is generated as a result of merging identical tasks.
  • false — A standard task suite created by “smart mixing” or by the requester.
created

string

The UTC date and time when the task suite was created, in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

Parameter Overview
id

string

ID of a task suite.

tasks[].id

string

Task ID if the task suite is created automatically with the “smart mixing” option (for more information, see the Requester's guide).

tasks[].origin_task_id

string

The ID of a task from another pool from which this task was copied for majority vote verification.

remaining_overlap

integer

The remaining overlap for each task. For example, if the task has an overlap of 5 but was completed by two  people, the remaining_overlap value is 3.

If the task is under review or active, the key is 0.

automerged

boolean

Flag for whether a task suite is created after merging tasks. Value:

  • true — The task suite is generated as a result of merging identical tasks.
  • false — A standard task suite created by “smart mixing” or by the requester.
created

string

The UTC date and time when the task suite was created, in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].