> 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/embedding-spaces-api.md).

# Embedding spaces API

{% hint style="info" %}
**Outcome:** Create vector spaces, upsert asset or frame vectors, and run scoped similarity search.
{% endhint %}

### Endpoints

| Method | Endpoint                                        | Purpose                              |
| ------ | ----------------------------------------------- | ------------------------------------ |
| GET    | `/api/sdk/embedding-spaces/`                    | List vector spaces                   |
| POST   | `/api/sdk/embedding-spaces/`                    | Create a fixed-dimension space       |
| GET    | `/api/sdk/embedding-spaces/{space_id}/`         | Read readiness and dimensions        |
| DELETE | `/api/sdk/embedding-spaces/{space_id}/`         | Delete a space                       |
| POST   | `/api/sdk/embedding-spaces/{space_id}/vectors/` | Upsert asset- or frame-level vectors |
| POST   | `/api/sdk/embedding-spaces/{space_id}/search/`  | Search nearest neighbors             |

### Create, upsert, and search

```bash
curl --fail-with-body --silent --show-error \
  -X POST "$UNITLAB_API_URL/api/sdk/embedding-spaces/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"vision-encoder-2026-07","dimensions":3,"model_name":"encoder@sha256:..."}'

curl --fail-with-body --silent --show-error \
  -X POST "$UNITLAB_API_URL/api/sdk/embedding-spaces/SPACE_ID/vectors/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"items":[{"asset_id":"ASSET_A","vector":[0.1,0.2,0.3]},{"asset_id":"ASSET_B","frame_index":4,"vector":[0.3,0.2,0.1]}]}'

curl --fail-with-body --silent --show-error \
  -X POST "$UNITLAB_API_URL/api/sdk/embedding-spaces/SPACE_ID/search/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"vector":[0.1,0.2,0.3],"limit":25,"project_id":"PROJECT_ID","level":"frame"}'
```

Every vector must match declared dimensions. Record encoder identity, preprocessing, normalization, source version, and run ID. Create a new space for an incompatible model or dimension.

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