API quick start

  1. Select an App
  2. Get information about the App
  3. Create an App project
  4. Create batch
  5. Wait for the READY status
  6. Start processing the batch
  7. Check the status of the project's items
  8. Parameters

Select an App

Request a list of Apps and select the one that fits your goals.

In this example we will run the “Text Classification” App.

GET /api/app/v0/apps
Host: https://toloka.yandex.ru
Authorization: OAuth <OAuth token>
Response
200 OK

{
    "content": [
        {
            "id": "qQAbNn1RPP5CyJRj5995",
            "name": "Image Classification",
            "image": "https://labs-images-testing.s3.yandex.net/large/4-NEW-img-classification.png",
            "description": "This solution helps you classify images. For example, you can divide them into categories or evaluate their quality.",
            "examples": [
                {
                    "name": "Was the driver wearing a seatbelt?"
                },
                {
                    "name": "Is there any illegal content/porn/profanity in the picture?"
                }
            ],
            "default_item_price": 0.07
        },
        {
            "id": "2eN4l59qL2xHB5b8Jqp6",
            "name": "Text Classification",
            "image": "https://labs-images-testing.s3.yandex.net/large/1-NEW-text-classification.png",
            "description": "This solution helps you classify texts. For example, you can divide reviews into categories or evaluate their grammatical correctness.",
            "examples": [
                {
                    "name": "Evaluate the sentiment of a review"
                },
                {
                    "name": "Select a category for an ad"
                }
            ],
            "default_item_price": 0.07
        }
    ],
    "has_more": false
}

Get information about the App

Request information about an App to check the specification parameters and input data. As a path parameter, specify the app_id of the selected App.

To view the App specification, set app_id=2eN4l59qL2xHB5b8Jqp6.

GET /api/app/v0/apps/2eN4l59qL2xHB5b8Jqp6
Host: https://toloka.yandex.ru
Authorization: OAuth <OAuth token>
Response
200 OK

{
    "id": "2eN4l59qL2xHB5b8Jqp6",
    "name": "Text Classification",
    "image": "https://labs-images-testing.s3.yandex.net/large/1-NEW-text-classification.png",
    "description": "This solution helps you classify texts. For example, you can divide reviews into categories or evaluate their grammatical correctness.",
    "param_spec": {
        "fields": {
            "type": "object",
            "required": [
                "default_language",
                "name",
                "option_multiple_choice",
                "option_other",
                "instruction_classes",
                "instruction_examples",
                "instruction_intro"
            ],
            "properties": {
                "name": {
                    "type": "string"
                },
                "option_other": {
                    "type": "boolean"
                },
                "default_language": {
                    "type": "string"
                },
                "instruction_intro": {
                    "type": "string"
                },
                "instruction_classes": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "required": [
                            "label",
                            "value",
                            "description"
                        ],
                        "properties": {
                            "label": {
                                "type": "string"
                            },
                            "value": {
                                "type": "string"
                            },
                            "description": {
                                "type": "string"
                            }
                        }
                    }
                },
                "instruction_examples": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "required": [
                            "text",
                            "label",
                            "description"
                        ],
                        "properties": {
                            "text": {
                                "type": "string"
                            },
                            "label": {
                                "type": "string"
                            },
                            "description": {
                                "type": "string"
                            }
                        }
                    }
                },
                "option_multiple_choice": {
                    "type": "boolean"
                }
            }
        }
    },
    "input_spec": {
        "id": {
            "type": "string",
            "required": false
        },
        "text": {
            "type": "string",
            "required": true
        }
    },
    "output_spec": {
        "result": {
            "type": "array_string",
            "required": true
        },
        "confidence": {
            "type": "float",
            "required": false
        }
    },
    "examples": [
        {
            "name": "Evaluate the sentiment of a review"
        },
        {
            "name": "Select a category for an ad"
        }
    ],
    "constraints_description": "For tasks with a single response, you can specify up to 12 classes, and for tasks with multiple responses, up to 8. The data file size must be 7 MB max.",
    "input_format_info": {
        "input_fields": [
            {
                "name": "text",
                "description": "Text"
            },
            {
                "name": "id",
                "description": "Optional identificator"
            }
        ],
        "format_description": "Prepare data in TSV-file: Single file for all your data"
    },
    "default_item_price": 0.07
}

Create an App project

Create an object named parameters. It has to match the json-scheme in the project's param_spec.

POST /api/app/v0/app-projects
Host: https://toloka.yandex.ru
Authorization: OAuth <OAuth token>
Request body
{
    "app_id": "2eN4l59qL2xHB5b8Jqp6",
    "name": "Text Classification",
    "parameters": {
        "name": "Text Classification",
        "instruction_classes": [
            {
                "label": "Correct",
                "value": "OK",
                "description": "There are no errors in the text"
            },
            {
                "label": "Mistake",
                "value": "BAD",
                "description": "There are errors in the text"
            }
        ],
        "instruction_examples": [
            {
                "text": "It’s raining.",
                "label": "Correct",
                "description": "There are no errors in the text"
            },
            {
                "text": "There is my hause.",
                "label": "Mistake",
                "description": "There are errors in the text"
            }
        ],
        "default_language": "en",
        "option_other": false,
        "option_multiple_choice": false,
        "instruction_intro": "Are there any errors in the text"
    }
}
Response
200 OK

{
    "id": "6Vv8kdlrjLYu7ZgPdezj",
    "app_id": "2eN4l59qL2xHB5b8Jqp6",
    "parent_app_project_id": "",
    "status": "CREATING",
    "created": "2021-10-03T09:19:44.378888",
    "name": "Text Classification",
    "parameters": {
        "name": "Text Classification",
        "option_other": false,
        "default_language": "en",
        "instruction_intro": "Are there any errors in the text",
        "instruction_classes": [
            {
                "label": "Correct",
                "value": "OK",
                "description": "There are no errors in the text"
            },
            {
                "label": "Mistake",
                "value": "BAD",
                "description": "There are errors in the text"
            }
        ],
        "instruction_examples": [
            {
                "text": "It’s raining.",
                "label": "Correct",
                "description": "There are no errors in the text"
            },
            {
                "text": "There is my hause.",
                "label": "Mistake",
                "description": "There are errors in the text"
            }
        ],
        "option_multiple_choice": false
    },
    "errors": [],
    "item_price": 0.0700,
    "read_only": false
}

Now you have the app_project_id of your project. In this case, it's 6Vv8kdlrjLYu7ZgPdezj.

Create batch

Create a batch and add items to it. You can see the input data names and types in the project's input_spec. In our example, there are id and text, both of string type.

POST /api/app/v0/app-projects/6Vv8kdlrjLYu7ZgPdezj/batches
Host: https://toloka.yandex.ru
Authorization: OAuth <OAuth token>
Request body
{
  "items": [
   {
       "id": "1",
       "text": "Kate likes dogs."
   },
   {
       "id": "2",
       "text": "I don’t like hooney."
   }
  ]
}
Response
200 OK

{
    "id": "z1Qy7aryrj9har9yKdY0",
    "app_project_id": "6Vv8kdlrjLYu7ZgPdezj",
    "status": "NEW",
    "name": "",
    "items_count": 2,
    "item_price": 0.0700,
    "cost": 0.1400,
    "created_at": "2021-10-03T09:49:14.028",
    "read_only": false
}

Wait for the READY status

At this stage, you need to wait until the project's status changes to READY.

To find out the status of the project, use request:

GET https://toloka.yandex.ru/api/app/v0/app-projects/6Vv8kdlrjLYu7ZgPdezj

Start processing the batch

POST /api/app/v0/app-projects/6Vv8kdlrjLYu7ZgPdezj/batches/z1Qy7aryrj9har9yKdY0/start
Host: https://toloka.yandex.ru
Authorization: OAuth <OAuth token>

Check the status of the project's items

Regularly check the items status:

  • NEW: A new item.
  • PROCESSING: The item is being processed.
  • COMPLETED: Item processing is complete.

The expected status is COMPLETED.

GET /api/app/v0/app-projects/6Vv8kdlrjLYu7ZgPdezj/items?%26batch_id%3D=z1Qy7aryrj9har9yKdY0
Host: https://toloka.yandex.ru
Authorization: OAuth <OAuth token>
Response
200 OK

{
    "content": [
        {
            "id": "QlvdZj5d53QHj5Nvx9Vd",
            "app_project_id": "6Vv8kdlrjLYu7ZgPdezj",
            "batch_id": "z1Qy7aryrj9har9yKdY0",
            "status": "COMPLETED",
            "input_data": {
                "id": "1",
                "text": "Kate likes dogs."
            },
            "output_data": {
                "text": "Kate likes dogs.",
                "result": [
                    "OK"
                ],
                "confidence": 0.9998542274
            },
            "errors": [],
            "created_at": "2021-10-03T09:49:14.028",
            "started_at": "2021-10-03T10:10:27.561182",
            "finished_at": "2021-10-03T11:24:46.818213"
        },
        {
            "id": "nbeya74y4PpU1NkbaxA4",
            "app_project_id": "6Vv8kdlrjLYu7ZgPdezj",
            "batch_id": "z1Qy7aryrj9har9yKdY0",
            "status": "COMPLETED",
            "input_data": {
                "id": "2",
                "text": "I don’t like hooney."
            },
            "output_data": {
                "text": "I don’t like hooney.",
                "result": [
                    "BAD"
                ],
                "confidence": 0.9998542274
            },
            "errors": [],
            "created_at": "2021-10-03T09:49:14.028",
            "started_at": "2021-10-03T10:10:27.561182",
            "finished_at": "2021-10-03T11:24:47.704265"
        }
    ],
    "has_more": false
}

Parameters

Parameter Overview
app_project_id

string

App project ID.

batch_id

string

Batch ID.

Parameter Overview
app_project_id

string

App project ID.

batch_id

string

Batch ID.

Contact support