The toloka.yandex.com
domain will be disabled starting July 1, 2023. Please use the toloka.dev
domain for API requests.
Choose a platform to get an OAuth token:
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>
.Use the POST /api/v1/projects
method:
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.
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", ...}
You'll need the id
to create pools in the project: specify it in the add pool request.
In the given code example, substitute the parameter values:
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).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
:
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.
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", ...}
You'll need the id
to add tasks to the pool: specify it in the upload tasks request.
In the given code example, substitute the parameter values:
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).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
:
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.
Before you start the pool, go to the Toloka interface, select the pool, click Preview, and check that the tasks are displayed properly.
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:
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
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.
Read the instructions on how to get results.