Buckets

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"}'

Bucket Collections

Collections are permission and search shards inside a bucket. Uploads can target a collection, and bucket search fans out only to collections the caller can search.

bash# Create a child collection
curl -X POST https://api.schift.io/v1/buckets/{bucket_id}/collections \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{"name": "support-only", "description": "Support team corpus"}'

# Grant search access to a role
curl -X POST https://api.schift.io/v1/buckets/{bucket_id}/collections/{collection_id}/grants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{"subject_type": "role", "subject_id": "support", "permission": "search"}'

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 "files=@report.pdf" \
  -F "files=@notes.md" \
  -F "collection_id={collection_id}" \
  -F "ocr_strategy=auto" \
  -F "chunk_size=512"

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}'

Search is permission-scoped. The server computes the caller's searchable collections, searches those collections, then merges the ranked 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"

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"}'