Quick Startクイックスタート

The Saachi API is a REST API served at https://saachi.ai. Interactive OpenAPI docs are available at /docs.

Saachi APIは https://saachi.ai で提供されるREST APIです。インタラクティブなOpenAPIドキュメントは /docs から利用できます。

Every example below uses an API key. Create one from Account → API Keys in the dashboard (or via the keys endpoint).

以下の例ではAPIキーを使用します。ダッシュボードの アカウント → APIキー から作成できます（またはキーエンドポイント経由で）。

1. Create a collection1. コレクションを作成

curl -X POST https://saachi.ai/collections \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Knowledge Base"}'
# → {"id": "...", "name": "My Knowledge Base", ...}

2. Upload files2. ファイルをアップロード

curl -X POST https://saachi.ai/collections/<collection_id>/ingest \
  -H "Authorization: Bearer <api_key>" \
  -F "files=@/path/to/document.pdf"

3. Ask a question3. 質問する

curl -X POST https://saachi.ai/collections/<collection_id>/query/sync \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"question": "What does the contract say about renewal?"}'
# → {"answer": "...", "sources": [...], "sources_used": [0], ...}

Authentication認証

All requests authenticate with an API key in the Authorization header:

すべてのリクエストは Authorization ヘッダーのAPIキーで認証します：

Authorization: Bearer <api_key>

Keys are issued per account and shown only once at creation — save the value immediately.

キーはアカウントごとに発行され、作成時に一度だけ表示されます — すぐに保存してください。

Key typesキーの種類

Key scopeキーのスコープ

Manage keys programmatically under Account → Keys.

APIキーはプログラムからアカウント → キーで管理できます。

Collectionsコレクション

A collection is an isolated knowledge base. Files, folders, and vector embeddings are scoped per collection.

コレクションは独立したナレッジベースです。ファイル、フォルダ、ベクトル埋め込みはコレクションごとにスコープされます。

GET /collections

List all collections the key can access.

キーがアクセスできるすべてのコレクションを一覧表示します。

POST /collections

Create a collection. Body: {"name": "My KB"}. Returns the new collection with its id.

コレクションを作成します。ボディ：{"name": "My KB"}。新しいコレクションと id を返します。

GET /api/collections/<id>

Fetch a single collection's metadata (name, timestamps, file counts).

コレクションのメタデータ（名前、タイムスタンプ、ファイル数）を取得します。

PATCH /collections/<id>

Rename a collection. Body: {"name": "New name"}.

コレクション名を変更します。ボディ：{"name": "新しい名前"}。

DELETE /collections/<id>

Delete a collection and all of its folders, files, and embeddings. Irreversible.

コレクションとすべてのフォルダ、ファイル、埋め込みを削除します。元に戻せません。

Foldersフォルダ

Folders group files inside a collection. A file is active in queries only if its folder is enabled (or the file has no folder).

フォルダはコレクション内のファイルをグループ化します。フォルダが有効な場合のみ、そのファイルがクエリで使用されます（フォルダなしのファイルは常にアクティブ）。

GET /collections/<id>/folders

List folders with their enabled flag and file_count.

enabled フラグと file_count を含むフォルダ一覧を返します。

POST /collections/<id>/folders

Create a folder. Body: {"name": "Contracts"}.

フォルダを作成します。ボディ：{"name": "契約書"}。

PATCH /collections/<id>/folders/<folder_id>

Toggle a folder on or off. Body: {"enabled": false}. Disabling a folder excludes all its files from retrieval without changing individual file flags.

フォルダのオン/オフを切り替えます。ボディ：{"enabled": false}。無効化すると個別ファイルのフラグを変更せずに検索から除外されます。

DELETE /collections/<id>/folders/<folder_id>

Delete a folder. Files inside are moved back to the collection root.

フォルダを削除します。フォルダ内のファイルはコレクションのルートに移動します。

Filesファイル

GET /collections/<id>/files

List files. Each record includes id, filename, file_type, enabled, chunk_count, folder_id, and an optional profile summary.

ファイル一覧を返します。各レコードには id、filename、file_type、enabled、chunk_count、folder_id、オプションの profile サマリーが含まれます。

PATCH /collections/<id>/files/<file_id>

Update a file. Any subset of fields:

ファイルを更新します。任意のフィールドの組み合わせ：

{
  "enabled": false,          // toggle in/out of retrieval
  "filename": "renamed.pdf", // rename the record
  "folder_id": "folder-abc"  // move to folder (null = collection root)
}

DELETE /collections/<id>/files/<file_id>

Delete a file, its chunks, and its embeddings.

ファイル、チャンク、埋め込みを削除します。

GET /collections/<id>/files/<file_id>/content

Return the extracted plain-text of the file (the text actually used for retrieval).

ファイルから抽出されたプレーンテキスト（検索に使用されるテキスト）を返します。

GET /collections/<id>/files/<file_id>/download

Download the original uploaded file.

元のアップロードファイルをダウンロードします。

Ingestionインジェスト

POST /collections/<id>/ingest

Upload one or more files. Returns immediately with queued job IDs — parsing, chunking, and embedding happen asynchronously.

1つ以上のファイルをアップロードします。キューに入ったジョブIDをすぐに返します — 解析、チャンク化、埋め込みは非同期で処理されます。

Supported formats:

対応フォーマット：

• Text:テキスト： .txt .md .pdf .docx .csv .html
• Audio / video音声 / 動画 (transcribed with Whisper):（Whisperで文字起こし）： .mp3 .wav .m4a .ogg .flac .mp4 .webm

Optional form field folder_id places the files into a specific folder.

オプションのフォームフィールド folder_id でファイルを特定のフォルダに配置できます。

curl -X POST https://saachi.ai/collections/<id>/ingest \
  -H "Authorization: Bearer <api_key>" \
  -F "files=@report.pdf" \
  -F "files=@notes.md" \
  -F "folder_id=folder-abc"
# → [{"job_id": "...", "filename": "report.pdf", "status": "pending"}, ...]

GET /collections/<id>/ingest/jobs

Returns ingest jobs that are still in progress (pending, processing, or failed). Completed jobs drop off this list once the file shows up in /files.

進行中のインジェストジョブ（pending、processing、failed）を返します。完了したジョブは /files にファイルが表示されると一覧から消えます。

# → [{"id": "...", "filename": "report.pdf", "status": "processing"}, ...]

Queryingクエリ

Four query endpoints share the same request body. Pick by response shape and retrieval strategy.

4つのクエリエンドポイントは同じリクエストボディを共有します。レスポンス形式と検索戦略に応じて選択してください。

Request bodyリクエストボディ

POST /collections/<id>/query/sync

Single JSON response. Best for scripts and integrations.

単一のJSONレスポンス。スクリプトや連携に最適です。

curl -X POST https://saachi.ai/collections/<id>/query/sync \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the refund policy?"}'

{
  "answer": "Refunds are accepted within 30 days of purchase.",
  "sources": [
    {"filename": "policy.md", "score": 0.91, "chunk": "...", "chunk_index": 0, "file_id": "..."}
  ],
  "sources_used": [0],
  "model": "meta-llama/llama-4-scout-17b-16e-instruct",
  "prompt_tokens": 1240,
  "completion_tokens": 52
}

sources_used is a 0-indexed list of which sources the model cited. null means no citation footer was found.

sources_used はモデルが引用したソースの0始まりのインデックスリストです。null は引用フッターが見つからなかったことを意味します。

POST /collections/<id>/query

Streaming response (Server-Sent Events). Best for UIs showing tokens as they arrive.

ストリーミングレスポンス（Server-Sent Events）。トークンをリアルタイムで表示するUIに最適です。

data: {"sources": [{"filename": "policy.md", "score": 0.91, "chunk": "..."}]}
data: {"token": "Refunds"}
data: {"token": " are"}
...
data: {"sources_used": [0]}
data: {"done": true}

POST /collections/<id>/query/deep

Deep Research: the server splits the question into sub-questions, retrieves for each, and synthesises a longer answer. Costs roughly 3× a standard query. Streams SSE events including per-step progress.

ディープリサーチ：サーバーが質問をサブ質問に分解し、それぞれ検索してより詳細な回答を合成します。標準クエリの約3倍のコストです。SSEでステップごとの進捗をストリームします。

POST /collections/<id>/query/multilingual

Translates the question, retrieves in the source and English, and merges the results before answering. Streams SSE. The model field is ignored — multilingual runs on a server-pinned model.

質問を翻訳し、元の言語と英語で検索してから回答します。SSEをストリームします。model フィールドは無視され、多言語モードはサーバー固定のモデルで動作します。

Sharing共有

Generate a public share link for a collection. Anyone with the link can ask questions; they cannot add, modify, or delete content.

コレクションの公開共有リンクを生成します。リンクを持つ誰でも質問できますが、コンテンツの追加・変更・削除はできません。

GET /collections/<id>/share

Return the active share config, or null if none exists.

アクティブな共有設定を返します。存在しない場合は null を返します。

POST /collections/<id>/share

Create or update a share link. Body accepts settings like allowed model, deep-research permission, and monthly credit cap.

共有リンクを作成または更新します。ボディには許可モデル、ディープリサーチ権限、月次クレジット上限などの設定を指定できます。

DELETE /collections/<id>/share

Revoke the share link immediately.

共有リンクを即座に無効化します。

Teamチーム

Invite teammates into your account. Each member gets their own login and can be granted their own API keys.

アカウントにチームメンバーを招待します。各メンバーは独自のログインと独自のAPIキーを持てます。

GET /account/members

List active members and pending invites.

アクティブなメンバーと保留中の招待を一覧表示します。

POST /account/members/invite

Send an invite email. Body: {"email": "new@teammate.com"}.

招待メールを送信します。ボディ：{"email": "new@teammate.com"}。

DELETE /account/members/<user_id>

Remove a member from the account.

アカウントからメンバーを削除します。

DELETE /account/invites/<invite_id>

Cancel a pending invite.

保留中の招待をキャンセルします。

Accountアカウント

GET /account/me

Return the principal tied to the current key (user id, email, account id, role).

現在のキーに紐づくプリンシパル（ユーザーID、メール、アカウントID、役割）を返します。

GET /account/usage

Spend and query counts for the current billing month.

現在の請求月の支出とクエリ数を返します。

curl https://saachi.ai/account/usage \
  -H "Authorization: Bearer <api_key>"
# → {"used": 0.42, "limit": 10.0, "remaining": 9.58, "currency_label": "$",
#    "plan": "pro", "query_count_this_month": 38, ...}

Manage API keysAPIキーの管理

GET /account/keys

List existing keys (prefix, name, type, scope, limits, last-used timestamp). Raw key values are never returned again after creation.

既存のキー（プレフィックス、名前、種類、スコープ、制限、最終使用タイムスタンプ）を一覧表示します。キーの値は作成後に再表示されません。

POST /account/keys

curl -X POST https://saachi.ai/account/keys \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "key_type": "admin",
    "scope": "account",
    "monthly_spend_limit_usd": 5.00
  }'
# → {"id": "...", "key": "sk-...", "monthly_spend_limit_usd": 5.0, ...}

For a collection-scoped key, send "scope": "collection" and "collection_ids": ["...","..."].

コレクションスコープのキーの場合、"scope": "collection" と "collection_ids": ["...","..."] を送信します。

PATCH /account/keys/<key_id>

Update a key's monthly spend limit without rotating it. Body: {"monthly_spend_limit_usd": 10.0}.

キーをローテーションせずに月次支出制限を更新します。ボディ：{"monthly_spend_limit_usd": 10.0}。

DELETE /account/keys/<key_id>

Revoke a key. Subsequent requests using it return 401.

キーを無効化します。以降のリクエストは 401 を返します。

Modelsモデル

Pass a model field in your query body to override the server default (meta-llama/llama-4-scout-17b-16e-instruct).

クエリボディに model フィールドを指定してサーバーデフォルト（meta-llama/llama-4-scout-17b-16e-instruct）を上書きできます。

Deep Research and Multilingual endpoints ignore the model field and use server-pinned models.

ディープリサーチと多言語エンドポイントは model フィールドを無視し、サーバー固定のモデルを使用します。

Errorsエラー

Errors return a JSON body: {"detail": "..."}.

エラーはJSONボディ {"detail": "..."} を返します。