The Label Studio REST API supports the full data labeling lifecycle: managing projects, tasks, annotations, annotation reviews, comments, predictions, ML backends, prompts, storage (S3 / Azure / GCS), webhooks, users, organizations, and analytics. The OpenAPI 3.1 specification is published by HumanSignal at https://api.labelstud.io/openapi.yaml.
openapi: 3.1.0
info:
title: API Reference
version: 1.0.0
paths:
/api/activity-logs/:
get:
operationId: list
summary: ✨ Get activity logs
description: |-
<Card href="https://humansignal.com/goenterprise">
<img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/>
<p style="margin-top: 10px; font-size: 14px;">
This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)
</p>
</Card>
Retrieve activity logs filtered by workspace, project, user, HTTP method, date range or search query.
tags:
- subpackage_activityLogs
parameters:
- name: end_date
in: query
description: End date/time (ISO-8601) for log filtering.
required: false
schema:
type: string
- name: method
in: query
description: HTTP request method used in the log.
required: false
schema:
$ref: '#/components/schemas/ApiActivityLogsGetParametersMethod'
- name: ordering
in: query
description: Which field to use when ordering the results.
required: false
schema:
type: string
- name: page
in: query
description: '[or "start"] Current page index.'
required: false
schema:
type: integer
- name: page_size
in: query
description: '[or "length"] Logs per page, use -1 to obtain all logs (might be slow).'
required: false
schema:
type: integer
- name: project
in: query
description: Project ID to filter logs.
required: false
schema:
type: integer
- name: search
in: query
description: Search expression using "AND"/"OR" to filter by request URL.
required: false
schema:
type: string
- name: start_date
in: query
description: Start date/time (ISO-8601) for log filtering.
required: false
schema:
type: string
- name: user
in: query
description: User ID to filter logs.
required: false
schema:
type: integer
- name: workspace
in: query
description: Workspace owner ID to filter logs.
required: false
schema:
type: integer
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: Activity logs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ActivityLogResponse'
'404':
description: No more logs found
content:
application/json:
schema:
description: Any type
/api/annotation-history/:
get:
operationId: list
summary: ✨ List all annotation history items for annotation
description: >-
<Card href="https://humansignal.com/goenterprise">
<img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/>
<p style="margin-top: 10px; font-size: 14px;">
This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)
</p>
</Card>
List annotation history items for an annotation. Annotation history logs all actions performed with annotations,
such as: imports, submits, updates, reviews, and more. Users can view annotation history items in the Annotation
History panel during labeling.
tags:
- subpackage_annotationHistory
parameters:
- name: annotation
in: query
description: Annotation ID to get annotation history items for.
required: false
schema:
type: integer
- name: ordering
in: query
description: Which field to use when ordering the results.
required: false
schema:
type: string
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AnnotationHistory'
delete:
operationId: delete
summary: ✨ Delete annotation history items
description: >-
<Card href="https://humansignal.com/goenterprise">
<img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/>
<p style="margin-top: 10px; font-size: 14px;">
This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)
</p>
</Card>
Delete all annotation history items for a specific annotation, task or project. This method is available only
for users with administrator roles.
tags:
- subpackage_annotationHistory
parameters:
- name: annotation
in: query
description: Annotation ID to delete annotation history items for.
required: false
schema:
type: integer
- name: project
in: query
description: Project ID to delete annotation history items for.
required: false
schema:
type: integer
- name: task
in: query
description: Task ID to delete annotation history items for.
required: false
schema:
type: integer
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: Returns a dict containing the count of removed items.
content:
application/json:
schema:
$ref: '#/components/schemas/annotation_history_delete_Response_200'
/api/annotation-history/{id}/:
get:
operationId: retrieve
summary: ✨ Retrieve a single annotation history item (full result for hydration)
description: >-
<Card href="https://humansignal.com/goenterprise">
<img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/>
<p style="margin-top: 10px; font-size: 14px;">
This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)
</p>
</Card>
Get one annotation history item by ID with full result. Used when FIT-720 lazy load is on and the user clicks a
stubbed history item to hydrate it.
tags:
- subpackage_annotationHistory
parameters:
- name: id
in: path
required: true
schema:
type: integer
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationHistory'
/api/projects/{id}/annotation-history/:
get:
operationId: list-for-project
summary: ✨ List annotation history items for project
description: |-
<Card href="https://humansignal.com/goenterprise">
<img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/>
<p style="margin-top: 10px; font-size: 14px;">
This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)
</p>
</Card>
List all annotation history items for the project with pagination.
tags:
- subpackage_annotationHistory
parameters:
- name: id
in: path
required: true
schema:
type: integer
- name: page
in: query
description: A page number within the paginated result set.
required: false
schema:
type: integer
- name: page_size
in: query
description: Number of results to return per page.
required: false
schema:
type: integer
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedAnnotationHistoryList'
/api/annotation-reviews/:
get:
operationId: list
summary: ✨ List reviews
description: |-
<Card href="https://humansignal.com/goenterprise">
<img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/>
<p style="margin-top: 10px; font-size: 14px;">
This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)
</p>
</Card>
List all reviews for a specific annotation ID. Only allowed for organizations with reviewing features enabled.
tags:
- subpackage_annotationReviews
parameters:
- name: annotation
in: query
required: false
schema:
type: integer
- name: annotation__task__project
in: query
required: false
schema:
type: integer
- name: ordering
in: query
description: Which field to use when ordering the results.
required: false
schema:
type: string
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AnnotationReview'
post:
operationId: create
summary: ✨ Create review
description: |-
<Card href="https://humansignal.com/goenterprise">
<img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/>
<p style="margin-top: 10px; font-size: 14px;">
This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)
</p>
</Card>
Create a review for a specific annotation ID. Only allowed for organizations with reviewing features enabled.
tags:
- subpackage_annotationReviews
parameters:
- name: async_postprocess
in: query
description: Whether to postprocess the review asynchronously.
required: false
schema:
type: boolean
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationReview'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationReviewRequest'
/api/annotation-reviews/{id}/:
get:
operationId: get
summary: ✨ Get review
description: >-
<Card href="https://humansignal.com/goenterprise">
<img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/>
<p style="margin-top: 10px; font-size: 14px;">
This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)
</p>
</Card>
Retrieve a specific review by ID for an annotation. Only allowed for organizations with reviewing features
enabled.
tags:
- subpackage_annotationReviews
parameters:
- name: id
in: path
description: A unique integer value identifying this annotation review.
required: true
schema:
type: integer
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationReview'
delete:
operationId: delete
summary: ✨ Delete review
description: |-
<Card href="https://humansignal.com/goenterprise">
<img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/>
<p style="margin-top: 10px; font-size: 14px;">
This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)
</p>
</Card>
Delete a review by ID. Only allowed for organizations with reviewing features enabled.
tags:
- subpackage_annotationReviews
parameters:
- name: id
in: path
description: A unique integer value identifying this annotation review.
required: true
schema:
type: integer
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: Successful response
patch:
operationId: update
summary: ✨ Update review
description: |-
<Card href="https://humansignal.com/goenterprise">
<img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/>
<p style="margin-top: 10px; font-size: 14px;">
This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)
</p>
</Card>
Update a specific review by ID. Only allowed for organizations with reviewing features enabled.
tags:
- subpackage_annotationReviews
parameters:
- name: id
in: path
description: A unique integer value identifying this annotation review.
required: true
schema:
type: integer
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationReview'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedAnnotationReviewRequest'
/api/annotations/bulk-delete/:
post:
operationId: delete-bulk
summary: Bulk delete annotations by IDs
description: >-
Delete multiple annotations by their IDs. The deletion is processed synchronously. Returns the count of deleted
annotations in the response.
tags:
- subpackage_annotations
parameters:
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: Annotations deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/annotations_delete_bulk_Response_200'
'400':
description: Bad request - validation errors
content:
application/json:
schema:
description: Any type
'403':
description: Forbidden - insufficient permissions
content:
application/json:
schema:
description: Any type
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationBulkDeleteRequest'
/api/annotations/bulk/:
post:
operationId: create-bulk
summary: Bulk create annotations
description: Create multiple annotations at once
tags:
- subpackage_annotations
parameters:
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'201':
description: Bulk annotations created successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiAnnotationsBulkPostResponsesContentApplicationJsonSchemaItems'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationBulkSerializerWithSelectedItemsRequest'
/api/annotations/{id}/:
get:
operationId: get
summary: Get annotation by its ID
description: Retrieve a specific annotation for a task using the annotation result ID.
tags:
- subpackage_annotations
parameters:
- name: id
in: path
required: true
schema:
type: integer
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: Retrieved annotation
content:
application/json:
schema:
$ref: '#/components/schemas/Annotation'
delete:
operationId: delete
summary: Delete annotation
description: Delete an annotation. This action can't be undone!
tags:
- subpackage_annotations
parameters:
- name: id
in: path
required: true
schema:
type: integer
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: Successful response
patch:
operationId: update
summary: Update annotation
description: Update existing attributes on an annotation.
tags:
- subpackage_annotations
parameters:
- name: id
in: path
required: true
schema:
type: integer
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: Updated annotation
content:
application/json:
schema:
$ref: '#/components/schemas/Annotation'
requestBody:
content:
application/json:
schema:
type: object
properties:
completed_by:
type: integer
description: User ID of the person who created this annotation
ground_truth:
type: boolean
description: This annotation is a Ground Truth
lead_time:
type: number
format: double
description: How much time it took to annotate the task (in seconds)
project:
type: integer
description: Project ID for this annotation
result:
type: array
items:
$ref: '#/components/schemas/ApiAnnotationsIdPatchRequestBodyContentApplicationJsonSchemaResultItems'
description: >-
Labeling result in JSON format. Read more about the format in [the Label Studio
documentation.](https://labelstud.io/guide/task_format)
task:
type: integer
description: Corresponding task for this annotation
updated_by:
type: integer
description: Last user who updated this annotation
was_cancelled:
type: boolean
description: User skipped the task
/api/tasks/{id}/annotations/:
get:
operationId: list
summary: Get all task annotations
description: List all annotations for a task.
tags:
- subpackage_annotations
parameters:
- name: id
in: path
description: Task ID
required: true
schema:
type: integer
- name: ordering
in: query
description: Which field to use when ordering the results.
required: false
schema:
type: string
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: Annotation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Annotation'
post:
operationId: create
summary: Create annotation
description: |2-
Add annotations to a task like an annotator does. The content of the result field depends on your
labeling configuration. For example, send the following data as part of your POST
request to send an empty annotation with the ID of the user who completed the task:
```json
{
"result": {},
"was_cancelled": true,
"ground_truth": true,
"lead_time": 0,
"task": 0
"completed_by": 123
}
```
tags:
- subpackage_annotations
parameters:
- name: id
in: path
description: Task ID
required: true
schema:
type: integer
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'201':
description: Created annotation
content:
application/json:
schema:
$ref: '#/components/schemas/Annotation'
requestBody:
content:
application/json:
schema:
type: object
properties:
completed_by:
type: integer
description: User ID of the person who created this annotation
ground_truth:
type: boolean
description: This annotation is a Ground Truth
lead_time:
type: number
format: double
description: How much time it took to annotate the task (in seconds)
project:
type: integer
description: Project ID for this annotation
result:
type: array
items:
$ref: '#/components/schemas/ApiTasksIdAnnotationsPostRequestBodyContentApplicationJsonSchemaResultItems'
description: >-
Labeling result in JSON format. Read more about the format in [the Label Studio
documentation.](https://labelstud.io/guide/task_format)
task:
type: integer
description: Corresponding task for this annotation
updated_by:
type: integer
description: Last user who updated this annotation
was_cancelled:
type: boolean
description: User skipped the task
/api/billing/info:
get:
operationId: info
summary: ✨ Get billing info
description: |-
<Card href="https://humansignal.com/goenterprise">
<img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/>
<p style="margin-top: 10px; font-size: 14px;">
This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)
</p>
</Card>
Retrieve billing checks and feature flags for the active organization.
tags:
- subpackage_billing
parameters:
- name: Authorization
in: header
description: >-
The token (or API key) must be passed as a request header. You can find your user token on the User Account
page in Label Studio. Example: <br><pre><code class="language-bash">curl
https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>
required: true
schema:
type: string
responses:
'200':
description: Billing information for the active organization
content:
application/json:
schema:
# --- truncated at 32 KB (1214 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/label-studio/refs/heads/main/openapi/label-studio-openapi.yml