> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/api-sdk-cli/api-sdk-and-cli.md).

# API, SDK & CLI

Connect AI assistants with Unitlab MCP, or build data annotation automations with the Python SDK, CLI, and authenticated HTTP API.

```mermaid
flowchart LR
  AI["AI assistants"] --> MCP["MCP with OAuth"]
  APP["Applications and workers"] --> SDK["Python SDK"]
  OPS["Shell, CI, and runbooks"] --> CLI["CLI"]
  EXT["Other runtimes"] --> HTTP["Authenticated HTTP API"]
  SDK --> PLATFORM["Unitlab platform API"]
  CLI --> PLATFORM
  HTTP --> PLATFORM
  MCP --> PLATFORM
  PLATFORM --> RES["Projects · Data · Workflows · Queues · Releases"]
```

*Choose the integration surface by runtime and operating model. These surfaces provide access to Unitlab resources through their respective authentication and permission models.*

{% hint style="info" %}
**Outcome:** Connect an AI assistant through MCP, or build production Unitlab automations with the Python SDK, CLI, and authenticated HTTP API.
{% endhint %}

The Python SDK and CLI help you upload data, organize datasets, and automate annotation workflows. The upload guides below use **Unitlab 3.1.3** and include file preparation, grouping rules, annotation imports, and processing checks.

## Choose a surface

| Need                           | Recommended surface                                                        |
| ------------------------------ | -------------------------------------------------------------------------- |
| Conversational AI workflows    | [Unitlab MCP](https://docs.unitlab.ai/api-sdk-cli/mcp)                     |
| Python application or notebook | [Python SDK quickstart](/api-sdk-cli/get-started/python-sdk-quickstart.md) |
| Terminal or shell script       | [CLI quickstart](/api-sdk-cli/get-started/cli-quickstart.md)               |
| Another programming language   | [HTTP API overview](/api-sdk-cli/apis/api-overview.md)                     |

## Connect an AI assistant with MCP

[Unitlab MCP](https://docs.unitlab.ai/api-sdk-cli/mcp) lets a compatible AI assistant work in one selected workspace: create projects, upload data, annotate supported modalities, manage workflow tasks, check quality, and export releases.

The hosted MCP server is `https://api.unitlab.ai/mcp`. Sign in with OAuth, choose a workspace, select Read only or Read and write, and limit permissions if needed. This connection does not require a Unitlab API key. The assistant remains bounded by your current workspace role and connection permissions.

Start with [Connect your AI assistant](https://docs.unitlab.ai/api-sdk-cli/mcp/connect-your-assistant) or the [image-folder quickstart](https://docs.unitlab.ai/api-sdk-cli/mcp/quickstart). Then explore the [MCP tool reference](https://docs.unitlab.ai/api-sdk-cli/mcp/tools) and [workflow automation guide](https://docs.unitlab.ai/api-sdk-cli/mcp/workflows).

## Upload data and existing annotations

| What you want to do                                              | Start here                                                                                                                                |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Upload a file or folder; automate a local file list              | [Python project uploads](/api-sdk-cli/sdks/project-uploads.md) or [CLI project uploads](/api-sdk-cli/clis/cli-projects-and-data-units.md) |
| Add reusable files to the Asset library                          | [SDK Assets](/api-sdk-cli/sdks/assets-and-custom-metadata.md) or [CLI Assets](/api-sdk-cli/clis/cli-assets-and-folders.md)                |
| Import local annotation JSON, COCO, or supported exported labels | [SDK annotation imports](/api-sdk-cli/sdks/annotation-imports.md)                                                                         |
| Group files using filename rules and a saved layout              | [Data Group automation](/api-sdk-cli/sdks/data-group-automation.md)                                                                       |
| Check accepted source data formats                               | [Supported files and upload preparation](https://docs.unitlab.ai/documentation/data/data-upload)                                          |

Annotation imports use a separate SDK workflow with a preview before commit. There is no annotation-import CLI command in version 3.1.3. A JSON file containing a list of paths is also distinct from annotation JSON; see the project upload guide for a Python loop that reads a local file list.

## Follow one complete example

Start with two local images in the [Python quickstart](/api-sdk-cli/get-started/python-sdk-quickstart.md) or [CLI quickstart](/api-sdk-cli/get-started/cli-quickstart.md). Once the images are processed, follow [Pre-labels, review, and export](/api-sdk-cli/sdks/prelabels-review-and-export.md) to import model labels, review them, and retrieve a release.

The guides distinguish three JSON inputs:

| File                                      | Purpose                                      | Where it is used                                                    |
| ----------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------- |
| A local list of media paths               | Input to your own upload loop                | [Project uploads](/api-sdk-cli/sdks/project-uploads.md)             |
| COCO or supported Unitlab annotation JSON | Labels that reference media                  | [Annotation imports](/api-sdk-cli/sdks/annotation-imports.md)       |
| `grouping-config.json`                    | Rules and layout for files already in Assets | [Data Group automation](/api-sdk-cli/sdks/data-group-automation.md) |

## Coverage

Projects, Data Units, Batch Queues, Assets, folders, cloud storage, grouping, datasets and versions, embedding spaces, ontologies, workflow stages and tasks, releases, errors, and production automation patterns.

{% hint style="warning" %}
The installed SDK and CLI help are authoritative for the pinned package version. Test upgrades against representative create, upload, attach, workflow, embedding, and release operations before changing production jobs.
{% endhint %}

## Keep the result of each step

| Step              | Save and check                                                                |
| ----------------- | ----------------------------------------------------------------------------- |
| Upload media      | Project or folder ID, Batch Queue ID, accepted files, and processing failures |
| Import labels     | Import ID, preview matches and conflicts, then the commit report              |
| Group files       | Estimate, generated grouped-folder ID, and the resulting groups/layout        |
| Review and export | Workflow decisions, release scope and status, then the downloaded labels      |

After a timeout, inspect the existing operation before repeating a create, upload, or commit request. For specific errors, use the recovery section in the guide for that operation.

***

> **Explore related Unitlab capabilities:** [enterprise data annotation workflows](https://unitlab.ai/en/data-annotation) and [Unitlab MCP for AI assistants](https://unitlab.ai/en/mcp).