> 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/apis/api-overview.md). # API overview Understand the public HTTP resource model, base URL, version boundary, and request lifecycle. {% hint style="info" %} **Outcome:** Understand the public HTTP resource model, base URL, version boundary, and request lifecycle. {% endhint %} ### Current HTTP contract This reference covers the public routes used by Unitlab SDK 3.1.3. Every endpoint begins with `/api/sdk/`. Private browser calls and internal routes are intentionally excluded. | Convention | Contract | | ----------------- | ---------------------------------------------------------------------------------------------- | | Base URL | `https://api.unitlab.ai`, unless Unitlab assigned another deployment URL | | Authentication | `Authorization: Api-Key YOUR_API_KEY` | | Payloads | JSON for resources; multipart form data for file uploads | | Identifiers | Stable Project, Dataset, Folder, Asset, Task, Ontology, Queue, Release, or Embedding Space IDs | | Pagination | Follow response `next` URLs or provider tokens until empty | | Long-running work | Preserve the Batch Queue ID and poll its status | ### Resource scopes | Scope | What it controls | | ------------------------ | --------------------------------------------------------------------------------------------- | | Projects | Lifecycle, Data Units, attachments, uploads, Batch Queues | | Assets and folders | Durable workspace data, hierarchy, metadata, cloud sync, Auto-Groups | | Datasets | Reusable membership, drafts, immutable versions | | Ontologies | Reusable label schemas and revisions | | Annotations and workflow | Annotation-import previews and commits, stages, tasks, ownership, actions, overrides, history | | Releases | Versioned exports and download preparation | | Embeddings | Vector spaces, upserts, scoped similarity search | | Cloud storage | Approved integrations, safe browsing, Project imports | ## Upload media, labels, and grouped files over HTTP These guides cover the same workflows as the CLI, Python SDK, and frontend, using the public HTTP endpoints: | Task | HTTP guide | Equivalent product/client guide | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Upload a media file or local folder and monitor processing | [Project data and Batch Queues API](/api-sdk-cli/apis/project-data-and-batch-queues-api.md) | [CLI media uploads](/api-sdk-cli/clis/cli-projects-and-data-units.md) | | Import local or cloud annotation JSON, map it to existing media, and commit labels | [Annotations and workflow API](/api-sdk-cli/apis/annotations-and-workflow-api.md) | [Python SDK label imports](/api-sdk-cli/sdks/annotation-imports.md) and [frontend label imports](https://docs.unitlab.ai/documentation/data/import-local-annotations) | | Upload reusable Assets, organize folders, and configure grouped files/layouts | [Assets and folders API](/api-sdk-cli/apis/assets-and-folders-api.md) | [Grouped files and layouts](https://docs.unitlab.ai/documentation/data/data-groups-and-layouts) | | Link media from a saved cloud-storage connection | [Cloud storage API](/api-sdk-cli/apis/cloud-storage-api.md) | [SDK cloud storage](/api-sdk-cli/sdks/cloud-storage.md) | Upload media before importing its labels. A file-list JSON used by your own script is different from annotation JSON or an Auto Groups configuration: each has a separate role. HTTP integrations must send the appropriate file requests rather than upload an arbitrary JSON list and expect Unitlab to fetch its contents. Annotation Imports requires a compatible server deployment. The installed SDK version alone does not establish server availability; the annotation guide explains this requirement. ## Make your first request Use a workspace API key from [Authentication and configuration](/api-sdk-cli/get-started/authentication-and-configuration.md). Run the following in a macOS or Linux shell, replacing `YOUR_API_KEY` with your configured credential. Change the base URL only if Unitlab assigned a different deployment. ```bash export UNITLAB_API_URL="https://api.unitlab.ai" export UNITLAB_API_KEY="YOUR_API_KEY" curl --fail-with-body --silent --show-error \ "$UNITLAB_API_URL/api/sdk/projects/" \ -H "Authorization: Api-Key $UNITLAB_API_KEY" \ -H "Accept: application/json" ``` **Expected result:** an HTTP 200 response containing the projects accessible to the key. A workspace with no visible projects can return an empty collection. Use the intended project's ID in the upload examples; do not substitute its display name. Next, choose one of the upload guides above. Keep its returned Batch Queue or import ID so you can inspect processing or refresh a preview without repeating the initial request. ### Production mutation sequence 1. Read the target and capture current state. 2. Validate the request and use an explicit timeout. 3. Send one mutation and preserve returned IDs. 4. Poll asynchronous work instead of repeating create requests. 5. Read the target again and compare server state with the intended outcome. {% hint style="warning" %} The Python SDK is the reference implementation for pagination, multipart uploads, retries, and error mapping. Direct clients must implement those responsibilities. {% endhint %} ### Request operating contract | Concern | Required behavior | | ----------------- | ----------------------------------------------------------------------------------------------------- | | Execution surface | TLS-verified client using the reviewed current public `/api/sdk/...` route contract. | | Identity | Least-privilege workspace service identity; secrets remain outside code and logs. | | Request boundary | URL-encoded stable IDs, explicit deadlines, structured errors, and complete pagination. | | Success evidence | Response identifiers, read-after-write verification, and separate processing status for Batch Queues. | {% hint style="warning" %} Do not infer undocumented private routes. After a timeout, inspect remote state before repeating a mutation. {% endhint %} *** > **Related Unitlab capability guides:** [enterprise data annotation workflows](https://unitlab.ai/en/data-annotation)