Embedding spaces API

Create vector spaces, upsert asset or frame vectors, and run scoped similarity search.

Outcome: Create vector spaces, upsert asset or frame vectors, and run scoped similarity search.

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

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.

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

---

Explore related Unitlab capabilities: Unitlab’s data curation platform