Create a project

Attention

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

Creates a project.

Restriction

You can send a maximum of 20 requests of this kind per minute and a maximum of 100 requests per day. Refer to the Rate limiting section for the complete list of the request limitations in Toloka API.

Request

Tip

Try our new API reference: more parameter details, request/response examples, and code samples in various programming languages, including the Toloka-Kit usage samples.

Production version
Sandbox
POST https://toloka.dev/api/v1/projects
Authorization: OAuth <OAuth token>
Content-Type: application/JSON
{<project parameters>}

Headers

TitleOverview
AuthorizationA token for account authorization. Add OAuth as a prefix.
Content-TypeSpecifies the data format in the request body.

Request body

{
"public_name": "Image classification",
"public_description": "Look at the picture and determine the category of shoes",
"public_instructions": "<div> In this task you will see images of different shoes.<br /><br /> You need to determine their category.<br /><br /> To complete the task faster, use the hotkeys 1, 2, 3, and arrows, if you are performing the task on a desktop computer or laptop.<br /><br /> How to complete the task: <ol><li>Look carefully at the image.</li><li>Click the <strong>Rotate</strong> button if you need to turn the picture, it can be on one side or upside down.</li><li>Choose one of the answer options. If the image doesn&#39;t correspond to any of the categories press <strong>Other</strong>.</li><li>Skip the tasks if the image doesn’t load or loads only partly.</li></ol> </div>",
"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"
]
}
},
"view_spec": {
"type": "tb",
"settings": {
"showSubmit": true,
"showSkip": true,
"showFinish": true,
"showTimer": true,
"showTitle": true,
"permissions": [],
"showMessage": true,
"showReward": true,
"showFullscreen": true,
"showInstructions": true
},
"config": {...},
"lock": {
"core": "1.13.1",
"view.list": "1.2.0",
"action.set": "1.0.8",
"view.image": "1.4.0",
"plugin.toloka": "1.1.8",
"plugin.hotkeys": "1.3.0",
"condition.required": "1.1.6",
"field.button-radio-group": "1.3.1"
},
"localization_Config": {
"keys": []
}
}
},
"assignments_issuing_type": "AUTOMATED"
}
ParameterOverview
public_namestring | required

Name of the project. It will be shown to Tolokers.
public_descriptionstring | required

Description of the project. It will be shown to Tolokers.
task_specobject | required

Parameters for input and output data and the task interface.
task_spec.input_specobject | required

The input data parameters for tasks. The complete list of parameters is shown in the Input and output data table.
task_spec.output_specobject | required

Parameters for output data from the input fields. The complete list of parameters is shown in the Input and output data table.
task_spec.view_specobject

Description of the task interface. The complete list of parameters is shown in the Task interface table.
assignments_issuing_view_configstring | required if

Required if assignments_issuing_type=MAP_SELECTOR.

Settings for displaying field tasks. For a complete list of parameters, see Settings for displaying field tasks.
public_instructionsstring

Instructions for completing the task. You can use any HTML markup in the instructions.
private_commentstring

Comments that are only visible to the requester.
assignments_issuing_type

string

How to assign tasks:

  • AUTOMATED — The Toloker is assigned a task suite from the pool. You can configure the order for assigning task suites.

  • MAP_SELECTOR — The Toloker selects a task suite on the map. If you are using MAP_SELECTOR, specify the text to display in the map name and description in the assignments_issuing_view_config key:

    "assignments_issuing_view_config": {
    "title_template": "<task name>",
    "description_template": "<brief description of the task>",
    "map_provider": "YANDEX"
    }

The default value is AUTOMATED.

assignments_automerge_enabledboolean

Resolve merging identical tasks in the project. The default value is false.
max_active_assignments_countinteger

The number of task suites the Toloker can complete simultaneously ("Active" status).
quality_controlobject

The quality control rule.
quality_control.configs[]array of objects

Presets
localization_configobject

Block of translations to other languages. The complete list of parameters is shown in the Translations to other languages table.

For more information about translation, see Translations to other languages.

Input and output data (input_spec and output_spec)

The input_spec and output_spec parameters contain JSON with the input data properties and response validation parameters. Use them to define the data type (string, integer, URL, and so on) and specify validation parameters (such as the string length).

ParameterOverview
<ID>

object | required

  • For input data,  the ID of the object to display in the task, and its properties.
  • For output data, the ID of the response input field and response validation parameters.
type

string | required

Data type:

  • url — URL of an image, page, and so on.
  • boolean — Boolean data type (true/false).
  • integer — Integer.
  • string — String.
  • float — Floating-point number.
  • json — JSON object.
  • file — File (only for output data).
  • coordinates — Geographical coordinates, such as "53.910236, 27.531110").
requiredboolean

Whether the object or input field is required. The default value is true.
hiddenboolean

Whether to hide field with the input value from the Toloker or not. The default value is false.

For output data, always false.
min_valuefloat

Minimum value of the number.
max_valuefloat

Maximum value of the number.
allowed_values[]array of strings, array of integers, array of floats

Allowed values.

Setting acceptable values improves the quality of response aggregation.
min_lengthinteger

Minimum length of the string.
max_lengthinteger

Maximum length of the string.
current_locationstring

Only for output data of the coordinates type: populate the field with the Toloker's current coordinates in the field (true/false). Used in tasks for the mobile app.

Task interface (view_spec)

ParameterOverview
markupstring

HTML markup of the task.

For more information, see the HTML block section.
scriptstring

JavaScript code of the task.

For more information, see the JavaScript block section.
stylesstring

CSS styles of the task.

For more information, see the CSS block section.
settingsobject | required

Whether to display common interface elements in the task.
config[]array of objects

Configuration for Template Builder
lockobject | required if

Required if type is set to tb.

The set of the Template Builder component versions that will be used to create the project task interface.
assets

object

Linked files:

  • CSS styles
  • JavaScript libraries
  • Toloka assets with the $TOLOKA_ASSETS prefix. Add items in the order they should be linked when running the task interface.
assets.script_urls[]

array of strings

Links to JavaScript libraries and Toloka assets.

Toloka assets:

Note that the image labeling interface should only be connected together with the Handlebars helpers. The order of connection matters:

"script_urls": [
"$TOLOKA_ASSETS/js/toloka-handlebars-templates.js",
"$TOLOKA_ASSETS/js/image-annotation.js"
]
assets.style_urls[]array of strings

Links to CSS libraries.
type

string

Editor type used to create the project interface:

  • classic — the HTML/CSS/JS editor which allows using HTML, CSS, and JavaScript elements to create the task interface.
  • tb — the Template Builder editor which allows using elements with JSON syntax for the task interface.

Depending on the editor type, the following parameters are used:

  • assets, markup, script, and styles when the value is set to classic.
  • config, lock when the value is set to tb.
localizationConfigobject

Editor configuration.

In the Template Builder, add to this field the keys for the properties of text components that you need to translate into other languages.

For more information, see Translating the task interface.
localizationConfig.keys

string

Keys in the source language.

"key": "<key name>",
"defaultValue": "<source text>"

For more information, see Translating the task interface.

settings.showTimerboolean

Show the remaining time. The default value is true.
settings.showTitleboolean

Show the project name in task titles. The default value is true.
settings.showInstructionsboolean

Show the Instructions button. The default value is true.
settings.showFullscreenboolean

Show the Fullscreen button. The default value is true.
settings.showSubmitboolean

Show the Submit button. The default value is true.
settings.showSkipboolean

Show the Skip button. The default value is true.
settings.showFinishboolean

Show the Exit button. The default value is true.
settings.showMessageboolean

Show the Contact requester button. The default value is true.
settings.showRewardboolean

Show the price per task suite. The default value is true.

Settings for displaying field tasks (assignments_issuing_view_config)

ParameterOverview
title_templatestring | required if

Required if assignments_issuing_type=MAP_SELECTOR.

Name of the task. Tolokers will see it in the task preview.
description_templatestring | required if

Required if assignments_issuing_type=MAP_SELECTOR.

A description of the task. Tolokers will see it in the task preview.
map_provider

string

This parameter is available when the project has "assignments_issuing_type": "MAP_SELECTOR".

Map provider for tasks:

  • GOOGLE — Google Maps.
  • YANDEX — Yandex Maps.

    If the parameter is not set, then the Toloker selects the map.

Translations to other languages (localization_config)

ParameterOverview
default_languagestring

The source language used in the fields public_name, public_description, and public_instructions.
additional_languages[]array of objects

Array of target languages.
additional_languages[]. languagestring

Target language.
additional_languages[]. public_name

object

Translation of the project name.

"value": "<target text>",
"source": "<source text>"

Translation source:

  • REQUESTER — The requester set the value themselves.
additional_languages[]. public_description

object

Translation of the project description.

"value": "<target text>",
"source": "<source text>"

Translation source:

  • REQUESTER — The requester set the value themselves.
additional_languages[]. public_instructions

object

Translation of instructions for completing tasks.

"value": "<target text>",
"source": "<source text>"

Translation source:

  • REQUESTER — The requester set the value themselves.
additional_languages[]. tb_view_specobject

Translating the task interface.
additional_languages[]. tb_view_spec.keys[]

array of objects

Keys with the translation of the task interface elements.

"key": "<key name>",
"value": "<target text>",
"source": "<source text>"

Translation source:

  • REQUESTER — The requester set the value themselves.

Response

Contains information about the uploaded project in JSON format. The project is automatically assigned an ID.

It includes:

ParameterOverview
ownerobject

Parameters of the requester that created the project
owner.idstring

Parameters to sort by:
owner.myself

boolean

Checks who the object belongs to:

  • true — The user whose OAuth token is specified in the request.
  • false — Another account (employee or owner).
idstring

Project ID (assigned automatically).
status

string

Status of the project:

  • ACTIVE — Active.
  • ARCHIVED — Archived.
createdstring

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

See also

Contact support
Toloka API
OverviewAccessing the APIRate limiting
Quick start
Reference
Project
Pools
Training
Subscriptions to events
Toloker selection
Ways to upload tasks
Tasks
Task suites
Tracking operations
Getting responses
Checking completed tasks
Bonuses
Messages for Tolokers
Various parameters
Libraries