Collections

Show: All versions v2 only

The Collections API is a deprecated v1 compatibility surface for older clients and SDKs. Internally, collections and buckets refer to the same underlying storage object, and collection search delegates to bucket search.

Note: For new integrations, use Buckets and POST /v2/buckets/\{bucket_id\}/search instead of the routes documented here.

API Versions

Version	Status	Path prefix	Guidance
v1	Deprecated	/v1/collections/*	Compatibility only. No new features will be added.
v2	Current	/v2/buckets/*	Use for all new integrations.

The v1 collection search endpoint returns Deprecation: true, Warning, and Link successor-version headers pointing to POST /v2/buckets/\{bucket_id\}/search.

Authentication

All collection API endpoints require an API key in the Authorization header:

Authorization: Bearer sch_xxxxxxxxxxxxxxxxxxxx

Each endpoint also requires a specific API key scope:

Scope	Access
collections:manage	Create and delete collections.
collections:read	List collections, get a collection, or read stats.
collections:use	Upsert or delete vectors.
embed	Embed and upsert documents (/documents and /add).
query	Search a collection.

Dashboard session routes under /v1/organizations/\{org_id\} require a signed-in user who is a member of the target organization.

Collection object

Field	Type	Description
id	string	Unique collection identifier.
name	string	Human-readable collection name.
dimension	integer	Embedding dimension of the collection.
model	string	Embedding model used for the collection.
backend	string	Vector backend, for example engine.
vector_count	integer	Number of indexed vectors.

POST /v1/collections

Create a new collection. The collection name must be unique within the organization.

Request body

Field	Type	Required	Default	Description
name	string	Yes	—	Collection name.
dimension	integer	Yes	—	Vector dimension for the collection.
model	string	No	schift-embed-1-small	Embedding model to use.
backend	string	No	engine	Vector backend. Supported values: engine, pgvector, weaviate, qdrant, pinecone, milvus, chroma, elasticsearch, redis, mongodb.

Request example

{
  "name": "legacy-faq",
  "dimension": 1024,
  "model": "schift-embed-1-small",
  "backend": "engine"
}

Response example

{
  "id": "abc123def456",
  "name": "legacy-faq",
  "dimension": 1024,
  "model": "schift-embed-1-small",
  "backend": "engine",
  "vector_count": 0
}

Errors

Status	Cause
400	Invalid backend or request body.
403	API key lacks the collections:manage scope.
409	A collection with this name already exists.

GET /v1/collections

List collections for the authenticated organization.

Response example

[
  {
    "id": "abc123def456",
    "name": "legacy-faq",
    "dimension": 1024,
    "model": "schift-embed-1-small",
    "backend": "engine",
    "vector_count": 128
  }
]

Errors

Status	Cause
403	API key lacks the collections:read scope.

GET /v1/collections/{name}

Get a single collection by name.

Path parameters

Parameter	Type	Description
name	string	Collection name.

Response example

{
  "id": "abc123def456",
  "name": "legacy-faq",
  "dimension": 1024,
  "model": "schift-embed-1-small",
  "backend": "engine",
  "vector_count": 128
}

Errors

Status	Cause
403	API key lacks the collections:read scope.
404	Collection not found.

GET /v1/collections/{name}/stats

Return the current vector count and metadata for a collection. The count is read directly from the vector backend and the stored count is refreshed.

Path parameters

Parameter	Type	Description
name	string	Collection name.

Response example

{
  "name": "legacy-faq",
  "dimension": 1024,
  "model": "schift-embed-1-small",
  "backend": "engine",
  "vector_count": 128
}

Errors

Status	Cause
403	API key lacks the collections:read scope.
404	Collection not found.

DELETE /v1/collections/{name}

Delete a collection and drop its vector table.

Path parameters

Parameter	Type	Description
name	string	Collection name.

Response

Returns 204 No Content on success.

Errors

Status	Cause
403	API key lacks the collections:manage scope.
404	Collection not found.

POST /v1/collections/{collection}/vectors

Upsert raw vectors into a collection. Each vector id is replaced if it already exists.

Note: Maximum batch size is 2048 vectors per request.

Path parameters

Parameter	Type	Description
collection	string	Collection name.

Request body

Field	Type	Required	Description
vectors	object[]	Yes	Array of vector items.
vectors[].id	string	Yes	Unique vector identifier.
vectors[].values	number[]	Yes	Embedding values. Must match the collection dimension.
vectors[].metadata	object	No	Free-form metadata.

Request example

{
  "vectors": [
    {
      "id": "vec-1",
      "values": [0.01, -0.02, 0.03],
      "metadata": {"source": "faq"}
    }
  ]
}

Response example

{
  "upserted": 1
}

Errors

Status	Cause
400	Batch size exceeds 2048, or vector dimension does not match the collection.
402	Quota exceeded.
403	API key lacks the collections:use scope.
404	Collection not found.

DELETE /v1/collections/{collection}/vectors

Delete specific vectors from a collection by their IDs.

Path parameters

Parameter	Type	Description
collection	string	Collection name.

Request body

Field	Type	Required	Description
ids	string[]	Yes	Vector IDs to delete. Must not be empty.

Request example

{
  "ids": ["vec-1", "vec-2"]
}

Response example

{
  "deleted": 2
}

Errors

Status	Cause
400	ids is empty.
403	API key lacks the collections:use scope.
404	Collection not found.
501	The configured backend does not support vector deletion by ID.

POST /v1/collections/{collection}/documents

Embed documents and store the resulting vectors in a collection. The request body includes the target embedding model.

Note: Maximum batch size is 2048 documents per request.

Path parameters

Parameter	Type	Description
collection	string	Collection name.

Request body

Field	Type	Required	Description
documents	object[]	Yes	Array of document items.
documents[].id	string	No	Document identifier. Generated if omitted.
documents[].text	string	Yes	Text to embed.
documents[].metadata	object	No	Free-form metadata.
model	string	Yes	Embedding model ID.

Request example

{
  "documents": [
    {
      "id": "doc-1",
      "text": "How do I reset my password?",
      "metadata": {"category": "support"}
    }
  ],
  "model": "schift-embed-1-small"
}

Response example

{
  "upserted": 1
}

Errors

Status	Cause
400	Batch size exceeds 2048, or the embedding model is unknown.
402	Quota exceeded.
403	API key lacks the required collections:use or embed scope.
404	Collection not found.

POST /v1/collections/{name}/add

Embed documents and add them to a collection. If the collection does not exist, it is auto-created with dimension=1024, model=schift-embed-1-small, and backend=engine.

Note: Maximum batch size is 2048 documents per request.

Path parameters

Parameter	Type	Description
name	string	Collection name.

Request body

Field	Type	Required	Default	Description
documents	string[]	Yes	—	Raw text strings to embed. Must not be empty.
ids	string[]	No	null	Optional document IDs.
metadata	object[]	No	null	Optional metadata objects, one per document.
task	string	No	null	Embedding task. One of: retrieval_query, retrieval_document, semantic_similarity, question_answering, clustering, classification, code_retrieval.
model	string	No	schift-embed-1-small	Embedding model ID.

Request example

{
  "documents": [
    "How do I reset my password?",
    "Where can I download invoices?"
  ],
  "metadata": [
    {"category": "support"},
    {"category": "billing"}
  ],
  "model": "schift-embed-1-small"
}

Response example

{
  "collection": "legacy-faq",
  "added": 2,
  "ids": ["id-1", "id-2"]
}

Errors

Status	Cause
400	documents is empty or batch size exceeds 2048.
402	Quota exceeded.
403	Embedding entitlement limit reached, or API key lacks the required scope.

POST /v1/collections/{name}/search

Search a collection. This endpoint is a compatibility wrapper over bucket search and returns a simplified response.

Path parameters

Parameter	Type	Description
name	string	Collection name.

Request body

Field	Type	Required	Default	Description
query	string	No*	—	Text query. Either query or query_vector is required.
query_vector	number[]	No*	—	Pre-computed query vector.
task	string	No	null	Embedding task. See valid task values.
top_k	integer	No	10	Number of results to return. Max 1000.
filter	object	No	null	Metadata filter.
model	string	No	null	Embedding or rerank model override.
mode	string	No	hybrid	Search mode: vector or hybrid.
rerank	boolean	No	false	Enable reranking.
rerank_top_k	integer	No	null	Top-k cutoff for reranking.
rerank_model	string	No	null	Reranker model ID.
temporal	string	No	null	Temporal filter: before, after, between, as_of, or latest.
temporal_start	integer	No	null	Required when temporal is set (except latest).
temporal_end	integer	No	null	Required when temporal=between.
advanced	object	No	null	Advanced scoring params: graph_weight, temporal_weight, hit_weight, vector_weight, bm25_weight, hops, temporal_half_life_days.
expand_context	object	No	null	Context expansion params: window, max_extra, score_decay.

Request example

{
  "query": "reset password",
  "top_k": 5,
  "filter": {"category": "support"},
  "mode": "hybrid"
}

Response example

{
  "collection": "legacy-faq",
  "results": [
    {
      "id": "doc-1",
      "score": 0.92,
      "text": "How do I reset my password?",
      "metadata": {"category": "support"},
      "neighbors": null,
      "citation": null
    }
  ]
}

The response also includes deprecation headers pointing to the v2 bucket search successor:

Deprecation: true
Warning: 299 - "Deprecated search endpoint; migrate to /v2/buckets/{bucket_id}/search"
Link: </v2/buckets/abc123def456/search>; rel="successor-version"

Errors

Status	Cause
400	Neither query nor query_vector provided, or invalid temporal parameters.
402	Quota exceeded.
403	Search entitlement limit reached, or API key lacks the required scope.
404	Collection not found.

Dashboard organization routes

These routes are used by the Schift dashboard and rely on session authentication. The calling user must be a member of \{org_id\}.

GET /v1/organizations/{org_id}/collections

List collections in the organization.

GET /v1/organizations/{org_id}/collections/{name}

Get a single collection in the organization.

POST /v1/organizations/{org_id}/collections

Create a collection in the organization.

Request body

Field	Type	Required	Default	Description
name	string	Yes	—	Collection name.
model	string	No	schift-embed-1-small	Embedding model.
dimension	integer	No	model default or 1024	Vector dimension.
backend	string	No	engine	Vector backend.

Errors

Status	Cause
400	Missing name or unsupported backend.
403	User is not an organization member, or the collection limit for the plan was reached.

DELETE /v1/organizations/{org_id}/collections/{name}

Delete a collection in the organization. Returns 204 No Content.

GET /v1/organizations/{org_id}/collections/{name}/stats

Return collection stats, including the live vector count.

GET /v1/organizations/{org_id}/vectordb-configs

List organization-level VectorDB configurations.

PUT /v1/organizations/{org_id}/vectordb-configs

Create or update a VectorDB configuration for a backend.

Request body

Field	Type	Required	Description
collection_id	string	Yes	Target collection ID.
backend	string	Yes	Backend name. Must be supported.
endpoint	string	No	Backend endpoint URL.
api_key	string	No	Backend credentials.
extra	object	No	Additional backend-specific options.

Response example

{
  "status": "ok"
}

Errors

Status	Cause
400	Unsupported backend.
403	User is not an organization member.

See also

• Buckets
• Query
• Embeddings