SDK

The current TypeScript SDK contract is 0.16.0 in the repository. It covers bucket search, embeddings, Warehouse Data, and Structify. Python and CLI surfaces are documented separately where their contracts differ.

SDK packages

Package	Language	Install	Use case
`schift`	Python	`pip install schift`	Python apps, notebooks, data pipelines
`@schift-io/sdk`	TypeScript	`npm install @schift-io/sdk`	Bucket search, embeddings, Warehouse Data, Structify
`schift-cli`	Python CLI	`pip install schift-cli`	Repeatable terminal workflows and ops

Release note: The repository contract is 0.16.0. Check the npm registry before pinning a released version; the local source and the public registry are separate release lanes.

Authentication

Create an API key in Console → API keys (/app/console/keys), then configure it with an environment variable or explicit constructor argument.

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

For this environment, set SCHIFT_API_URL to {apiUrl}/v1. The SDKs also read SCHIFT_BASE_URL as a fallback for the API origin. The CLI reads SCHIFT_API_KEY first, then falls back to ~/.schift/config.json written by schift auth login.

Environment variables

Variable	Used by	Purpose
`SCHIFT_API_KEY`	Python SDK, TypeScript SDK, CLI	API key (`sch_...`)
`SCHIFT_API_URL`	Python SDK, TypeScript SDK, CLI	Full API base URL, usually ending in `/v1`
`SCHIFT_BASE_URL`	Python SDK, TypeScript SDK	API origin without the `/v1` path

Note: When SCHIFT_API_URL is missing, the SDKs and CLI do not assume a production origin. Set it explicitly for local, staging, or hosted workspaces.

Python SDK

The Python SDK exposes two client styles:

WorkspaceClient: modular client for live API operations such as bucket ingest, search, embeddings, and usage.
Client: legacy projection client for fitting and downloading Projection objects that run locally.

WorkspaceClient

from schift import WorkspaceClient

with WorkspaceClient() as client:
    bucket = client.buckets.create(name="finance-docs")
    upload = client.buckets.upload(
        bucket["id"],
        [("files", ("q1-report.pdf", open("q1-report.pdf", "rb").read(), "application/pdf"))],
    )
    hits = client.buckets.search(
        bucket["id"],
        "revenue guidance",
        top_k=5,
    )

WorkspaceClient holds a shared httpx.Client, so prefer a context manager for short-lived scripts. For long-running processes, keep one instance and call close() during shutdown.

Core modules

Module	Example call	Purpose
`catalog`	`client.catalog.list()`	List embedding models
`embed`	`client.embed(text, model=...)`	Single-text embedding
`embed.batch`	`client.embed.batch(texts=[...])`	Batch embedding
`buckets`	`client.buckets.create(name=...)`	Bucket ingest and search
`db`	`client.db.upsert(collection=...)`	Raw vector and document upserts
`query`	`client.query("...", bucket=...)`	Hosted bucket or passthrough search
`rerank`	`client.rerank(query, documents=[...])`	Rerank candidates
`pii`	`client.redact_pii(text, types=[...])`	Mask Korean PII
`usage`	`client.usage.get(period="30d")`	Usage summaries

TypeScript SDK

The TypeScript SDK centers on WorkspaceClient.

The 0.16.0 exports also include DataClient, VectorClient, and StructifyClient as separate current surfaces. Use them for Parquet-backed Warehouse Data, caller-computed vector collections, and document structuring. DataClient defaults to https://gw.schift.io; pass dataUrl (or set SCHIFT_DATA_URL) to VectorClient, and gatewayUrl (or set SCHIFT_GATEWAY_URL) to StructifyClient.

import { WorkspaceClient } from "@schift-io/sdk";

const client = new WorkspaceClient({
  apiKey: process.env.SCHIFT_API_KEY!,
  baseUrl: process.env.SCHIFT_API_URL!,
});

await client.createBucket({ name: "company-docs" });
const file = new File([await readFile("manual.pdf")], "manual.pdf", {
  type: "application/pdf",
});
await client.db.upload("company-docs", { files: [file] });

const results = await client.bucketSearch("company-docs", {
  query: "refund policy",
  topK: 5,
});

Core methods

Method	Purpose
`embed(request)`	Single-text embedding
`embedBatch(request)`	Batch embedding
`search(request)`	Vector search
`bucketSearch(nameOrId, request)`	Search a bucket
`chat(request)`	Bucket-backed RAG chat
`chatStream(request)`	Streaming RAG chat
`webSearch(query, maxResults?)`	Web search
`redactPii(request)`	Mask Korean PII
`mask(text, options)`	Convenience PII mask
`restorePii(request)`	Restore PII tokens locally
`data.put(where, input, options?)`	Write JSON, NDJSON, or Parquet rows
`data.search(where, options?)`	Filtered, text, and near search over warehouse rows
`data.aggregate(where, spec)`	Group and measure hot/cold rows
`vectors.upsert(collection, records)`	Store caller-computed vectors
`StructifyClient.ocr()` / `.structify()`	OCR and schema-guided extraction
`tools.openai()` / `tools.anthropic()` / `tools.vercelAI()`	Tool definitions for provider SDKs

Note: For a complete TypeScript class and type reference, see the SDK API Reference.

CLI

The Python schift-cli package installs a schift executable.

pip install schift-cli
schift auth login
schift auth status

Command groups

Command	Purpose
`schift auth ...`	Manage local authentication state
`schift catalog ...`	Browse supported embedding models
`schift embed ...`	Generate embeddings from text
`schift db ...`	Create, list, and inspect buckets
`schift upload ...`	Upload files into a bucket
`schift jobs ...`	Inspect, reprocess, and cancel ingest jobs
`schift search ...`	Run bucket search
`schift query ...`	Compatibility alias for bucket search
`schift usage ...`	Show aggregated usage and billing summary

Common workflow

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

schift upload ./handbook.pdf --bucket company-docs
schift jobs list --bucket company-docs
schift search "revenue report" --bucket company-docs --top-k 5

Retired compatibility surfaces

Managed Agents, Agent Hub, and APM were retired on 2026-09-25. The TypeScript compatibility exports are deprecated and will be removed in the next major; new integrations should use bucket search, Warehouse Data, or Structify instead. The removed providers and migrate SDK clients are not available in 0.16.0.

SchiftIndex

SchiftIndex is the SDK-managed sync surface for repeatable source ingestion into workspace buckets. Use it when a team wants local manifests, text diffs, checkpointed sync, retry, and source-specific adapters such as Obsidian vault sync.

cd "/path/to/Obsidian Vault"
schift-index init --manifest schift.index.json --template dot-vault
SCHIFT_API_KEY=... schift-index sync --manifest schift.index.json --cloud

Error handling

Python SDK errors:

from schift import WorkspaceClient
from schift import AuthError, QuotaError, SDKError

try:
    with WorkspaceClient() as client:
        client.catalog.list()
except AuthError:
    ...
except QuotaError:
    ...
except SDKError:
    ...

TypeScript SDK error classes:

import { AuthError, QuotaError, PlatformError } from "@schift-io/sdk";

try {
  await client.embed({ text: "test" });
} catch (err) {
  if (err instanceof AuthError) {
    // 401
  } else if (err instanceof QuotaError) {
    // 402
  } else if (err instanceof PlatformError) {
    // 403, 422, 429, 500, 502
  }
}

SDK