User Guide

This guide walks you through the most common ways to use Schift. It covers the dashboard, REST API, Python and TypeScript SDKs, the CLI, and the Model Context Protocol (MCP) server.

Before you start

You need a Schift account and an API key. If you do not have a key yet, create one from the dashboard at {appUrl}.

Most examples below use environment variables:

export SCHIFT_API_KEY=sch_your_key_here
export SCHIFT_API_URL=<your-api-url>

For this environment, set SCHIFT_API_URL to {apiUrl}. Keep your API key secret, rotate keys regularly, and use a separate key for each environment.

Choose the right surface

Surface	Best for	Entry point
Dashboard	Key management, billing, and checking bucket status	`{appUrl}`
REST API	Direct backend integration	`{apiUrl}`
Python SDK	Scripts, ingestion, search, and migrations	`pip install schift`
TypeScript SDK	TypeScript or Node.js applications	`npm install @schift-io/sdk`
CLI	Repeatable terminal operations	`pip install schift-cli`
MCP	Claude Desktop or Claude Code connection	`npx schift-mcp`

Quick installation checklist

# Python SDK
pip install schift

# TypeScript SDK
npm install @schift-io/sdk

# CLI
pip install schift-cli
schift --help

# MCP server
npx schift-mcp

Typical workflow

Create a bucket from the dashboard or with POST /v2/buckets.
Upload documents to the bucket with POST /v2/buckets/{bucket_id}/documents.
Wait for indexing and check readiness with GET /v2/buckets/{bucket_id}/search/status.
Search the bucket with POST /v2/buckets/{bucket_id}/search to get cited context.
Ask questions with POST /v1/chat to get a bucket-backed RAG answer.

Note: Bucket search is the upload-first, ingest-optimized surface. Use POST /v1/collections/{name}/search only for legacy integrations.

Common endpoints

POST /v2/buckets
POST /v2/buckets/{bucket_id}/documents
GET /v2/buckets/{bucket_id}/search/status
POST /v2/buckets/{bucket_id}/search
POST /v1/chat
POST /v1/chat/completions

Authentication

All API requests use Bearer authentication:

curl -H "Authorization: Bearer $SCHIFT_API_KEY" \
  $SCHIFT_API_URL/v2/buckets

Use the same SCHIFT_API_KEY value across the SDKs, CLI, and MCP so tools do not use different keys in the same environment.

Next steps

Create and manage knowledge in Buckets.
Search uploaded content with Bucket Search.
Get grounded answers with RAG Chat.
Route OpenAI-compatible requests through Chat Completions.
If you are migrating an older integration, see the Legacy Collections API.