Docs

Buckets

Upload documents into a bucket, check search readiness, and ask questions through the v2 knowledge-search API.

Create Bucket

bashcurl -X POST https://api.schift.io/v2/buckets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{"name": "research-papers", "description": "ML research corpus"}'

Field	Type	Required	Description
`name`	string	Yes	Unique bucket name within your organization
`description`	string	No	Human-readable description

Upload Files

Upload one or more files via multipart form data. Processing is asynchronous — the endpoint returns job IDs immediately and files are processed in the background.

bashcurl -X POST https://api.schift.io/v2/buckets/{bucket_id}/documents \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "ocr_strategy=auto" \
  -F "chunk_size=512" \
  -F 'metadata={"source":"research"}'

Field	Type	Default	Description
`files`	File[]	—	One or more files (PDF, DOCX, Markdown, images, text)
`ocr_strategy`	string	`auto`	OCR mode: `auto`, `force`, or `skip`
`chunk_size`	integer	`512`	Characters per text chunk
`chunk_overlap`	integer	`50`	Overlap between consecutive chunks
`metadata`	string	—	Optional JSON metadata attached to uploaded documents

Async processing

Each file becomes a background job. Use the Jobs API to track progress. Credits are held at upload time and reconciled when processing completes.

Check Readiness

bashcurl https://api.schift.io/v2/buckets/{bucket_id}/search/status \
  -H "Authorization: Bearer $SCHIFT_API_KEY"

Search Bucket

bashcurl -X POST https://api.schift.io/v2/buckets/{bucket_id}/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query": "attention mechanisms in transformers",
    "top_k": 8,
    "context_budget": 4000,
    "options": {
      "rerank": {"enabled": true, "top_k": 20},
      "instructions": {"task": "retrieval_query"}
    }
  }'

Field	Type	Default	Description
`query`	string	—	Natural language search query
`top_k`	integer	`8`	Maximum cited passages to return
`context_budget`	integer	server default	Approximate maximum context size
`filters`	object	—	Metadata filters for results
`options.rerank`	object	—	Optional ranking controls

V2 search returns answer-ready context plus citations. The server owns embedding, hybrid retrieval, reranking, context packing, and warning handling.

List & Delete

bash# List all buckets
curl https://api.schift.io/v2/buckets \
  -H "Authorization: Bearer $SCHIFT_API_KEY"

# Delete a bucket (irreversible)
curl -X DELETE https://api.schift.io/v2/buckets/{bucket_id} \
  -H "Authorization: Bearer $SCHIFT_API_KEY"

Supported file types

PDF, DOCX, Markdown, plain text, and images (JPG, PNG, WebP, TIFF, BMP, GIF). Images and scanned PDFs are processed with OCR automatically when ocr_strategy is auto.

Use v2 for new integrations

Older v1 bucket search, query, collection grant, edge, and facet routes are compatibility or internal surfaces. New docs and product integrations should use v2 bucket documents and v2 bucket search.