Buckets

Show:

A bucket is Schift’s public knowledge-storage surface. Use buckets to upload documents, check indexing readiness, search answer-ready context with citations, and manage the documents that belong to a knowledge base.

Note: All bucket endpoints require an Authorization: Bearer <SCHIFT_API_KEY> header. Endpoints that create, modify, or delete buckets or documents require the buckets:manage scope. Read and search endpoints accept any valid API key subject to organization limits.

API Versions

The public product API is v2. New integrations should use the /v2/buckets/* routes documented below.

The older /v1/buckets/* routes are a deprecated compatibility surface for existing clients. They continue to work, but v1 search endpoints return Deprecation and Link successor-version headers pointing to the v2 equivalents. Public buckets are read-only on both versions.

Bucket object

Field	Type	Description
`id`	`string`	Unique bucket identifier.
`name`	`string`	Human-readable bucket name.
`description`	`string`	Optional description.
`dimension`	`integer`	Embedding dimension configured for the bucket.
`model`	`string`	Embedding model used for the bucket.
`backend`	`string`	Vector backend, for example `engine`.
`file_count`	`integer`	Number of uploaded documents.
`vector_count`	`integer`	Number of indexed vectors.
`active_job_count`	`integer`	Number of in-progress jobs for this bucket.
`created_at`	`string`	ISO 8601 creation timestamp.
`default_privacy_level`	`integer`	Default privacy level for bucket content.
`max_privacy_level`	`integer`	Maximum privacy level allowed.
`external_max_privacy_level`	`integer`	Maximum privacy level exposed externally.
`enforce_access_policy`	`boolean`	Whether access policies are enforced.
`scope_by_department`	`boolean`	Whether access is scoped by department metadata.

POST /v2/buckets

Create a new bucket. Schift auto-configures the embedding model, dimension, and backend.

Request body

Field	Type	Required	Default	Description
`name`	`string`	Yes	—	Bucket name. Must not start with `__schift_`.
`description`	`string`	No	`""`	Optional description.
`metadata`	`object`	No	`null`	Free-form user metadata.
`default_privacy_level`	`integer`	No	`3`	Default privacy level.
`max_privacy_level`	`integer`	No	`10`	Maximum privacy level.
`external_max_privacy_level`	`integer`	No	`1`	External privacy ceiling.
`enforce_access_policy`	`boolean`	No	`true`	Enable access-policy enforcement.
`scope_by_department`	`boolean`	No	`false`	Scope access by department.

Request example

{
  "name": "product-docs",
  "description": "Product support knowledge"
}

Response example

{
  "id": "bucket_01J8X1234567890ABCDEF",
  "name": "product-docs",
  "description": "Product support knowledge",
  "dimension": 1024,
  "model": "text-embedding-3-large",
  "backend": "engine",
  "file_count": 0,
  "vector_count": 0,
  "active_job_count": 0,
  "created_at": "2026-06-19T05:00:00Z",
  "default_privacy_level": 3,
  "max_privacy_level": 10,
  "external_max_privacy_level": 1,
  "enforce_access_policy": false,
  "scope_by_department": false
}

Errors

Status	Cause
`400`	Invalid request body.
`403`	Bucket name uses the reserved `__schift_` namespace.
`409`	A bucket with this name already exists.

GET /v2/buckets

List buckets for the authenticated organization.

Response example

[
  {
    "id": "bucket_01J8X1234567890ABCDEF",
    "name": "product-docs",
    "description": "Product support knowledge",
    "dimension": 1024,
    "model": "text-embedding-3-large",
    "backend": "engine",
    "file_count": 12,
    "vector_count": 128,
    "active_job_count": 0,
    "created_at": "2026-06-19T05:00:00Z",
    "default_privacy_level": 3,
    "max_privacy_level": 10,
    "external_max_privacy_level": 1,
    "enforce_access_policy": false,
    "scope_by_department": false
  }
]

GET /v2/buckets/{bucket_id}

Retrieve a single bucket by ID.

Path parameters

Parameter	Type	Required	Description
`bucket_id`	`string`	Yes	Bucket identifier.

Response example

Same shape as the POST /v2/buckets response.

Errors

Status	Cause
`404`	Bucket not found or not accessible.

PATCH /v2/buckets/{bucket_id}

Modify mutable bucket fields. Currently supports renaming, updating the description, and updating metadata including privacy policy fields.

Path parameters

Parameter	Type	Required	Description
`bucket_id`	`string`	Yes	Bucket identifier.

Request body

All fields are optional.

Field	Type	Description
`name`	`string`	New bucket name.
`description`	`string`	New description.
`metadata`	`object`	Free-form metadata merged into existing metadata.
`default_privacy_level`	`integer`	Default privacy level.
`max_privacy_level`	`integer`	Maximum privacy level.
`external_max_privacy_level`	`integer`	External privacy ceiling.
`enforce_access_policy`	`boolean`	Enable access-policy enforcement.
`scope_by_department`	`boolean`	Scope access by department.

Request example

{
  "description": "Updated product support knowledge"
}

Response example

Same shape as the POST /v2/buckets response.

Errors

Status	Cause
`403`	Public buckets are read-only.
`404`	Bucket not found.
`409`	The new bucket name is already taken.

DELETE /v2/buckets/{bucket_id}

Queue a bucket for deletion. Deletion is performed asynchronously and returns a job ID.

Path parameters

Parameter	Type	Required	Description
`bucket_id`	`string`	Yes	Bucket identifier.

Response example

{
  "bucket_id": "bucket_01J8X1234567890ABCDEF",
  "job_id": "job_01J8Y1234567890ABCDEF",
  "status": "queued",
  "delete_requested_at": "2026-06-19T05:05:00Z"
}

Errors

Status	Cause
`403`	Public buckets are read-only.
`404`	Bucket not found.

GET /v2/buckets/{bucket_id}/collections

List the child collections inside a bucket.

Path parameters

Parameter	Type	Required	Description
`bucket_id`	`string`	Yes	Bucket identifier.

Response example

[
  {
    "id": "col_01J8X1234567890ABCDEF",
    "bucket_id": "bucket_01J8X1234567890ABCDEF",
    "name": "migration-guides",
    "description": "",
    "dimension": 1024,
    "model": "text-embedding-3-large",
    "backend": "engine",
    "file_count": 4,
    "vector_count": 42,
    "active_job_count": 0
  }
]

Errors

Status	Cause
`404`	Bucket not found.

GET /v2/buckets/{bucket_id}/search/status

Check whether a bucket is ready to answer questions. This endpoint returns a consumer-facing readiness summary without running a search.

Path parameters

Parameter	Type	Required	Description
`bucket_id`	`string`	Yes	Bucket identifier.

Response example

{
  "status": "ready",
  "operational_status": "ready",
  "bucket_id": "product-docs",
  "indexed_count": 128,
  "document_count": 12,
  "pending_job_count": 0,
  "failed_job_count": 0,
  "last_indexed_at": "2026-06-19T04:55:00Z",
  "backfill_required": false
}

Errors

Status	Cause
`404`	Bucket not found.

POST /v2/buckets/{bucket_id}/search

Run the managed knowledge-search pipeline and return answer-ready context with citations. Callers do not need to choose embedding routes, vector modes, or rerank machinery.

Path parameters

Parameter	Type	Required	Description
`bucket_id`	`string`	Yes	Bucket identifier.

Request body

Field	Type	Required	Default	Description
`query`	`string`	Yes	—	Question to ask against the bucket.
`top_k`	`integer`	No	`8`	Maximum cited passages to return. Range `1`–`100`.
`context_budget`	`integer`	No	`2000`	Approximate maximum context size in tokens. Range `100`–`32000`.
`filters`	`object`	No	`null`	Metadata filters. See Filters.
`options.rerank.enabled`	`boolean`	No	`true`	Improve citation ordering before context assembly.
`options.rerank.top_k`	`integer`	No	`null`	Candidate passages to rerank. Range `1`–`1000`.
`options.instructions.task`	`string`	No	`null`	Search instruction preset such as `retrieval_query`.

Request example

{
  "query": "How do I migrate embedding models?",
  "top_k": 8,
  "context_budget": 4000,
  "filters": {"product": "schift"},
  "options": {
    "rerank": {"enabled": true, "top_k": 20},
    "instructions": {"task": "retrieval_query"}
  }
}

Response example

{
  "status": "ready",
  "operational_status": "ready",
  "bucket_id": "product-docs",
  "query": "How do I migrate embedding models?",
  "context": "[1] Migration guide excerpt...",
  "citations": [
    {
      "index": 1,
      "document_id": "doc_042",
      "source_id": "doc_042",
      "title": "Migration Guide",
      "source_url": null,
      "page": null,
      "section": null
    }
  ],
  "warnings": []
}

Errors

Status	Cause
`400`	Invalid filter or request body.
`402`	Search quota exceeded.
`403`	Search quota unavailable or plan restriction.
`404`	Bucket not found.

POST /v2/buckets/{bucket_id}/collections/{collection_id}/search

Search a single collection within a bucket using the raw v2 search contract. This is useful when you want results from a specific child collection rather than the whole bucket.

Path parameters

Parameter	Type	Required	Description
`bucket_id`	`string`	Yes	Bucket identifier.
`collection_id`	`string`	Yes	Collection identifier.

Request body

Field	Type	Required	Default	Description
`query`	`string`	Yes*	`""`	Text query. Either `query` or `queryVector` is required.
`queryVector`	`number[]`	Yes*	`null`	Raw embedding vector.
`topK`	`integer`	No	`10`	Maximum results. Range `1`–`1000`.
`model`	`string`	No	`null`	Embedding model override.
`filter`	`object`	No	`null`	Metadata filter.
`accessMode`	`string`	No	`auto`	One of `auto`, `internal`, `external`. `raw` is internal-only.
`mode`	`string`	No	`hybrid`	`vector` or `hybrid`.
`rerank`	`boolean`	No	`false`	Enable reranking.
`rerankTopK`	`integer`	No	`null`	Candidate count for reranking.
`minScore`	`number`	No	`null`	Minimum result score. Range `0`–`1`.
`debug`	`boolean`	No	`false`	Include debug timing and scores.

Response example

{
  "bucket_id": "product-docs",
  "query": "migration",
  "search_id": "search_01J8X1234567890ABCDEF",
  "results": [
    {
      "id": "chunk_042",
      "score": 0.923,
      "text": "Migration guide excerpt...",
      "metadata": {"document_id": "doc_042"},
      "citation": null
    }
  ],
  "degraded": false,
  "warnings": []
}

Errors

Status	Cause
`400`	Missing `query` or `queryVector`, or invalid temporal parameters.
`403`	`raw` retrieval mode is internal-only.
`404`	Bucket or collection not found.

POST /v2/buckets/{bucket_id}/documents

Upload one or more files into a bucket. Uploaded files are extracted, chunked, embedded, and indexed asynchronously. This endpoint accepts multipart/form-data.

Path parameters

Parameter	Type	Required	Description
`bucket_id`	`string`	Yes	Bucket identifier.

Form fields

Field	Type	Required	Default	Description
`files`	`file`	Yes	—	One or more files. PDFs, Markdown, text, Office documents, and images are supported.
`ocr_strategy`	`string`	No	`auto`	OCR strategy for image-based documents.
`chunk_size`	`integer`	No	`512`	Target chunk size. Range `64`–`8192`.
`chunk_overlap`	`integer`	No	`50`	Chunk overlap. Range `0`–`512`.
`metadata`	`string`	No	`null`	JSON-stringified object attached to every uploaded file.
`collection_id`	`string`	No	`null`	Target child collection. Defaults to the bucket.

Request example

curl -X POST ${API_BASE_URL}/v2/buckets/product-docs/documents \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "ocr_strategy=auto" \
  -F "chunk_size=512" \
  -F 'metadata={"source":"support","product":"schift"}'

Response example

{
  "jobs": [
    {
      "job_id": "job_01J8X1234567890ABCDEF",
      "document_id": "doc_01J8X1234567890ABCDEF",
      "file_name": "manual.pdf",
      "file_type": "pdf",
      "status": "queued",
      "estimated_cost": 0.05
    }
  ],
  "total_estimated_cost": 0.05
}

Errors

Status	Cause
`400`	Unsupported file type or invalid form data.
`403`	API key lacks the `buckets:manage` scope.
`404`	Bucket not found.
`413`	File or request exceeds upload limits.

GET /v2/buckets/{bucket_id}/documents

List documents in a bucket.

Path parameters

Parameter	Type	Required	Description
`bucket_id`	`string`	Yes	Bucket identifier.

Query parameters

Parameter	Type	Required	Default	Description
`status`	`string`	No	—	Filter by document status.
`limit`	`integer`	No	`50`	Maximum results. Range `1`–`500`.

Response example

[
  {
    "id": "doc_01J8X1234567890ABCDEF",
    "bucket_id": "product-docs",
    "collection_id": null,
    "file_name": "manual.pdf",
    "file_type": "pdf",
    "status": "ready",
    "metadata": {"source": "support", "product": "schift"},
    "source_metadata": {},
    "latest_job_id": "job_01J8X1234567890ABCDEF",
    "latest_successful_job_id": "job_01J8X1234567890ABCDEF",
    "last_error_summary": null,
    "created_at": "2026-06-19T04:00:00Z",
    "updated_at": "2026-06-19T04:05:00Z"
  }
]

Errors

Status	Cause
`404`	Bucket not found.

GET /v2/buckets/{bucket_id}/documents/{document_id}

Retrieve a single document by ID.

Path parameters

Parameter	Type	Required	Description
`bucket_id`	`string`	Yes	Bucket identifier.
`document_id`	`string`	Yes	Document identifier.

Response example

Same shape as a single item in the GET /v2/buckets/{bucket_id}/documents response.

Errors

Status	Cause
`404`	Bucket or document not found.

PATCH /v2/buckets/{bucket_id}/documents/{document_id}

Update a document’s metadata. Changes that affect search visibility trigger a reindex by default.

Path parameters

Parameter	Type	Required	Description
`bucket_id`	`string`	Yes	Bucket identifier.
`document_id`	`string`	Yes	Document identifier.

Request body

Field	Type	Required	Default	Description
`metadata`	`object`	No	`{}`	Metadata to merge.
`public_accessible`	`boolean`	No	`null`	Whether the document is publicly accessible.
`privacy_level`	`integer`	No	`null`	Privacy level. Range `1`–`10`.
`classification`	`string`	No	`null`	One of `internal`, `public`, `restricted`, `confidential`.
`review_status`	`string`	No	`null`	One of `pending`, `approved`, `rejected`.
`reindex`	`boolean`	No	`true`	Queue reindexing after the update.

Response example

Same shape as the GET /v2/buckets/{bucket_id}/documents/{document_id} response.

Errors

Status	Cause
`400`	Invalid metadata.
`404`	Bucket or document not found.

DELETE /v2/buckets/{bucket_id}/documents/{document_id}

Queue a document for hard deletion. Deletion is performed asynchronously and returns a job ID.

Path parameters

Parameter	Type	Required	Description
`bucket_id`	`string`	Yes	Bucket identifier.
`document_id`	`string`	Yes	Document identifier.

Response example

{
  "bucket_id": "product-docs",
  "document_id": "doc_01J8X1234567890ABCDEF",
  "job_id": "job_01J8Y1234567890ABCDEF",
  "status": "queued",
  "delete_requested_at": "2026-06-19T05:10:00Z"
}

Errors

Status	Cause
`404`	Bucket or document not found.

GET /v2/buckets/{bucket_id}/metadata-keys

List metadata keys that appear across documents in a bucket, together with their most common values.

Path parameters

Parameter	Type	Required	Description
`bucket_id`	`string`	Yes	Bucket identifier.

Query parameters

Parameter	Type	Required	Default	Description
`limit`	`integer`	No	`500`	Maximum documents scanned for keys. Range `1`–`2000`.
`values_per_key`	`integer`	No	`20`	Maximum values returned per key. Range `0`–`100`.

Response example

{
  "bucket_id": "product-docs",
  "keys": [
    {
      "key": "product",
      "document_count": 12,
      "values": [
        {"value": "schift", "count": 10},
        {"value": "docs", "count": 2}
      ]
    }
  ]
}

Errors

Status	Cause
`404`	Bucket not found.

GET /v2/buckets/{bucket_id}/metadata-keys/{key}/values

List the values observed for a specific metadata key.

Path parameters

Parameter	Type	Required	Description
`bucket_id`	`string`	Yes	Bucket identifier.
`key`	`string`	Yes	Metadata key.

Query parameters

Parameter	Type	Required	Default	Description
`limit`	`integer`	No	`100`	Maximum distinct values. Range `1`–`1000`.
`document_limit`	`integer`	No	`2000`	Maximum documents scanned. Range `1`–`10000`.

Response example

{
  "bucket_id": "product-docs",
  "key": "product",
  "values": [
    {"value": "schift", "count": 10},
    {"value": "docs", "count": 2}
  ]
}

Errors

Status	Cause
`404`	Bucket not found or metadata key not found.

POST /v1/buckets

Deprecated. Creates a new bucket. Use POST /v2/buckets instead.

GET /v1/buckets

Deprecated. Lists buckets for the authenticated organization. Use GET /v2/buckets instead.

GET /v1/buckets/{bucket_id}

Deprecated. Retrieves a single bucket by ID. Use GET /v2/buckets/{bucket_id} instead.

PATCH /v1/buckets/{bucket_id}

Deprecated. Updates mutable bucket fields. Use PATCH /v2/buckets/{bucket_id} instead.

DELETE /v1/buckets/{bucket_id}

Deprecated. Queues a bucket for deletion. Use DELETE /v2/buckets/{bucket_id} instead.

GET /v1/buckets/{bucket_id}/collections

Deprecated. Lists the child collections inside a bucket. Use GET /v2/buckets/{bucket_id}/collections instead.

POST /v1/buckets/{bucket_id}/upload

Deprecated. Uploads files into a bucket. Use POST /v2/buckets/{bucket_id}/documents instead.

POST /v1/buckets/{bucket_id}/search

Deprecated. Runs a raw bucket search that returns scored result items. Use POST /v2/buckets/{bucket_id}/collections/{collection_id}/search for the raw v2 search contract, or POST /v2/buckets/{bucket_id}/search for managed knowledge search with citations.