Project

In a project, you set properties for tasks and responses:

  • Input data parameters. These parameters describe the objects to display in a task, such as images or text.

  • Output data parameters. These parameters describe users' responses. They are used for validating the responses entered: the data type (integer, string, etc.), range of values, string length, and so on.

  • Task interface. For more information about how to define the appearance of tasks, see the Toloka Requester's guide.

A sample project in JSON with key descriptions is shown below.

You can use the API for performing the following operations with projects:

Sample project in JSON

{
  "public_name": "Elephant color",
  "public_description": "What color is the elephant in the picture?",
  "public_instructions": "<p>Look at the image and determine what color the elephant is.</p> You can zoom in or out using the buttons:</p> <img src=\"disc/img1.png>\"",
  "private_comment": "My first project",
  "task_spec": {
    "input_spec": {
      "image": {
        "type": "url",
        "required": true,
        "hidden": false
      }
    },
    "output_spec": {
      "result": {
        "type": "string",
        "required": true,
        "hidden": false                
      }
    },
    "view_spec": {
      "assets": {
        "script_urls": ["library1.js", "library2.js"]
      },
      "markup": "<task interface code>",
      "script": "<JavaScript code>",
      "styles": "<CSS code>",
      "settings": {
        "showSkip": true,
        "showTimer": true,
        "showTitle": true,
        "showSubmit": true,
        "showFullscreen": true,
        "showInstructions": true,
        "showFinish": true,
        "showMessage": true,
        "showReward": true
      }
    }
  },
  "assignments_issuing_type": "AUTOMATED",
  "assignments_automerge_enabled": false,
  "max_active_assignments_count": 15,
  "quality_control": {
    "configs": [{
      "collector_config": {
        "type": "SKIPPED_IN_ROW_ASSIGNMENTS"
      },
      "rules": [{
        "conditions": [{
          "key": "skipped_in_row_count",
          "operator": "GTE",
          "value": 10
        }],
        "action": {
          "type": "REJECT_ALL_ASSIGNMENTS",
          "parameters": {
            "public_comment": "Skipped more than 10 task suites in a row"
          }
        }
      }]
    }]
  },
  "localization_config": {
    "default_language": "EN",
    "additional_languages": [
      {
        "language": "RU",
        "public_name": {
          "value": "Elephant color",
          "source": "REQUESTER"
        },
        "public_description": {
          "value": "Какого цвета слон на картинке?",
          "source": "REQUESTER"
        },
        "public_instructions": {
          "value": "<p>Рассмотрите изображение и определите цвет слона.</p> Картинку можно увеличить или уменьшить при помощи кнопок:</p> <img src=\"disc/img1.png>\"",
          "source": "REQUESTER"
        }
      }
    ]
  }
}
Copied to clipboard

Keys

Key

Value

Data type

Required during creation

public_name

Name of the project. Visible to users.

String

Yes

public_description

Description of the project. Visible to users.

String

Yes

public_instructions

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

String

No

private_comment

Comments about the project. Visible only to the requester.

String

No

task_spec

Parameters for input and output data and the task interface.

JSON

Yes

task_spec.input_spec

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

JSON

Yes

task_spec.output_spec

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

JSON

Yes

task_spec.view_spec

Description of the task interface. For a complete list of parameters, see the table below.

JSON

Yes

assignments_issuing_type

How to assign tasks:

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

  • MAP_SELECTOR — The user chooses 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>"} 

The default value is AUTOMATED.

String

Yes

assignments_issuing_view_config.title_template

Only for tasks that the user chooses on the map (assignments_issuing_type: "MAP_SELECTOR").

Name of the task. Users will see it in the task preview.

String

Yes, if the parameter is specified
assignments_issuing_type: "MAP_SELECTOR"
assignments_issuing_view_config.description_template

Only for tasks that the user chooses on the map (assignments_issuing_type: "MAP_SELECTOR").

A brief description of the task. Users will see it in the task preview.

String

Yes, if the parameter is specified
assignments_issuing_type: "MAP_SELECTOR"
assignments_automerge_enabled
Resolve merging identical tasks in the project. The default value is false. Boolean No
max_active_assignments_count
The number of task suites the user can complete simultaneously (“Active” status). Number No
quality_control
The quality control rule. JSON No
quality_control.configs[]
Presets Array of JSON objects No
localization_config

Block of translations to other languages.

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

JSON

No

localization_config.default_language

The source language used in the fields public_name, public_description, and public_instructions.

String

No

localization_config.additional_languages[]

Array of target languages.

Array of JSON objects

No

localization_config.additional_languages[].language

Target language.

String

No

localization_config.additional_languages[].public_name

Translation of the project name.

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

Translation source:

  • REQUESTER — The requester set the value themselves.

  • AUTOMATIC_TRANSLATION — The value was obtained using machine translation.

  • MANUAL_TRANSLATION — The value was obtained from human translators.

JSON

No

localization_config.additional_languages[].public_description

Translation of the project description.

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

Translation source:

  • REQUESTER — The requester set the value themselves.

  • AUTOMATIC_TRANSLATION — The value was obtained using machine translation.

  • MANUAL_TRANSLATION — The value was obtained from human translators.

JSON

No

localization_config.additional_languages[].public_instructions

Translation of instructions for completing tasks.

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

Translation source:

  • REQUESTER — The requester set the value themselves.

  • AUTOMATIC_TRANSLATION — The value was obtained using machine translation.

  • MANUAL_TRANSLATION — The value was obtained from human translators.

JSON

No

id

Project ID (assigned automatically).

String

Not used

status

Status of the project:

  • ACTIVE

  • ARCHIVED

String

Not used

created

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

String

Not used

Key

Value

Data type

Required during creation

public_name

Name of the project. Visible to users.

String

Yes

public_description

Description of the project. Visible to users.

String

Yes

public_instructions

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

String

No

private_comment

Comments about the project. Visible only to the requester.

String

No

task_spec

Parameters for input and output data and the task interface.

JSON

Yes

task_spec.input_spec

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

JSON

Yes

task_spec.output_spec

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

JSON

Yes

task_spec.view_spec

Description of the task interface. For a complete list of parameters, see the table below.

JSON

Yes

assignments_issuing_type

How to assign tasks:

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

  • MAP_SELECTOR — The user chooses 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>"} 

The default value is AUTOMATED.

String

Yes

assignments_issuing_view_config.title_template

Only for tasks that the user chooses on the map (assignments_issuing_type: "MAP_SELECTOR").

Name of the task. Users will see it in the task preview.

String

Yes, if the parameter is specified
assignments_issuing_type: "MAP_SELECTOR"
assignments_issuing_view_config.description_template

Only for tasks that the user chooses on the map (assignments_issuing_type: "MAP_SELECTOR").

A brief description of the task. Users will see it in the task preview.

String

Yes, if the parameter is specified
assignments_issuing_type: "MAP_SELECTOR"
assignments_automerge_enabled
Resolve merging identical tasks in the project. The default value is false. Boolean No
max_active_assignments_count
The number of task suites the user can complete simultaneously (“Active” status). Number No
quality_control
The quality control rule. JSON No
quality_control.configs[]
Presets Array of JSON objects No
localization_config

Block of translations to other languages.

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

JSON

No

localization_config.default_language

The source language used in the fields public_name, public_description, and public_instructions.

String

No

localization_config.additional_languages[]

Array of target languages.

Array of JSON objects

No

localization_config.additional_languages[].language

Target language.

String

No

localization_config.additional_languages[].public_name

Translation of the project name.

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

Translation source:

  • REQUESTER — The requester set the value themselves.

  • AUTOMATIC_TRANSLATION — The value was obtained using machine translation.

  • MANUAL_TRANSLATION — The value was obtained from human translators.

JSON

No

localization_config.additional_languages[].public_description

Translation of the project description.

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

Translation source:

  • REQUESTER — The requester set the value themselves.

  • AUTOMATIC_TRANSLATION — The value was obtained using machine translation.

  • MANUAL_TRANSLATION — The value was obtained from human translators.

JSON

No

localization_config.additional_languages[].public_instructions

Translation of instructions for completing tasks.

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

Translation source:

  • REQUESTER — The requester set the value themselves.

  • AUTOMATIC_TRANSLATION — The value was obtained using machine translation.

  • MANUAL_TRANSLATION — The value was obtained from human translators.

JSON

No

id

Project ID (assigned automatically).

String

Not used

status

Status of the project:

  • ACTIVE

  • ARCHIVED

String

Not used

created

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

String

Not used

Input and output data (the "input_spec" and "output_spec" keys)

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

Key

Value

Data type

Required during creation

<ID>

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.

JSON

Yes

type

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”.

String

Yes

required

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

Boolean

No

hidden
Whether or not to hide the input value field from the user. The default value is false.

For output data, always false.

Boolean No
min_value

Minimum value of the number.

Number

No

max_value

Maximum value of the number.

Number

No

allowed_values[]

Allowed values.

Array

No

min_length

Minimum length of the string.

Number

No

max_length

Maximum length of the string.

Number

No

current_location

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

String

No

Key

Value

Data type

Required during creation

<ID>

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.

JSON

Yes

type

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”.

String

Yes

required

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

Boolean

No

hidden
Whether or not to hide the input value field from the user. The default value is false.

For output data, always false.

Boolean No
min_value

Minimum value of the number.

Number

No

max_value

Maximum value of the number.

Number

No

allowed_values[]

Allowed values.

Array

No

min_length

Minimum length of the string.

Number

No

max_length

Maximum length of the string.

Number

No

current_location

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

String

No

Task UI (the "view_spec" key)

Key

Value

Data type

Required during creation

assets
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.

JSON

No

assets.script_urls[]

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"]

Array of strings

No

assets.style_urls[]

Links to CSS libraries.

Array of strings

No

markup

Task interface.

For more information, see Requester's guide.

String

Yes

script

JavaScript interface for the task.

For more information, see Requester's guide.

String Yes
styles

CSS task interface.

For more information, see Requester's guide.

String Yes
settings

Whether to display standard UI elements in the task.

JSON

Yes

settings.showTimer

Show the timer. The default value is true.

Boolean

No

settings.showTitle

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

Boolean

No

settings.showInstructions

Show the Instructions button. The default value is true.

Boolean

No

settings.showFullscreen

Show the Expand to fullscreen button. The default value is true.

Boolean

No

settings.showSubmit

Show the Next button. The default value is true.

Boolean

No

settings.showSkip

Show the Skip button. The default value is true.

Boolean

No

settings.showFinish

Show the Back to main page button. The default value is true.

Boolean

No

settings.showMessage

Show the Message for the requester button. The default value is true.

Boolean

No

settings.showReward

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

Boolean

No

Key

Value

Data type

Required during creation

assets
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.

JSON

No

assets.script_urls[]

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"]

Array of strings

No

assets.style_urls[]

Links to CSS libraries.

Array of strings

No

markup

Task interface.

For more information, see Requester's guide.

String

Yes

script

JavaScript interface for the task.

For more information, see Requester's guide.

String Yes
styles

CSS task interface.

For more information, see Requester's guide.

String Yes
settings

Whether to display standard UI elements in the task.

JSON

Yes

settings.showTimer

Show the timer. The default value is true.

Boolean

No

settings.showTitle

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

Boolean

No

settings.showInstructions

Show the Instructions button. The default value is true.

Boolean

No

settings.showFullscreen

Show the Expand to fullscreen button. The default value is true.

Boolean

No

settings.showSubmit

Show the Next button. The default value is true.

Boolean

No

settings.showSkip

Show the Skip button. The default value is true.

Boolean

No

settings.showFinish

Show the Back to main page button. The default value is true.

Boolean

No

settings.showMessage

Show the Message for the requester button. The default value is true.

Boolean

No

settings.showReward

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

Boolean

No

Merging tasks

Tasks with identical input data can be merged. This allows you to save money if the same task was uploaded to different pools.

Restriction.
  • You can only merge tasks in open pools. If a new pool got a task that was previously completed in a pool that has been closed or archived, the tasks won't be merged.
  • You can only merge your main tasks.

The response to the task received will be automatically applied to another task if all of the following are true:

  • Both tasks have the same input data.
  • The tasks are located in different pools of the same project.
  • An identical task is available to the performer responding.
  • The identical task has fewer responses than the overlap.

The response will be recorded with a zero price, and the overlap will be reduced by one.

This option is only available for main tasks with automatic acceptance that were uploaded using “smart mixing”.

To activate task merging in a project, specify "assignments_automerge_enabled": true in the project.