Create a project

  1. Request
  2. Headers
  3. Request body
  4. Input and output data (the input_spec and output_spec parameters)
  5. Task interface (the view_spec parameter)
  6. Response

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.

Request

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

{<project 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.

Request body

{
  "public_name": "Elephant color",
  "public_description": "What color is the elephant in the picture?",
  "public_instructions": "<p>Look at the picture and decide 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": "Цвет слона",
          "source": "REQUESTER"
        },
        "public_description": {
          "value": "Какого цвета слон на картинке?",
          "source": "REQUESTER"
        },
        "public_instructions": {
          "value": "<p>Рассмотрите изображение и определите цвет слона.</p> Картинку можно увеличить или уменьшить при помощи кнопок:</p> <img src=\"disc/img1.png>\"",
          "source": "REQUESTER"
        }
      }
    ]
  }
}
Copied to clipboard
Parameter Overview
public_name

string | required

Name of the project. Visible to users.

public_description

string | required

Description of the project. Visible to users.

task_spec

object | required

Parameters for input and output data and the task interface.

task_spec.input_spec

object | required

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

assignments_issuing_view_ config.title_template

string | required if

Required if assignments_issuing_type=MAP_SELECTOR.

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

public_instructions

string

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

private_comment

string

Comments that are only visible to the requester.

task_spec.output_spec | required

object

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_spec

object

Description of the task interface. The complete list of parameters is shown in the Task interface table.

assignments_issuing_type

string

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.

assignments_automerge_ enabled

boolean

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

max_active_assignments_ count

integer

The number of task suites the user can complete simultaneously (“Active” status).

quality_control

object

The quality control rule.

quality_control.configs[]

array of objects

Presets

localization_config

object

Block of translations to other languages.

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

localization_config.default_ language

string

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

localization_config. additional_languages[]

array of objects

Array of target languages.

localization_config. additional_languages[]. language

string

Target language.

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

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

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

localization_config. additional_languages[]. tb_view_spec

object

Translating the task interface.

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

Parameter Overview
public_name

string | required

Name of the project. Visible to users.

public_description

string | required

Description of the project. Visible to users.

task_spec

object | required

Parameters for input and output data and the task interface.

task_spec.input_spec

object | required

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

assignments_issuing_view_ config.title_template

string | required if

Required if assignments_issuing_type=MAP_SELECTOR.

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

public_instructions

string

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

private_comment

string

Comments that are only visible to the requester.

task_spec.output_spec | required

object

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_spec

object

Description of the task interface. The complete list of parameters is shown in the Task interface table.

assignments_issuing_type

string

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.

assignments_automerge_ enabled

boolean

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

max_active_assignments_ count

integer

The number of task suites the user can complete simultaneously (“Active” status).

quality_control

object

The quality control rule.

quality_control.configs[]

array of objects

Presets

localization_config

object

Block of translations to other languages.

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

localization_config.default_ language

string

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

localization_config. additional_languages[]

array of objects

Array of target languages.

localization_config. additional_languages[]. language

string

Target language.

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

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

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

localization_config. additional_languages[]. tb_view_spec

object

Translating the task interface.

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

Input and output data (the input_spec and output_spec parameters)

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

Parameter Overview
<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”).

required

boolean

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

hidden

boolean

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

For output data, always false.

min_value

float

Minimum value of the number.

max_value

float

Maximum value of the number.

allowed_values[]

array of strings, array of integers, array of floats

Allowed values.

min_length

integer

Minimum length of the string.

max_length

integer

Maximum length of the string.

current_location

string

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

Parameter Overview
<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”).

required

boolean

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

hidden

boolean

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

For output data, always false.

min_value

float

Minimum value of the number.

max_value

float

Maximum value of the number.

allowed_values[]

array of strings, array of integers, array of floats

Allowed values.

min_length

integer

Minimum length of the string.

max_length

integer

Maximum length of the string.

current_location

string

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

Task interface (the view_spec parameter)

Parameter Overview
markup

string | required

For more information, see the Requester's guide.

script

string | required

JavaScript interface for the task.

For more information, see the Requester's guide.

styles

string | required

CSS task interface.

For more information, see the Requester's guide.

settings

object | required

Whether to display standard UI elements in the task.

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:

  • tb — Template Builder.
localizationConfig

object

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

boolean

Show the timer. The default value is true.

settings.showTitle

boolean

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

settings.showInstructions

boolean

Show the Instructions button. The default value is true.

settings.showFullscreen

boolean

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

settings.showSubmit

boolean

Show the Next button. The default value is true.

settings.showSkip

boolean

Show the Skip button. The default value is true.

settings.showFinish

boolean

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

settings.showMessage

boolean

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

settings.showReward

boolean

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

Parameter Overview
markup

string | required

For more information, see the Requester's guide.

script

string | required

JavaScript interface for the task.

For more information, see the Requester's guide.

styles

string | required

CSS task interface.

For more information, see the Requester's guide.

settings

object | required

Whether to display standard UI elements in the task.

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:

  • tb — Template Builder.
localizationConfig

object

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

boolean

Show the timer. The default value is true.

settings.showTitle

boolean

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

settings.showInstructions

boolean

Show the Instructions button. The default value is true.

settings.showFullscreen

boolean

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

settings.showSubmit

boolean

Show the Next button. The default value is true.

settings.showSkip

boolean

Show the Skip button. The default value is true.

settings.showFinish

boolean

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

settings.showMessage

boolean

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

settings.showReward

boolean

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

Response

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

It includes:

Parameter Overview
owner

object

Parameters of the requester that created the project

owner.id

string

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).
id

string

Project ID (assigned automatically).

status

string

Status of the project:

  • ACTIVE — Active.

  • ARCHIVED — Archived.

created

string

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

Parameter Overview
owner

object

Parameters of the requester that created the project

owner.id

string

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).
id

string

Project ID (assigned automatically).

status

string

Status of the project:

  • ACTIVE — Active.

  • ARCHIVED — Archived.

created

string

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