> 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

{% 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.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

```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"
```

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.

{% 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 %}