Docs

Buckets

Upload files into a bucket and let Schift handle OCR, chunking, embedding, and indexing. Then search across all documents with a single query.

Create Bucket

bashcurl -X POST https://api.schift.io/v1/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/v1/buckets/{bucket_id}/upload \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "ocr_strategy=auto" \
  -F "chunk_size=512"

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

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.

Search Bucket

bashcurl -X POST https://api.schift.io/v1/buckets/{bucket_id}/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{"query": "attention mechanisms in transformers", "top_k": 5}'

Field	Type	Default	Description
`query`	string	—	Natural language search query
`top_k`	integer	`10`	Number of results to return
`model`	string	bucket default	Override embedding model for the query
`filter`	object	—	Metadata filter for results

Results include the matching text chunk, similarity score, source file name, and chunk metadata.

List & Delete

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

# Delete a bucket (irreversible)
curl -X DELETE https://api.schift.io/v1/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.

Edges

Define relationships between nodes in a bucket. Use edges to express curriculum order, legal precedent chains, document hierarchy, and more.

bash# Add edges
curl -X POST https://api.schift.io/v1/buckets/{bucket_id}/edges \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "edges": [
      {"source": "case-2024-456", "target": "case-2024-123", "relation": "supersedes"},
      {"source": "chapter-1", "target": "section-1-1", "relation": "has_child"}
    ]
  }'

# List edges for a node
curl https://api.schift.io/v1/buckets/{bucket_id}/edges/{node_id}?direction=both \
  -H "Authorization: Bearer $SCHIFT_API_KEY"

# Delete an edge
curl -X DELETE https://api.schift.io/v1/buckets/{bucket_id}/edges \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{"source": "A", "target": "B", "relation": "related_to"}'

relation	Description	Example
`contradicts`	Two nodes conflict with each other	Conflicting rulings
`supersedes`	Source replaces target	Amended precedent
`caused_by`	Causal relationship	Root cause
`is_a`	Classification / type relationship	Category
`related_to`	General association	Default
`has_child`	Parent → child structure	Document hierarchy
`follows`	Sequential ordering	Curriculum order