> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.labelstud.io/api-reference/introduction/getting-started/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.labelstud.io/_mcp/server.

> **Note**
>
> Endpoints with sparkles ✨ next to them are only available for Label Studio Enterprise and, in many cases, Starter Cloud users.

> **Version 2.0 is here!**
>
> Version 2.0 of the Label Studio SDK is here, and it's packed with more functionality and a smoother developer experience!
>
> If you're using an older version, please review the [breaking changes](https://github.com/HumanSignal/label-studio-sdk/releases/tag/2.0.0) before upgrading.

You can use the Label Studio Python SDK to make annotating data a more integrated part of your data science and machine learning pipelines. This software development kit (SDK) lets you call the Label Studio API directly from scripts using predefined classes and methods.

The following are basic examples. For more advanced examples, see [Tutorials](/tutorials).

> **Tip**
>
> If you are using our SDK with an LLM, you can use this: [https://api.labelstud.io/llms.txt](https://api.labelstud.io/llms.txt)

## Install

Install the Label Studio SDK using pip:

```
pip install label-studio-sdk
```

or

```
poetry add label-studio-sdk
```

## Authenticate and Connect to the API

### “API keys” vs. “Access tokens”

In Label Studio, “access tokens” and “API keys” mean the same thing and are used interchangeably.

For example, if you set the `LABEL_STUDIO_API_KEY` environment variable, you will set it to your access token.

### Python SDK

In your Python scripts, you will need to do the following:

* Import the SDK.
* **Define your Label Studio URL.**

  For example, `http://localhost:8080` or `https://app.humansignal.com`

  Note:

  * Do not including a trailing slash in your URL
  * `LABEL_STUDIO_URL` should start with `https://` or `http://`
* **Define your access token/API key.**

  This should be available on the **Account & Settings** page, but you may need to enable it at the organization level first. See [Access tokens](https://labelstud.io/guide/access_tokens).

  You can use either the Legacy Token or the Personal Access Token, but for the SDK we recommend the Personal Access Token.
* Connect to the API.

Try this example:

```python
# Define the URL where Label Studio is accessible
LABEL_STUDIO_URL = 'YOUR_BASE_URL'
# API key is available at the Account & Settings page in Label Studio UI
LABEL_STUDIO_API_KEY = 'YOUR_API_KEY'

# Import the SDK and the client module
from label_studio_sdk import LabelStudio

# Connect to the Label Studio API 
client = LabelStudio(base_url=LABEL_STUDIO_URL, api_key=LABEL_STUDIO_API_KEY)

# A basic request to verify connection is working
me = client.users.whoami()

print("username:", me.username)
print("email:", me.email)
```

> **Tip**
>
> You can set `LABEL_STUDIO_URL` and `LABEL_STUDIO_API_KEY` as environment variables:
>
> ```bash
> export LABEL_STUDIO_API_KEY="YOUR_API_KEY"
> export LABEL_STUDIO_URL="YOUR_BASE_URL"
> ```

### SDK CLI

The SDK includes a CLI entrypoint that mirrors SDK resources and methods.

On **leaf commands** (for example `projects create`), use **`-h`** for minimal help (one-line summary, SDK signature, and options) and **`--help`** for the full generated documentation (parameters, examples, return shape, and options). Top-level groups only register **`--help`**.

```bash
export LABEL_STUDIO_API_KEY="YOUR_API_KEY"
export LABEL_STUDIO_URL="YOUR_BASE_URL"

# minimal help for one command
label-studio-sdk projects create -h

# full help (longer)
label-studio-sdk projects create --help

# top-level
label-studio-sdk --help

# List projects
label-studio-sdk projects list

# Create a project (generic key=value params)
label-studio-sdk projects create \
  --param title="CLI Example" \
  --param 'label_config=<View><Text name="text" value="$text"/></View>'
```

#### Running the CLI with uv

```bash
# from PyPI
uv run --with label_studio_sdk label-studio-sdk --help

# from github
uv run --with git+https://github.com/HumanSignal/label-studio-sdk.git label-studio-sdk --help

# from local
uv run --with-editable . label-studio-sdk --help
```

### HTTP API

If you are calling endpoints using HTTP (such as with cUrl commands), you will need to adjust your authorization header depending on which type of access token you are using.

Personal access tokens:

```bash
curl -X <method> <Label Studio URL>/api/<endpoint> \
-H 'Authorization: Bearer <token>'
```

Legacy tokens:

```bash
curl -X <method> <Label Studio URL>/api/<endpoint> \
-H 'Authorization: Token <token>'
```

## Tutorials

For examples of getting started using SDK, see the following tutorials:

* [Create a Project](/tutorials/tutorials/create-a-project)
* [Import Tasks](/tutorials/tutorials/import-tasks)
* [Assign Users to Tasks](/tutorials/tutorials/assign-users-to-tasks)
* [Add Model Predictions](/tutorials/tutorials/add-model-predictions)
* [Export and Convert Snapshots](/tutorials/tutorials/export-and-convert-snapshots)

Advanced tutorials focused on [ML backends](https://github.com/HumanSignal/label-studio-ml-backend):

* [Logging ML Server Predictions](/tutorials/tutorials/logging-ml-server-predictions)
* [Evaluate LLM Responses](/tutorials/tutorials/evaluate-llm-responses)
* [Improve Object Detection with YOLO](/tutorials/tutorials/improve-object-detection-with-yolo)
* [Interactive OCR with Tesseract](/tutorials/tutorials/interactive-ocr-with-tesseract)

> **Tip**
>
> For additional guidance on using our SDK, see [5 Tips and Tricks for Label Studio’s API and SDK](https://labelstud.io/blog/5-tips-and-tricks-for-label-studio-s-api-and-sdk/)

## SDK versions and compatibility

SDK version \< 1 is deprecated and no longer supported. We recommend upgrading to [the latest version](https://github.com/HumanSignal/label-studio-sdk).

If you still want to use the older version, you can install it using `pip install "label-studio-sdk<1"`.

You can also check out an older branch version in the GitHub repository:

```sh
git clone https://github.com/HumanSignal/label-studio-sdk.git
cd label-studio-sdk
git fetch origin
git checkout release/0.0.34
```

Or you can simply modify you code to change the import stream as follows:

```python
from label_studio_sdk import Client
from label_studio_sdk.data_manager import Filters, Column, Operator, Type
from label_studio_sdk._legacy import Project
```

If you're looking for the documentation for the older version, you can find it [here](https://labelstud.io/sdk/).

## Advanced

### Handling Errors

If you encounter an error while using the Label Studio Python SDK, you can catch the error and handle it in your script.

```python
from label_studio_sdk.core.api_error import ApiError

try:
    for annotated_task in annotated_tasks:
        print(annotated_task.annotations)
except ApiError as e:
    print(e)
```

Annotations are exported in the format specified in the [Label Studio JSON format](https://labelstud.io/guide/tasks.html#Basic-Label-Studio-JSON-format).

### Timeouts

By default, requests time out after 5 seconds. You can configure this with a timeout option at the client or request level.

```python
from label_studio_sdk import LabelStudio

client = LabelStudio(
    # All timeouts set to 20 seconds
    timeout=20
)

ls.projects.create(..., request_options={
    # Override timeout for a specific method
    'timeout_in_seconds': 20
})
```

### Custom HTTP client

You can override the httpx client to customize it for your use case. Some common use cases
include support for proxies and transports.

```python
custom_httpx_client = httpx.Client(
    transport=httpx.HTTPTransport(
        proxy="http://my.test.proxy.example.com",
        local_address="0.0.0.0"
    )
)
client = LabelStudio(
    api_key="YOUR_API_KEY",
    base_url="YOUR_LABEL_STUDIO_URL",
    httpx_client=custom_httpx_client,
)
```