API quick start

Choose a solution

Request a list of solutions and choose the one that fits your goals.

In this example, we'll run the Text Classification solution.

First, get the list of the available solutions to find the ID of the Text Classification solution.

curl -X GET 'https://toloka.dev/api/app/v0/apps' \
     -H 'Authorization: ApiKey PlaceYourRealApiKey_Here'

Response

Get information about the solution

Request information about the solution to check the spec parameters and input data.

For example, to view the Text Classification solution specs, specify its id in the request: 2eN4l59qL2xHB5b8Jqp6.

curl -X GET 'https://toloka.dev/api/app/v0/apps/2eN4l59qL2xHB5b8Jqp6' \
     -H 'Authorization: ApiKey PlaceYourRealApiKey_Here'

Response

Create a project

Create an object named parameters. It should match the JSON schema in the solution's param_spec.

curl -X POST 'https://toloka.dev/api/app/v0/app-projects' \
     -H 'Authorization: ApiKey PlaceYourRealApiKey_Here' \
     -H 'Content-Type: application/json' \
     -d '{
           "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

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

The project gets the CREATING status. You don't have to wait until it's moderated and can immediately start uploading task items.

Create a batch for labeling

Let's create a batch and upload task items to it. We'll use the schema from the project template. It's specified in the input_spec parameter. In this case, it's id and text.

curl -X POST 'https://toloka.dev/api/app/v0/app-projects/6Vv8kdlrjLYu7ZgPdezj/batches' \
     -H 'Authorization: ApiKey PlaceYourRealApiKey_Here' \
     -H 'Content-Type: application/json' \
     -d '{
           "items": [
             {
               "id": "1",
               "text": "Kate likes dogs."
             },
             {
               "id": "2",
               "text": "I don’t like honey."
             }
           ]
         }'

Response

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 the request:

curl -X GET 'https://toloka.dev/api/app/v0/app-projects/6Vv8kdlrjLYu7ZgPdezj' \
     -H 'Authorization: ApiKey PlaceYourRealApiKey_Here'

Start processing the batch

curl -X POST 'https://toloka.dev/api/app/v0/app-projects/6Vv8kdlrjLYu7ZgPdezj/batches/z1Qy7aryrj9har9yKdY0/start' \
     -H 'Authorization: ApiKey PlaceYourRealApiKey_Here'

Check the status of the project's task items

Check the status of the task items from time to time:

NEW: A new object.
PROCESSING: The object is being processed.
COMPLETED: Object processing is complete.

The expected status is COMPLETED.

curl -X GET 'https://toloka.dev/api/app/v0/app-projects/6Vv8kdlrjLYu7ZgPdezj/items?batch_id=z1Qy7aryrj9har9yKdY0' \
     -H 'Authorization: ApiKey PlaceYourRealApiKey_Here'

Response

Parameters

Parameter	Overview
app_project_id	string Project ID.
batch_id	string Batch ID.

Contact support

Last updated: July 5, 2023

Bespoke API

Accessing the API API quick start Stream processing of task items Iterating results

Reference

Overview

Bespoke

Bespoke-project

Item

Batch