Upload individual tasks or batches and group them into task suites, with overlap settings, known solutions for quality control, and asynchronous batch creation for large volumes.
openapi: 3.0.1
info:
title: Toloka API
description: >-
The Toloka API lets you build scalable, fully automated human-in-the-loop
data-labeling and human-data pipelines on the Toloka crowdsourcing platform.
You manage projects, pools, training pools, tasks, task suites, and
assignments; collect and review Toloker responses; issue bonuses; manage
skills and attachments; track asynchronous operations; and subscribe to
event webhooks. Most write operations that touch large batches of tasks or
suites run asynchronously and return an Operation you poll to completion.
termsOfService: https://toloka.ai/legal/terms_of_service/
contact:
name: Toloka Support
email: support@toloka.ai
version: '1.0'
servers:
- url: https://api.toloka.ai/api
description: Toloka production API (api.toloka.ai)
- url: https://toloka.dev/api
description: Toloka production API (toloka.dev)
security:
- OAuthToken: []
tags:
- name: Projects
description: Create and manage projects that define task interface and instructions.
- name: Pools
description: Create, configure, open, and close pools of tasks for Tolokers.
- name: Training
description: Create and manage training pools used to qualify Tolokers.
- name: Tasks
description: Upload and retrieve individual tasks.
- name: Task Suites
description: Upload and retrieve task suites (groups of tasks shown together).
- name: Assignments
description: Retrieve Toloker responses and accept or reject completed assignments.
- name: User Bonuses
description: Issue bonus payments to Tolokers.
- name: User Restrictions
description: Restrict Tolokers from a pool, project, or all projects.
- name: Skills
description: Create and manage skills assigned to Tolokers.
- name: Attachments
description: Retrieve files Tolokers attached to their assignments.
- name: Operations
description: Track the status of asynchronous operations.
- name: Webhook Subscriptions
description: Subscribe to platform events delivered to your endpoint.
paths:
/v1/projects:
get:
operationId: getProjects
tags:
- Projects
summary: Get the list of projects
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/SortField'
- name: status
in: query
schema:
type: string
enum: [ACTIVE, ARCHIVED]
description: Filter projects by status.
responses:
'200':
description: A page of projects.
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectSearchResult'
post:
operationId: createProject
tags:
- Projects
summary: Create a project
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
responses:
'201':
description: The created project.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
/v1/projects/{id}:
get:
operationId: getProject
tags:
- Projects
summary: Get a project
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'200':
description: The requested project.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
put:
operationId: updateProject
tags:
- Projects
summary: Edit a project
parameters:
- $ref: '#/components/parameters/PathId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
responses:
'200':
description: The updated project.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
/v1/projects/{id}/archive:
post:
operationId: archiveProject
tags:
- Projects
summary: Archive a project
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'202':
description: An asynchronous archive operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
/v1/pools:
get:
operationId: getPools
tags:
- Pools
summary: Get the list of pools
parameters:
- name: project_id
in: query
schema:
type: string
description: Return pools belonging to this project.
- name: status
in: query
schema:
type: string
enum: [OPEN, CLOSED, ARCHIVED, LOCKED]
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/SortField'
responses:
'200':
description: A page of pools.
content:
application/json:
schema:
$ref: '#/components/schemas/PoolSearchResult'
post:
operationId: createPool
tags:
- Pools
summary: Create a pool
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pool'
responses:
'201':
description: The created pool.
content:
application/json:
schema:
$ref: '#/components/schemas/Pool'
/v1/pools/{id}:
get:
operationId: getPool
tags:
- Pools
summary: Get a pool
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'200':
description: The requested pool.
content:
application/json:
schema:
$ref: '#/components/schemas/Pool'
put:
operationId: updatePool
tags:
- Pools
summary: Edit a pool
parameters:
- $ref: '#/components/parameters/PathId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pool'
responses:
'200':
description: The updated pool.
content:
application/json:
schema:
$ref: '#/components/schemas/Pool'
/v1/pools/{id}/open:
post:
operationId: openPool
tags:
- Pools
summary: Open a pool
description: Start showing the pool's tasks to Tolokers.
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'202':
description: An asynchronous open operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
/v1/pools/{id}/close:
post:
operationId: closePool
tags:
- Pools
summary: Close a pool
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'202':
description: An asynchronous close operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
/v1/pools/{id}/archive:
post:
operationId: archivePool
tags:
- Pools
summary: Archive a pool
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'202':
description: An asynchronous archive operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
/v1/trainings:
get:
operationId: getTrainings
tags:
- Training
summary: Get the list of training pools
parameters:
- name: project_id
in: query
schema:
type: string
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of training pools.
content:
application/json:
schema:
$ref: '#/components/schemas/TrainingSearchResult'
post:
operationId: createTraining
tags:
- Training
summary: Create a training pool
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Training'
responses:
'201':
description: The created training pool.
content:
application/json:
schema:
$ref: '#/components/schemas/Training'
/v1/trainings/{id}/open:
post:
operationId: openTraining
tags:
- Training
summary: Open a training pool
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'202':
description: An asynchronous open operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
/v1/tasks:
get:
operationId: getTasks
tags:
- Tasks
summary: Get the list of tasks
parameters:
- name: pool_id
in: query
schema:
type: string
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of tasks.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskSearchResult'
post:
operationId: createTasks
tags:
- Tasks
summary: Create tasks
description: >-
Create one task or a batch of tasks. Up to 100,000 tasks per minute and
2,000,000 tasks per day. With async_mode=true an Operation is returned.
parameters:
- $ref: '#/components/parameters/AsyncMode'
- name: allow_defaults
in: query
schema:
type: boolean
description: Use pool defaults for overlap when not set on a task.
- name: skip_invalid_items
in: query
schema:
type: boolean
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Task'
- type: array
items:
$ref: '#/components/schemas/Task'
responses:
'201':
description: The created task(s).
content:
application/json:
schema:
$ref: '#/components/schemas/TaskBatchResult'
'202':
description: An asynchronous task-creation operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
/v1/tasks/{id}:
get:
operationId: getTask
tags:
- Tasks
summary: Get a task
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'200':
description: The requested task.
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
patch:
operationId: patchTask
tags:
- Tasks
summary: Edit a task
description: Change a task's overlap or infinite_overlap.
parameters:
- $ref: '#/components/parameters/PathId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
overlap:
type: integer
infinite_overlap:
type: boolean
responses:
'200':
description: The updated task.
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
/v1/task-suites:
get:
operationId: getTaskSuites
tags:
- Task Suites
summary: Get the list of task suites
parameters:
- name: pool_id
in: query
schema:
type: string
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of task suites.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskSuiteSearchResult'
post:
operationId: createTaskSuites
tags:
- Task Suites
summary: Create task suites
description: Create one or many task suites. Supports async_mode for batches.
parameters:
- $ref: '#/components/parameters/AsyncMode'
- name: skip_invalid_items
in: query
schema:
type: boolean
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/TaskSuite'
- type: array
items:
$ref: '#/components/schemas/TaskSuite'
responses:
'201':
description: The created task suite(s).
content:
application/json:
schema:
$ref: '#/components/schemas/TaskSuiteBatchResult'
'202':
description: An asynchronous task-suite-creation operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
/v1/task-suites/{id}:
get:
operationId: getTaskSuite
tags:
- Task Suites
summary: Get a task suite
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'200':
description: The requested task suite.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskSuite'
/v1/assignments:
get:
operationId: getAssignments
tags:
- Assignments
summary: Get the list of assignments
description: Retrieve Toloker responses, optionally filtered by pool and status.
parameters:
- name: pool_id
in: query
schema:
type: string
- name: status
in: query
schema:
type: string
enum: [ACTIVE, SUBMITTED, ACCEPTED, REJECTED, SKIPPED, EXPIRED]
- name: user_id
in: query
schema:
type: string
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of assignments.
content:
application/json:
schema:
$ref: '#/components/schemas/AssignmentSearchResult'
/v1/assignments/{id}:
get:
operationId: getAssignment
tags:
- Assignments
summary: Get an assignment
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'200':
description: The requested assignment.
content:
application/json:
schema:
$ref: '#/components/schemas/Assignment'
patch:
operationId: patchAssignment
tags:
- Assignments
summary: Accept or reject an assignment
description: Set status to ACCEPTED or REJECTED, with a public comment for the Toloker.
parameters:
- $ref: '#/components/parameters/PathId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- status
- public_comment
properties:
status:
type: string
enum: [ACCEPTED, REJECTED]
public_comment:
type: string
responses:
'200':
description: The updated assignment.
content:
application/json:
schema:
$ref: '#/components/schemas/Assignment'
/v1/user-bonuses:
post:
operationId: createUserBonuses
tags:
- User Bonuses
summary: Issue bonuses to Tolokers
parameters:
- $ref: '#/components/parameters/AsyncMode'
- name: skip_invalid_items
in: query
schema:
type: boolean
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UserBonus'
- type: array
items:
$ref: '#/components/schemas/UserBonus'
responses:
'201':
description: The issued bonus(es).
content:
application/json:
schema:
$ref: '#/components/schemas/UserBonus'
'202':
description: An asynchronous bonus operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
/v1/user-restrictions:
post:
operationId: createUserRestriction
tags:
- User Restrictions
summary: Restrict a Toloker
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserRestriction'
responses:
'201':
description: The created restriction.
content:
application/json:
schema:
$ref: '#/components/schemas/UserRestriction'
/v1/skills:
get:
operationId: getSkills
tags:
- Skills
summary: Get the list of skills
parameters:
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of skills.
content:
application/json:
schema:
$ref: '#/components/schemas/SkillSearchResult'
post:
operationId: createSkill
tags:
- Skills
summary: Create a skill
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Skill'
responses:
'201':
description: The created skill.
content:
application/json:
schema:
$ref: '#/components/schemas/Skill'
/v1/user-skills:
post:
operationId: setUserSkill
tags:
- Skills
summary: Assign a skill value to a Toloker
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- user_id
- skill_id
- value
properties:
user_id:
type: string
skill_id:
type: string
value:
type: number
responses:
'201':
description: The assigned user skill.
content:
application/json:
schema:
$ref: '#/components/schemas/UserSkill'
/v1/attachments:
get:
operationId: getAttachments
tags:
- Attachments
summary: Get the list of attachments
parameters:
- name: pool_id
in: query
schema:
type: string
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of attachment metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentSearchResult'
/v1/attachments/{id}:
get:
operationId: getAttachment
tags:
- Attachments
summary: Get attachment metadata
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'200':
description: The requested attachment metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/Attachment'
/v1/attachments/{id}/download:
get:
operationId: downloadAttachment
tags:
- Attachments
summary: Download an attachment
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'200':
description: The attachment file.
content:
application/octet-stream:
schema:
type: string
format: binary
/v1/operations:
get:
operationId: getOperations
tags:
- Operations
summary: Get the list of operations
parameters:
- name: type
in: query
schema:
type: string
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of operations.
content:
application/json:
schema:
$ref: '#/components/schemas/OperationSearchResult'
/v1/operations/{id}:
get:
operationId: getOperation
tags:
- Operations
summary: Get an operation
description: Poll the status of an asynchronous operation.
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'200':
description: The requested operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
/v1/webhook-subscriptions:
get:
operationId: getWebhookSubscriptions
tags:
- Webhook Subscriptions
summary: Get the list of webhook subscriptions
parameters:
- name: pool_id
in: query
schema:
type: string
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of webhook subscriptions.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscriptionSearchResult'
put:
operationId: upsertWebhookSubscriptions
tags:
- Webhook Subscriptions
summary: Create webhook subscriptions
description: >-
Subscribe to platform events (e.g. POOL_CLOSED, ASSIGNMENT_CREATED,
ASSIGNMENT_SUBMITTED, ASSIGNMENT_APPROVED, ASSIGNMENT_REJECTED). Add a
secret_key to receive a signed Toloka-Signature header (HMAC SHA256).
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/WebhookSubscription'
- type: array
items:
$ref: '#/components/schemas/WebhookSubscription'
responses:
'201':
description: The created subscription(s).
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscriptionBatchResult'
/v1/webhook-subscriptions/{id}:
get:
operationId: getWebhookSubscription
tags:
- Webhook Subscriptions
summary: Get a webhook subscription
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'200':
description: The requested subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscription'
delete:
operationId: deleteWebhookSubscription
tags:
- Webhook Subscriptions
summary: Delete a webhook subscription
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'204':
description: The subscription was deleted.
components:
securitySchemes:
OAuthToken:
type: apiKey
in: header
name: Authorization
description: >-
Pass your Toloka OAuth token (or API key) in the Authorization header
as `Authorization: OAuth <token>` (legacy) or
`Authorization: ApiKey <key>`.
parameters:
PathId:
name: id
in: path
required: true
schema:
type: string
description: Object identifier.
Limit:
name: limit
in: query
schema:
type: integer
default: 50
maximum: 100000
description: Maximum number of results per page.
SortField:
name: sort
in: query
schema:
type: string
description: Comma-separated sort fields; prefix with `-` for descending.
AsyncMode:
name: async_mode
in: query
schema:
type: boolean
default: false
description: When true, the request runs asynchronously and returns an Operation.
schemas:
Project:
type: object
properties:
id:
type: string
readOnly: true
public_name:
type: string
public_description:
type: string
private_comment:
type: string
task_spec:
$ref: '#/components/schemas/TaskSpec'
assignments_issuing_type:
type: string
enum: [AUTOMATED, MAP_SELECTOR]
status:
type: string
enum: [ACTIVE, ARCHIVED]
readOnly: true
created:
type: string
format: date-time
readOnly: true
required:
- public_name
- public_description
- task_spec
TaskSpec:
type: object
description: Defines the task input/output schema and the Toloker view.
properties:
input_spec:
type: object
additionalProperties: true
output_spec:
type: object
additionalProperties: true
view_spec:
type: object
additionalProperties: true
Pool:
type: object
properties:
id:
type: string
readOnly: true
project_id:
type: string
private_name:
type: string
may_contain_adult_content:
type: boolean
reward_per_assignment:
type: number
description: Payment in US dollars for one completed task suite.
assignment_max_duration_seconds:
type: integer
defaults:
type: object
properties:
default_overlap_for_new_task_suites:
type: integer
default_overlap_for_new_tasks:
type: integer
will_expire:
type: string
format: date-time
auto_close_after_complete_delay_seconds:
type: integer
filter:
type: object
additionalProperties: true
description: Conditions controlling which Tolokers can access the pool.
quality_control:
type: object
additionalProperties: true
status:
type: string
enum: [OPEN, CLOSED, ARCHIVED, LOCKED]
readOnly: true
created:
type: string
format: date-time
readOnly: true
required:
- project_id
- private_name
- reward_per_assignment
- assignment_max_duration_seconds
- defaults
- will_expire
Training:
type: object
properties:
id:
type: string
readOnly: true
project_id:
type: string
private_name:
type: string
may_contain_adult_content:
type: boolean
assignment_max_duration_seconds:
type: integer
mix_tasks_in_creation_order:
type: boolean
shuffle_tasks_in_task_suite:
type: boolean
training_tasks_in_task_suite_count:
type: integer
task_suites_required_to_pass:
type: integer
retry_training_after_days:
type: integer
status:
type: string
enum: [OPEN, CLOSED, ARCHIVED, LOCKED]
readOnly: true
required:
- project_id
- private_name
Task:
type: object
properties:
id:
type: string
readOnly: true
pool_id:
type: string
input_values:
type: object
additionalProperties: true
description: Input data matching the project's input_spec.
known_solutions:
type: array
items:
type: object
properties:
output_values:
type: object
additionalProperties: true
correctness_weight:
type: number
overlap:
type: integer
infinite_overlap:
type: boolean
created:
type: string
format: date-time
readOnly: true
required:
- pool_id
- input_values
TaskSuite:
type: object
properties:
id:
type: string
readOnly: true
pool_id:
type: string
tasks:
type: array
items:
$ref: '#/components/schemas/Task'
overlap:
type: integer
infinite_overlap:
type: boolean
created:
type: string
format: date-time
readOnly: true
required:
- pool_id
- tasks
Assignment:
type: object
properties:
id:
type: string
readOnly: true
task_suite_id:
type: string
pool_id:
type: string
user_id:
type: string
status:
type: string
enum: [ACTIVE, SUBMITTED, ACCEPTED, REJECTED, SKIPPED, EXPIRED]
tasks:
type: array
items:
$ref: '#/components/schemas/Task'
solutions:
type: array
items:
type: object
properties:
output_values:
type: object
additionalProperties: true
reward:
type: number
public_comment:
type: string
created:
type: string
format: date-time
submitted:
type: string
format: date-time
accepted:
type: string
format: date-time
UserBonus:
type: object
properties:
id:
type: string
readOnly: true
user_id:
type: string
amount:
type: number
description: Bonus amount in US dollars.
assignment_id:
type: string
private_comment:
type: string
public_title:
type: object
additionalProperties:
type: string
public_message:
type: object
additionalProperties:
type: string
without_message:
type: boolean
required:
- user_id
- amount
UserRestriction:
type: object
properties:
id:
type: string
readOnly: true
user_id:
type: string
scope:
type: string
enum: [ALL_PROJECTS, PROJECT, POOL, SYSTEM]
project_id:
type: string
pool_id:
type: string
private_comment:
type: string
will_expire:
type: string
format: date-time
required:
- user_id
- scope
Skill:
type: object
properties:
id:
type: string
readOnly: true
name:
type: string
private_comment:
type: string
hidden:
type: boolean
skill_ttl_hours:
type: integer
training:
type: boolean
public_requester_description:
type: object
additionalProperties:
type: string
created:
type: string
format: date-time
readOnly: true
required:
- name
UserSkill:
type: object
properties:
id:
type: string
readOnly: true
user_id:
type: string
skill_id:
type: string
value:
type: number
created:
type: string
format: date-time
readOnly: true
Attachment:
type: object
properties:
id:
type: string
readOnly: true
atta
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/toloka/refs/heads/main/openapi/toloka-openapi.yml