Posting tasks

Attention

The toloka.yandex.com domain will be disabled starting July 1, 2023. Please use the toloka.dev domain for API requests.

Before you start

Choose a platform to get an OAuth token:

Sandbox

Production version

Register on the selected platform if you haven't done this before.
Get an OAuth token in the requester interface.
All examples use the sandbox URL: https://sandbox.toloka.dev/api/v1/<resource path>. If you decide to switch to the production version, replace the resource URL with https://toloka.dev/api/v1/<resource path>.

Create a project

Request

Use the POST /api/v1/projects method:

cURL

Postman

Send a request from the command line using the cURL utility:

curl -X POST \
     -H 'Authorization: OAuth <OAuth token>' \
     -H 'Content-Type: application/JSON' \
     -d '{
           "public_name": "Categories of shoes",
           "public_description": "Look at the picture and determine the category of shoes",
           "public_instructions": "In this task you will see images of different shoes. You need to determine their category.",
           "task_spec": {
             "input_spec": {
               "image": {
                 "type": "url",
                 "required": true,
                 "hidden": false
               }
             },
             "output_spec": {
               "result": {
                 "type": "string",
                 "required": true,
                 "hidden": false,
                 "allowed_values": ["boots","sneakers","other","failed to load"]
               }
             },
             "view_spec": {
               "lock": {
                 "core": "1.7.0",
                 "view.list": "1.0.5",
                 "view.image": "1.2.0",
                 "plugin.toloka": "1.1.8",
                 "field.radio-group": "1.1.10",
                 "condition.required": "1.1.5"
               },
               "type": "tb",
               "config": "{\"view\": {\"items\": [{\"url\": {\"path\": \"image\", \"type\": \"data.input\"}, \"ratio\": [1, 1], \"type\": \"view.image\"}, {\"data\": {\"path\": \"result\", \"type\": \"data.output\"}, \"validation\": {\"type\": \"condition.required\"}, \"options\": [{\"label\": \"Boots\", \"value\": \"boots\"}, {\"label\": \"Sneakers\", \"value\": \"sneakers\"}, {\"label\": \"Other\", \"value\": \"other\"}, {\"label\": \"Failed to load\", \"value\": \"failed to load\"}], \"type\": \"field.radio-group\"}], \"type\": \"view.list\"}, \"plugins\": [{\"layout\": {\"kind\": \"scroll\", \"taskWidth\": 400}, \"type\": \"plugin.toloka\"}]}",
               "settings": {
                 "showSkip": true,
                 "showTimer": true,
                 "showTitle": true,
                 "showFinish": true,
                 "showSubmit": true,
                 "showMessage": true,
                 "showFullscreen": true,
                 "showInstructions": true
               }
             }
           },
           "assignments_issuing_type": "AUTOMATED"
         }' \
https://sandbox.toloka.dev/api/v1/projects

The example shows the basic parameters that are necessary to create a simple project. For a more detailed description of all request parameters, see Create a project.

Response

In response to the request, you will receive a JSON object for the created project. This object contains the project id.

{
  "id": "12345",
  "public_name": "Categories of shoes",
  "public_description": "Look at the picture and determine the category of shoes",
  ...
}

Note

You'll need the id to create pools in the project: specify it in the add pool request.

Add a pool

Request

In the given code example, substitute the parameter values:

In the project_id parameter, replace <project id> with the ID of the project that the pool was created for (the ID received in response to the add project request).
In will_expire, replace <close date> with the UTC date and time in the ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss], specifying when the pool needs to be closed even if some task suites are not completed.

Next, send a POST request to /api/v1/pools:

cURL

Postman

Send a request from the command line using the cURL utility:

curl -X POST \
     -H 'Authorization: OAuth <OAuth token>' \
     -H 'Content-Type: application/JSON' \
     -d '{
           "project_id": "<project id>",
           "private_name": "Shoes pool 1",
           "may_contain_adult_content": true,
           "will_expire": "<close date>",
           "reward_per_assignment": 0.02,
           "assignment_max_duration_seconds": 60,
           "filter": {
             "and": [
               {
                 "or": [
                   {
                     "category": "profile",
                     "key": "languages",
                     "operator": "IN",
                     "value": "RU"
                   }
                 ]
               }
             ]
           },
           "quality_control": {
             "captcha_frequency": "LOW",
             "configs": [
               {
                 "collector_config": {
                   "type": "CAPTCHA",
                   "parameters": {
                     "history_size": 10
                   }
                 },
                 "rules": [
                   {
                     "conditions": [
                       {
                         "key": "stored_results_count",
                         "operator": "EQ",
                         "value": 10
                       },
                       {
                         "key": "success_rate",
                         "operator": "LTE",
                         "value": 70.0
                       }
                     ],
                     "action": {
                       "type": "RESTRICTION_V2",
                       "parameters": {
                         "scope": "PROJECT",
                         "duration_unit": "DAYS",
                         "duration": 3,
                         "private_comment": "Incorrect captcha input"
                       }
                     }
                   }
                 ]
               }
             ]
           },
           "mixer_config": {
             "real_tasks_count": 3,
             "golden_tasks_count": 0,
             "training_tasks_count": 0
           },
           "defaults": {
             "default_overlap_for_new_task_suites": 3
           }
         }' \
https://sandbox.toloka.dev/api/v1/pools

The example shows the basic parameters that are necessary to create a simple pool. For a more detailed description of all request parameters, see Create a pool.

Response

In response to the request, you will receive a JSON object for the created pool. This object contains the pool id.

{
  "id": "9876543",
  "project_id": "12345",
  "private_name": "Shoes pool 1",
  ...
}

Note

You'll need the id to add tasks to the pool: specify it in the upload tasks request.

Upload tasks

Request

In the given code example, substitute the parameter values:

In input_values, replace <proxy name>/<folder name>/<file name N>.<type> with specific values for the input data set in the project's input_spec parameter (in this example, these are paths to the images for labeling; place the image files on Yandex Disk and add it as a data source proxy).
In the pool_id parameter, replace <pool id> with the ID of the pool to upload the task to (the ID received in response to the add pool request).

Next, send a POST request to /api/v1/tasks:

cURL

Postman

Send a request from the command line using the cURL utility:

curl -X POST \
     -H 'Authorization: OAuth <OAuth token>' \
     -H 'Content-Type: application/JSON' \
     -d '[
           {
             "input_values": {
               "image": "https://sandbox.toloka.dev/api/proxy/<proxy name>/<folder name>/<file name 1>.<type>"
             },
             "pool_id": "<pool id>",
             "overlap": 2
           },
           {
             "input_values": {
               "image": "https://sandbox.toloka.dev/api/proxy/<proxy name>/<folder name>/<file name 2>.<type>"
             },
             "pool_id": "<pool id>",
             "overlap": 2
           },
           {
             "input_values": {
               "image": "https://sandbox.toloka.dev/api/proxy/<proxy name>/<folder name>/<file name 3>.<type>"
             },
             "pool_id": "<pool id>",
             "overlap": 2
           }
         ]' \
https://sandbox.toloka.dev/api/v1/tasks

The example shows the basic parameters that are necessary to upload simple tasks. For a more detailed description of each task parameter, see Create one or multiple tasks.

Start the pool

Before starting the pool

Before you start the pool, go to the Toloka interface, select the pool, click Preview, and check that the tasks are displayed properly.

Request

In the <pool_id> path parameter, insert the ID of the pool to start (the ID received in response to the add pool request) and use the POST method:

cURL

Postman

Send a request from the command line using the cURL utility:

curl -X POST \
     -H 'Authorization: OAuth <OAuth token>' \
     -H 'Content-Type: application/JSON' \
https://sandbox.toloka.dev/api/v1/pools/<pool_id>/open

Check the tasks

After starting the pool, make sure all the settings are correct and the tasks are displayed properly. To do this, log in to Toloka under the Toloker's username and open the card with the created tasks.