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, downloadable, chunk_count, folder_id, source (upload / google_drive / circleback / user_input), ingested_at, and an optional profile summary.

ファイル一覧を返します。各レコードには id、filename、file_type、enabled、downloadable、chunk_count、folder_id、source（upload / google_drive / circleback / user_input）、ingested_at、オプションの 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)
  "downloadable": false      // block visitors on share links / embeds from
                             // downloading this file, even when the surface's
                             // own allow-download setting is on
}

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.

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

Notes written in SaachiSaachiで作成するノート

Notes are Markdown files created directly in Saachi (no upload). They go through the normal ingest pipeline and are the only files whose content can be edited afterwards.

ノートはSaachi内で直接作成するMarkdownファイルです（アップロード不要）。通常のインジェストパイプラインで処理され、作成後にコンテンツを編集できる唯一のファイルです。

POST /collections/<id>/files/manual

{
  "title": "Meeting follow-ups",   // becomes the filename
  "content": "## Action items…",   // Markdown body
  "folder_id": "folder-abc"        // optional
}

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

Return the note's Markdown content. 403 unless the file's source is user_input.

ノートのMarkdownコンテンツを返します。ファイルの source が user_input でない場合は 403 を返します。

PUT /collections/<id>/files/<file_id>/manual

Replace the note's content and re-ingest it. Body: {"content": "…"}. Same 403 rule as above.

ノートのコンテンツを置き換えて再インジェストします。ボディ：{"content": "…"}。上記と同じ 403 ルールが適用されます。

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 .pptx .csv .xlsx .html
• .pptx decks are parsed slide-by-slide, speaker notes included. Google Docs, Sheets, and Slides import via the Google Drive integration..pptx はスライド単位で解析され、スピーカーノートも含まれます。Google ドキュメント・スプレッドシート・スライドは Google Drive 連携からインポートできます。
• 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リクエストボディ

Both date filters apply to files.ingested_at (upload time to Saachi), not any date inherent to the document itself.

日付フィルタはどちらもドキュメント自体の日付ではなく、files.ingested_at（Saachiへの取り込み日時）でフィルタします。

Query syntaxクエリ構文

Two inline operators tune retrieval inside the question string itself:

question 文字列内で使える2つのインライン演算子で検索を調整できます：

• |phrase| — positive pin: boosts chunks containing this exact phrase.|フレーズ| — ポジティブピン：このフレーズを含むチャンクを優先します。
• !term! — negative exclude: removes every chunk containing this term before retrieval runs. Example: "best healing item !potion!"!用語! — ネガティブ除外：この用語を含むチャンクを検索前に除外します。例："best healing item !potion!"

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": "openai/gpt-oss-20b",
  "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. All fields optional:

共有リンクを作成または更新します。すべてのフィールドは省略可能です：

{
  "model": "fast",               // tier name; null = server default
  "deep_research": false,        // let visitors run Deep Research
  "allow_download": false,       // let visitors download source files
                                 // (files marked downloadable:false stay blocked)
  "conversation": false,         // multi-turn chat with memory of earlier questions
  "sql_dive": false,             // SQL analysis over ingested CSV/Excel tables
  "monthly_spend_limit_usd": 0   // monthly credit cap for the link (0 = default)
}

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,
    "default_model": "fast"
  }'
# → {"id": "...", "key": "sk-...", "monthly_spend_limit_usd": 5.0, ...}

For a collection-scoped key, send "scope": "collection" and "collection_ids": ["...","..."]. default_model takes a tier name (see Models).

コレクションスコープのキーの場合、"scope": "collection" と "collection_ids": ["...","..."] を送信します。default_model にはティア名を指定します（モデル参照）。

Keys of type embed additionally accept feature flags controlling what the widget offers its visitors: allow_deep_research, allow_download, allow_conversation, allow_sql_dive (all default false). Note that even with allow_download on, individual files marked "downloadable": false stay blocked.

embed タイプのキーは、ウィジェットが訪問者に提供する機能を制御するフラグも受け付けます：allow_deep_research、allow_download、allow_conversation、allow_sql_dive（すべてデフォルト false）。allow_download が有効でも、"downloadable": false のファイルはダウンロードできません。

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. Use one of the tier names below, not a raw provider model ID — which physical model backs each tier can change over time, so pinning a tier keeps working across those changes automatically.

クエリボディに model フィールドを指定してサーバーデフォルトを上書きできます。プロバイダーの生のモデルIDではなく、以下のいずれかのティア名を指定してください — 各ティアの背後にある実際のモデルは変更される場合がありますが、ティア名を指定していればその変更後も自動的に動作し続けます。

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

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

Errorsエラー

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

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