API overview

Understand the public HTTP resource model, base URL, version boundary, and request lifecycle.

Outcome: Understand the public HTTP resource model, base URL, version boundary, and request lifecycle.

Current HTTP contract

This reference covers the public routes used by Unitlab SDK 3.0.0. 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	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

First request

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"

A successful response proves authentication and route access. Before a mutation, resolve the intended IDs and confirm least-privilege access.

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.

The Python SDK is the reference implementation for pagination, multipart uploads, retries, and error mapping. Direct clients must implement those responsibilities.

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.

Do not infer undocumented private routes. After a timeout, inspect remote state before repeating a mutation.

---

Related Unitlab capability guides: enterprise data annotation workflows