Label Studio SDK

Label Studio SDK is HumanSignal’s official Python library for talking to a running Label Studio instance — the open-source data labeling and annotation platform. It wraps the full Label Studio REST API in a typed, resource-oriented client (client.projects, client.tasks, client.annotations, client.webhooks, and dozens more) so teams can create labeling projects, import and export tasks, manage predictions and annotation reviews, configure ML backends, and administer users and workspaces without hand-rolling HTTP calls.

The library is generated from an OpenAPI spec using Fern, giving it a consistent, fully-typed surface across sync and async clients (LabelStudio / AsyncLabelStudio), Pydantic request/response models, typed exceptions per HTTP status code, retry and pagination handling, and a label_interface module for building and validating Label Studio’s XML labeling-config UI in Python. A companion CLI mirrors the SDK’s resources for scripting project setup from the shell, and a converter module handles format translation (COCO, YOLO, CSV, brush masks, FUNSD, and more) between Label Studio’s task format and common ML dataset formats.

Because the SDK is a thin, generated layer over the API, most real logic lives in the Label Studio server itself; the SDK’s value is a stable, versioned, well-documented way to drive that server programmatically from data pipelines, ML training loops, or internal tooling — including Enterprise-only endpoints like inter-annotator agreement stats and review workflows for teams on that tier.

What You Get

• A fully-typed synchronous and asynchronous client (LabelStudio / AsyncLabelStudio) generated from Label Studio’s OpenAPI spec, covering every documented API resource
• A label_interface module for programmatically building, validating, and previewing Label Studio’s XML label-config UI instead of hand-writing XML
• A converter module that translates between Label Studio’s task/annotation JSON and common ML dataset formats (COCO, YOLO, CSV, Brush masks, FUNSD)
• A CLI (label-studio-sdk) that mirrors SDK resources for scripting project creation, task import, and administration from the shell or CI
• Typed exceptions per HTTP status code (BadRequestError, ForbiddenError, NotFoundError, etc.) plus built-in retry, pagination, and request-option handling

Common Use Cases

• Bootstrapping a new labeling project and its label config from a script, then bulk-importing tasks from an existing dataset
• Feeding model predictions into Label Studio ahead of human review, to speed up annotation via pre-labeling
• Exporting completed annotations on a schedule and converting them into COCO/YOLO format for a training pipeline
• Wiring a custom ML backend or webhook into a project so new annotations trigger downstream retraining or QA
• Automating Enterprise workspace and user administration (roles, review assignment, inter-annotator agreement stats) as part of an internal ops tool

Under The Hood

Architecture The SDK is generated by Fern from Label Studio’s OpenAPI spec, producing per-resource client modules (src/label_studio_sdk/projects, tasks, annotations, webhooks, workspaces, prompts, and roughly 30 more) each exposing typed methods that map directly to API endpoints. client.py composes a LabelStudioBase/AsyncLabelStudioBase generated core with a small number of hand-written extension classes (TasksClientExt, ProjectsClientExt in */client_ext.py) that override selected properties to add convenience behavior on top of the generated code — a pattern that keeps the bulk of the client fully regenerable while allowing a few ergonomic additions to survive regeneration. Cross-cutting concerns (HTTP transport, retries, pagination, serialization, error parsing) live in core/, decoupling resource clients from transport details; a change to the core abstraction would ripple through every resource client uniformly.

Tech Stack Python 3.10+ with httpx (and optional aiohttp/httpx-aiohttp) as the HTTP transport, pydantic v1/v2-compatible models for request/response typing, typer for the CLI, and a cluster of labeling-domain dependencies — lxml/xmljson for the XML label-config interface, opencv-python-headless, Pillow, and numpy for image/annotation handling in the converter, nltk for text processing, and jsonschema/jsf for schema validation. Packaging is Poetry-based (pyproject.toml, poetry.lock), with datamodel-code-generator used to keep generated types in sync with the API schema.

Code Quality Tests live under tests/, split into utils/ (serialization, query encoding, HTTP client behavior) and custom/ (hand-written extension behavior); several test files are explicit placeholders (pytest.mark.skip(reason="Unimplemented")), indicating test coverage is uneven and concentrated on the hand-written extension layer rather than the generated resource clients, which rely on the correctness of code generation rather than direct unit tests. The project uses mypy for type checking and ruff for linting in its dev dependency group, and CI configuration lives under .github/. Error handling is explicit and typed — each HTTP status maps to a dedicated exception class in errors/.

API Design The API surface is deliberately mechanical and predictable: every resource follows the same client.<resource>.<method>() shape with typed request/response models, which lowers the learning curve for anyone who has used one Fern-generated SDK before. Getting started requires only a base URL and API key. The README explicitly documents breaking changes between SDK 1 and SDK 2 and flags which capabilities are Enterprise-only versus open-source, which is unusually transparent for a generated client and reduces the trial-and-error normally needed to discover tier-gated functionality.