fast-io

Fast.io MCP サーバー -- AI エージェントガイド

バージョン： 1.200 最終更新日： 2026-04-29

Fast.io MCP サーバーを使用する AI エージェント向けの決定版ガイドです。プラットフォームを使用する理由と方法を網羅しています。製品機能、無料のエージェントプラン、認証、主要な概念（ワークスペース、共有、インテリジェンス、プレビュー、コメント、URL インポート、メタデータ、ワークフロー、所有権の譲渡）、エンドツーエンドのワークフロー 12 種類、インタラクティブな MCP App ウィジェット、アクションベースのルーティングに対応した統合ツール 19 種類を取り上げます。

バージョン管理されたガイドです。 このガイドはバージョン管理されており、サーバーのリリースごとに更新されます。このドキュメントの先頭にあるバージョン番号は、ツールのパラメーター、ID 形式、API の動作の変更を追跡します。予期しないエラーが発生した場合は、最後に読んだときからガイドのバージョンが変わっている可能性があります。

プラットフォームのリファレンスです。 Fast.io の機能、エージェントプラン、主要なワークフロー、アップグレード方法の詳しい概要については、references/REFERENCE.md を参照してください。

---

1. 概要

エージェント型チームのためのワークスペース。すべてを 1 つの API から無料で利用し、AI と共同作業、共有、クエリを実行できます。

Fast.io は、エージェント型チーム向けのワークスペースを提供します。エージェント同士、またエージェントと人間が共同作業できます。成果物をアップロードし、ブランドに合わせた共有リンクを作成し、組み込み AI を使ってドキュメントについて質問し、作業が終わったらすべてを人間に引き継げます。管理が必要なインフラも、設定するサブスクリプションも、クレジットカードも不要です。

Fast.io が解決する問題

エージェント型チーム、つまりエージェント同士や人間と協力して作業するエージェントのグループには、共有して使える作業場所が必要です。現在、エージェントは S3 バケット、署名付き URL、メールの添付ファイル、独自のダウンロードページを寄せ集めて使っています。エージェントはそれぞれ独自に共同作業の仕組みを構築し、エージェントと人間が同じファイルを確認し、アクティビティを追跡し、作業を引き継げる共有ワークスペースはありません。

エージェントがドキュメントを単に保存するのではなく、その内容を理解する必要がある場合、ファイルをダウンロードし、多数の形式を解析し、検索インデックスを構築して、独自の RAG パイプラインを管理しなければなりません。「このドキュメントには何が書かれていますか？」という単純な質問に答えるための仕組みとしては、大がかりです。

問題	Fast.io の解決策
エージェント型チーム向けの共有ワークスペースがない	ファイルプレビュー、バージョン管理、AI を備え、エージェントと人間が共同作業できるワークスペース
エージェント間の連携に構造がない	チームメンバー間のアクティビティフィード、コメント、リアルタイム同期を備えた共有ワークスペース
成果物を人間と共有しにくい	リンク共有、パスワード、有効期限に対応した、用途に合わせて設計された共有（送信、受信、交換）
人間からファイルを集めるのが難しい	受信用共有を使えば、人間がメール添付なしでワークスペースに直接アップロードできます
ドキュメントの内容を理解しにくい	組み込み AI がファイルを読み取り、要約し、質問に回答します
RAG パイプラインを一から構築する必要がある	ワークスペースでインテリジェンスを有効にすると、ドキュメントが自動的にインデックス化、要約され、クエリ可能になります
大量のファイルの中から目的のファイルを見つけにくい	ストレージ検索でキーワードや意味からドキュメントを検索できます（インテリジェンスが有効な場合はセマンティック検索）
プロジェクトを人間に引き継ぎにくい	ワンクリックで所有権を譲渡できます。人間が組織を引き継ぎ、エージェントは管理者アクセスを維持します
何が起きたかを追跡しにくい	AI を活用したアクティビティ要約を備えた完全な監査証跡
コスト	無料。ストレージ 50 GB、月間クレジット 5,000、クレジットカード不要

MCP サーバー

この MCP サーバーは、Fast.io REST API の全機能を網羅する19個の統合ツールを提供します。認証が必要なすべての API エンドポイントに対応するツールアクションがあり、サーバーがセッション管理を自動的に処理します。

すべての API アクセスには MCP ツールを使用してください。 api.fast.io や MCP サーバーに直接 HTTP リクエストを送信しないでください。ツールが認証、セッション管理、エラー復旧、レスポンスの整形を自動的に処理します。例外はバイナリ転送のみです。アップロードには MCP サーバー上の POST /blob を使用します（ツールが curl コマンドを提供します）。ツールから返されるダウンロード URL（事前認証済み）と、大容量ファイルのストリーミング用に MCP サーバー上の GET /file/ パススルーエンドポイントも使用できます。それ以外はすべてツールを使用してください。

ユーザーが認証すると、認証トークンはサーバーセッションに保存され、以降のすべての API 呼び出しに自動的に付加されます。ツール呼び出しの間でトークンを渡す必要はありません。

サーバーエンドポイント

• 本番環境： mcp.fast.io
• 開発環境： mcp.fastdev1.com

それぞれで、次の2種類のトランスポートを利用できます。

• /mcp の Streamable HTTP — 新しい統合で推奨されるトランスポートです。
• /sse の SSE — 後方互換性のために維持されているレガシートランスポートです。

MCP リソース

サーバーは、静的 MCP リソース、ウィジェットリソース、ファイルダウンロードリソーステンプレートを公開します。クライアントは resources/list と resources/read を使用して読み取ることができます。

URI	名前	説明	MIME タイプ
skill://guide	skill-guide	19個すべてのツール、ワークフロー、プラットフォームのドキュメントを含むエージェント向けガイド（このドキュメント）	text/markdown
session://status	session-status	現在の認証状態：authenticated のブール値、user_id、user_email、auth_method（セッションの認証方法を示す "api_key"、"jwt"、"oauth" のいずれか）、token_expires_at（Unix エポック）、token_expires_at_iso（ISO 8601）、scopes（スコープ文字列、または null）、scopes_detail（エンティティ名、ドメイン、親情報を含む補完済みスコープオブジェクトの配列、または null）、agent_name（文字列、または null）	application/json
widget://*	ウィジェット HTML	インタラクティブな HTML5 ウィジェット（全6種類）。検出して起動するには apps ツールを使用します	text/html

ファイルダウンロードリソーステンプレート — 外部 HTTP アクセスを必要とせず、MCP 経由でファイルの内容を直接読み取れます。

URI Template	名前	認証	動的リスト表示	説明
download://workspace/{workspace_id}/{node_id}	download-workspace-file	セッショントークン	はい	ワークスペースからファイルをダウンロードします
download://share/{share_id}/{node_id}	download-share-file	セッショントークン	はい	共有からファイルをダウンロードします
download://quickshare/{quickshare_id}	download-quickshare-file	なし（公開）	いいえ	クイック共有ファイルをダウンロードします

50 MB 以下のファイルは、base64 エンコードされた blob コンテンツとしてインラインで返されます。それより大きなファイルの場合は、HTTP パススルーエンドポイントへの URL を含むテキスト形式の代替レスポンスが返されます（下記参照）。download ツールのレスポンスには、各ファイルに対応する URI を示す resource_uri フィールドが含まれます。

動的リソースのリスト表示： 認証済みの場合、ワークスペースと共有のファイルリソースは resources/list を通じて動的にリスト表示されます。MCP クライアント（Claude Desktop の @ メンションピッカーなど）は、ツールを呼び出さなくても利用可能なファイルを検出できます。最大10個のワークスペースと10個の共有が列挙され、それぞれから更新日時が新しいルートレベルのファイルが最大25個含まれます。リソースは「WorkspaceName / filename.ext」または「ShareTitle / filename.ext」として表示されます。結果はセッションごとに1分間キャッシュされます。リスト表示されるのはルートレベルのファイルのみで、サブディレクトリは再帰的に列挙されません。さらに詳しく参照するには、storage ツールのアクション list を使用してください。クイック共有テンプレートはテンプレートのみで、動的に列挙することはできません。

MCP プロンプト

サーバーは、クライアントの「追加元」／「＋」メニューに表示される、ユーザーがクリックして起動できるアプリランチャーとして機能する MCP プロンプトを登録します。主にデスクトップ MCP クライアント（例：Claude Desktop）向けです。コードモードのクライアント（Claude Code、Cursor）ではプロンプトは表示されません。

プロンプト名	説明
App: Choose Workspace or Org	Workspace Picker を起動して、組織の参照、ワークスペースの選択、共有の管理を行います
App: Pick a File	ワークスペースナビゲーターを内蔵した File Picker を起動して、ファイルの参照、検索、選択を行います
App: Open Workflow	Workflow Manager を起動します（ワークスペースが1つだけの場合は自動選択し、複数ある場合は先に Workspace Picker を開きます）
App: Upload Files	Uploader を起動して、ドラッグ＆ドロップ、進行状況の追跡、テキストファイルの作成によるファイルのアップロードを行います
App: Available Apps	利用可能なすべての MCP App ウィジェットを、説明と起動手順とともに一覧表示します

HTTP ファイルパススルー

50 MB を超えるファイル、またはバイナリデータをそのままストリーミングする必要がある場合、サーバーは API からファイルの内容を直接ストリーミングする HTTP パススルーエンドポイントを提供します。

エンドポイント	認証	説明
GET /file/workspace/{workspace_id}/{node_id}	Mcp-Session-Id ヘッダー	ワークスペースのファイルをストリーミングします
GET /file/share/{share_id}/{node_id}	Mcp-Session-Id ヘッダー	共有ファイルをストリーミングします
GET /file/quickshare/{quickshare_id}	なし（公開）	クイック共有ファイルをストリーミングします

応答には、上流 API から取得した適切な Content-Type、Content-Length、Content-Disposition ヘッダーが含まれます。エラーは HTML ページとして返されます。Mcp-Session-Id ヘッダーは、MCP プロトコルの通信で使用されるものと同じセッション識別子です。

ワークフローの概要

サーバーには、プロジェクト追跡用のワークフロー機能として、タスク（優先度と担当者が設定された構造化された作業項目）、作業ログ（追記専用のアクティビティログ）、承認（正式な承認依頼。下記のワークフロー承認 -- クイックスタートを参照）、ToDo（シンプルなチェックリスト）が含まれています。これらのツールを使う前に、workspace アクション enable-workflow でワークスペースのワークフローを有効にしてください。完全な手順については、セクション 6 のエージェント向け完全ワークフローレシピを参照してください。

ベストプラクティス（重要）： 状態を変更するアクション（ファイルのアップロード、共有の作成、タスクのステータス変更、メンバーの変更、ファイルの移動／削除）の後は、実施した内容とその理由を説明する作業ログのエントリーを追加してください。作業ログのエントリーがないと、ワークスペースを確認する人にはエージェントの作業が見えません。関連するアクションを複数まとめて実施する場合（例：複数ファイルのアップロード）は、各アクションの後ではなく、バッチの完了後に一度だけ記録してもかまいません。作業ログのエントリーは追記専用で、永続的に保存されます。

参考資料

• エージェントガイド（このファイル）： MCP サーバー上の /skill.md -- ツールのドキュメント、ワークフロー、制約事項。
• REST API リファレンス： https://api.fast.io/llms.txt -- 基盤となる REST API のエンドポイントに関するドキュメント（参考用です。直接 HTTP 呼び出しではなく、MCP ツールを使用してください）。
• プラットフォームガイド： references/REFERENCE.md -- 機能、エージェントプランの詳細、主なワークフロー、アップグレード方法。

---

2. 認証（最初に必ず実施）

以下の認証不要ツールを除き、ツールを呼び出す前に認証が必要です。

• auth のアクション：signin、signup、set-api-key、pkce-login、email-check、password-reset-request、password-reset
• download のアクション：quickshare-details

適切な方法の選択

エージェントとして Fast.io を利用する方法は、自律的に動作するか、既存の人間ユーザーを支援するかによって3つあります。

オプション 1：自律型エージェント -- エージェントアカウントを作成する 独立して稼働する（ファイルを保存する、ワークフローを実行する、ユーザー用のワークスペースを構築する）場合は、auth アクション signup で独自のエージェントアカウントを作成してください。エージェントアカウントには無料のエージェントプラン（50 GB、月間5,000クレジット）が適用され、準備ができたら組織を人間に移管できます。自律型エージェントには、この方法を推奨します。手順については、下記のエージェントアカウントの作成をご覧ください。

オプション 2：人間を支援する — 相手の API キーを使用する

人間がすでに Fast.io アカウントを持っており、ファイル、ワークスペース、共有の管理をあなたに任せたい場合は、あなたが使用する API キーを作成できます。エージェントアカウントを別途作成する必要はありません。人間のユーザーとして操作します。人間は「Settings -> Devices & Agents -> API Keys」（直接リンク：https://go.fast.io/settings/api-keys）でキーを作成します。auth のアクション set-api-key を呼び出し、キーを指定して認証します。キーは検証され、MCP セッションに自動的に保存されます。その後のツール呼び出しではすべて、そのキーが使用されます。デフォルトでは、API キーにはアカウント所有者と同じ権限が付与されます。キーは任意で、特定の組織、ワークスペース、共有にスコープを設定できます（OAuth トークンと同じスコープシステムを使用します）。スコープ設定済みのキーは、許可されたエンティティにのみアクセスでき、スコープ外の操作は 403 を返します。また、追跡用に agent_name タグを付けたり、有効期限を設定したりすることもできます。スコープが設定されていないキーは、取り消されない限り期限切れになりません。エージェントは、auth アクション api-key-create、api-key-update、api-key-list、api-key-get、api-key-delete を使って、プログラムから API キーを管理することもできます。

オプション 3：人間の組織に招待されたエージェントアカウント

独自のエージェント ID を持ちながら、人間の既存の組織内で作業する必要がある場合は、auth アクション signup でエージェントアカウントを作成し、その後、人間に member アクション add（entity_type org）で組織に招待してもらうか、member アクション add（entity_type workspace）でワークスペースに招待してもらいます。また、人間は UI の「Settings -> Your Organization -> Manage People」から招待することもできます。これにより、自分のアカウントを別に保ったまま、相手のワークスペースや共有にアクセスできます。user アクション accept-all-invitations で招待を承諾した後、auth アクション signin を使って通常どおり認証してください。注：人間があなたをワークスペースのみに招待した場合（組織には招待していない場合）、その組織は外部として表示されます。Organizations セクションの内部組織と外部組織をご覧ください。

オプション 4：ブラウザーログイン（PKCE）

**ヘッドレスエージェントには使用できません：**PKCE では、会話にブラウザーを使える人間が参加している必要があります。ヘッドレスエージェント、CLI ツール、自動化パイプラインではこのフローを完了できません。その場合は、オプション 1（signup）またはオプション 2（API キー）を使用してください。

パスワードをエージェント経由で送信したくない場合は、ブラウザーベースの PKCE ログインを使用してください。auth アクション pkce-login を呼び出すと、ログイン URL が取得できます（任意で email ヒントを指定できます）。ユーザーはブラウザーで URL を開き、サインイン（メールアドレス／パスワード、または Google／Microsoft などの SSO）して、アクセスを承認します。ブラウザーに認証コードが表示されるので、ユーザーがそのコードをエージェントにコピーして渡します。コードを指定して auth アクション pkce-complete を呼び出すと、サインインが完了します。認証情報がエージェントを経由しないため、これが最も安全な方法です。

PKCE ログインでは、scope_type パラメーターを使って任意のスコープ付きアクセスを設定できます。デフォルトでは、scope_type は "user"（アカウント全体へのアクセス）です。その他のスコープタイプでは、トークンを特定のエンティティタイプに制限できます。

scope_type	許可されるアクセス
user	アカウント全体へのアクセス（デフォルト）
org	ユーザーが特定の組織を選択
workspace	ユーザーが特定のワークスペースを選択
all_orgs	ユーザーが所属するすべての組織
all_workspaces	ユーザーがアクセスできるすべてのワークスペース
all_shares	ユーザーがメンバーとなっているすべての共有（share:*:<mode>）

**スコープの継承：**より広いスコープには、子エンティティへのアクセスが自動的に含まれます。

• all_orgsには、すべての組織と、それらの組織内のすべてのワークスペースおよび共有が含まれます
• all_workspacesには、すべてのワークスペースと、それらのワークスペース内のすべての共有が含まれます
• 特定の組織に対するorgスコープでは、その組織内のすべてのワークスペースと共有にアクセスできます
• 特定のワークスペースに対するworkspaceスコープでは、そのワークスペース内の共有にアクセスできます
• all_sharesを指定すると、ワークスペースや組織からの継承を迂回し、ユーザーがメンバーになっているすべての共有に直接アクセスできます

agent_nameパラメーターは、承認画面に表示する内容を制御します。画面には「**[agent_name]**があなたに代わって操作します」と表示されます。省略すると、クライアント名のみが表示されます。どのエージェントがアクセスを要求しているのかユーザーが把握できるよう、内容が分かりやすい名前を使用してください。

scope_typeごとの承認フロー：

• user（デフォルト）：アカウント全体へのアクセスです。ユーザーには、エンティティ選択画面のない、シンプルな承認／拒否の確認が表示されます。
• org、workspace：ユーザーがアクセス可能なエンティティがチェックボックス付きで一覧表示される選択画面と、読み取り専用／読み書きの切り替えが表示されます。ユーザーはアクセスを許可するエンティティを選び、承認または拒否します。
• all_orgs、all_workspaces、all_shares：要求されているワイルドカードアクセスの概要が表示されます（エンティティ選択画面はありません）。その後、ユーザーは承認または拒否します。

下位互換性を保つため、MCP サーバーのscope_typeはデフォルトで"user"です。

シナリオ	推奨される方法
自律的に操作し、ファイルを保存して、ユーザー向けのものを構築する	独自の組織でエージェントアカウントを作成する（オプション 1）
人間が既存のアカウントを管理できるよう支援する	人間にAPIキーを作成してもらう（オプション 2）
独自のIDで人間の組織内で作業する	エージェントアカウントを作成し、人間に招待してもらう（オプション 3）
人間に引き継ぐものを構築する	エージェントアカウントを作成して構築し、その後、組織を譲渡する（オプション 1）
エージェント経由でパスワードを送信せずにサインインする	ブラウザーを使用したPKCEログイン（オプション 4）
ヘッドレス環境で実行する／ブラウザーを利用できない	エージェントアカウントを作成する（オプション 1）か、APIキーを使用する（オプション 2）。PKCEは使用しないでください

**アカウントの種類ごとのクレジット制限：**エージェントアカウント（オプション 1、3）は、クレジットがなくなったときに組織を人間に譲渡できます。セクション 3の「所有権の譲渡」を参照してください。人間のアカウント（オプション 2）では譲渡／申請APIを使用できません。人間には、https://go.fast.io/settings/billingまたはorgアクションbilling-createからプランをアップグレードするよう案内してください。

標準的なサインインフロー

1. アクションsignin、email、passwordを指定してauthを呼び出します。
2. サーバーはJWTのauth_tokenを返し、自動的にセッションに保存します。
3. 以降のすべてのツール呼び出しでは、手動で渡さなくてもこのトークンが使用されます。

エージェントアカウントの作成

新しいアカウントを作成するとき（上記のオプション 1および3）は、エージェントはauthのアクションsignupを必ず使用してください。これにより、agent=trueを指定して自動的に登録されます。人間のアカウントとして登録してはいけません。エージェントアカウントでは、以下が提供されます。

• account_typeは"agent"に設定されます
• 無料のエージェントプランが自動的に割り当てられます
• 組織を人間に引き継ぐための譲渡／申請ワークフローが有効になります

手順：

1. （任意）authのアクションemail-checkを呼び出します。これは参考情報のみです。結果によって処理を中断してはいけません。必ずsignupを試してください。その理由についてはセクション 9を参照してください。
2. first_name、last_name、email、passwordを指定して、authのアクションsignupを呼び出します。agent=trueフラグはMCP サーバーによって自動的に送信されます。
3. アカウントが作成され、セッションも自動的に確立されます。エージェントは直ちにサインインした状態になります。
4. メールアドレスを確認します（ほとんどのエンドポイントを使用する前に必須です）。emailを指定してauthのアクションemail-verifyを呼び出し、確認コードを送信します。その後、emailとemail_tokenを指定して、authのアクションemail-verifyを再度呼び出し、コードを検証します。
5. クレジットカードは不要です。トライアル期間はありません。有効期限もありません。アカウントは無期限に存続します。

2 要素認証のフロー

1. auth アクション signin を email と password とともに呼び出します。
2. レスポンスに two_factor_required: true が含まれている場合、返されたトークンのスコープは制限されています。
3. 2FA の code（TOTP、SMS、または WhatsApp）を指定して、auth アクション 2fa-verify を呼び出します。
4. サーバーは、スコープが制限されたトークンを全スコープのトークンに自動的に置き換えます。

機密性の高い操作でのインライン 2FA

アカウントで 2FA が有効になっている場合、API エンドポイントによっては、リクエストごとの 2FA 検証が必要です。これらの操作には、通常の認証に加えて、有効な 2FA token パラメーター（6 桁の TOTP、または SMS／電話／WhatsApp のコード）が必要です。

• api-key-create — 新しい API キーの作成
• api-key-delete — API キーの取り消し

アカウントで 2FA が有効になっていない場合、これらの操作はトークンなしで通常どおり実行できます。2FA が有効で、トークンがないか無効な場合、リクエストは失敗します。

ワークフロー：

1. 2FA の状態を確認します：auth アクション 2fa-status — state が "enabled" の場合、インライン 2FA が必要です。
2. 認証アプリの TOTP コードをユーザーに求めるか、auth アクション 2fa-send でコードを送信します。
3. コードを token パラメーターとして api-key-create または api-key-delete に渡します。

ヒント： API キー認証（auth アクション set-api-key）では、インライン 2FA チェックが完全に回避されます。エージェントがすでに API キーで認証済みの場合、これらの操作にトークンは不要です。

ブラウザーでのログイン（PKCE）フロー

1. auth アクション pkce-login を呼び出します（任意で、サインインフォームに事前入力する email、スコープ付きアクセスをリクエストする scope_type、エージェントを識別する agent_name を指定できます）。
2. ツールから login_url が返されます。これをユーザーに提示し、ブラウザーで開いてもらいます。
3. ユーザーがサインインします（メールアドレス／パスワードまたは SSO）。
4. ユーザーに、agent_name（指定されていない場合はクライアント名）が表示された承認画面が表示されます。scope_type に応じて、user の場合はそのまま承認し、org／workspace の場合は特定のエンティティと読み取り専用／読み書きアクセスを選択し、all_orgs／all_workspaces／all_shares の場合はワイルドカードアクセスの概要を確認します。
5. ユーザーが「承認」をクリックします。ブラウザーに認証コードが表示されるので、ユーザーがコピーします。
6. code を指定して auth アクション pkce-complete を呼び出し、アクセストークンと交換します。
7. セッションは自動的に確立され、その後のすべてのツール呼び出しが認証済みになります。スコープ付きアクセスが許可された場合、レスポンスに scopes と agent_name が含まれ、セッションに保存されます。

セッション状態の確認

• auth アクション status — ローカルの Durable Object セッションを確認します。API 呼び出しは行われません。認証状態、ユーザー ID、メールアドレス、auth_method、トークンの有効期限、scopes、agent_name を返します。セッションの有効期限が切れている場合は、expired_reason（"token_expired" または "refresh_expired"）と expired_at のタイムスタンプを含む session_expired: true を返します。
• auth アクション check — Fast.io API に対してトークンを検証します。トークンがまだ有効な場合は、ユーザー ID を返します。

セッションの有効期限と自動更新

OAuth/PKCE セッション（デフォルト）では、アクセストークンの有効期間は 1 時間、リフレッシュトークンの有効期間は 30 日です。MCP サーバーは、有効期限が切れる前に OAuth アクセストークンを事前に更新します。期限切れの約 5 分前に内部アラームが作動し、保存済みのリフレッシュトークンを使って新しいトークンを通知なく取得します。これにより自己持続的なサイクルが生まれ、30 日間のリフレッシュトークンの連鎖が期限切れになるか、失効されるまで、ユーザーが操作しなくてもセッションは無期限に維持されます。事前の更新に失敗した場合は、次回のツール呼び出し時に再試行する事後対応のセーフティネットが働きます（401 → 更新 → 再試行）。

基本の JWT セッション（auth アクション signin によるもの）の有効期間は 30 日で、リフレッシュトークンはありません。トークンの有効期限が切れるとセッションはクリーンアップされ、再認証が必要になります。

API キーはデフォルトでは有効期限がありませんが、api-key-create または api-key-update で key_expires パラメーターを指定して、任意で有効期限を設定できます。API キーの有効期限はバックエンド側で適用されます。

MCP サーバーは、各セッションの認証方法（auth_method："api_key"、"jwt"、または "oauth"）を記録し、API キーのセッションではクライアント側の有効期限チェックをスキップします。

エラーの区別： セッションの有効期限が切れると、ツール呼び出しは "Session expired. Please re-authenticate..." を返します。これは、過去にセッションが存在しないことを示す "Not authenticated..." とは異なります。この違いにより、再接続の問題と初回セットアップを区別できます。

サインアウト

auth アクション signout を呼び出すと、Durable Object に保存されたセッションが消去されます。

---

3. コアコンセプト

組織

組織は、ワークスペースをまとめる最上位のコンテナーです。組織は、企業、事業部門、チーム、または単に個人用のコレクションを表すことができます。すべてのユーザーは 1 つ以上の組織に所属します。組織には次のものがあります。

• ワークスペース — 組織に属するファイルストレージ用コンテナーです。
• メンバー（役割：オーナー、管理者、メンバー、ゲスト、閲覧者）。
• Stripe 連携を通じて管理される請求とサブスクリプション。
• ストレージ、転送量、AI トークン数、メンバー数を制限するプランの上限。

組織は、19 桁の数値プロフィール ID またはドメイン文字列で識別されます。

重要： 組織を作成する際、エージェントは必ず org アクション create を使用しなければなりません。このアクションは billing_plan: "agent" を自動的に割り当てます。これにより、組織には無料のエージェントプラン（50 GB、月 5,000 クレジット）が適用されます。エージェントが作成する組織には、ほかの請求プランを使用しないでください。

カスタムドメイン

Pro または Business プランの組織では、組織のコンテンツを配信するカスタムドメイン（例：files.acme.com）を設定できます。組織ごとに設定できるカスタムドメインは 1 つです。

設定手順：

1. org アクション custom-domain-create を org_id と hostname（有効な FQDN。例：files.acme.com）とともに呼び出します。hostname、status: "pending"、cname_target が返されます。
2. 顧客が DNS CNAME レコードを追加します：files.acme.com CNAME custom.fast.io（本番環境）または custom.fastdev1.com（開発環境）。
3. CNAME 経由で最初のリクエストがあると、Let's Encrypt によって TLS 証明書が自動的にプロビジョニングされます（2～5 秒）。ドメインのステータスは pending から active に変わります。

ステータスの確認： org アクション custom-domain-get を org_id とともに呼び出します。ドメイン情報が返されます。カスタムドメインが設定されていない場合は { hostname: null } が返されます。

DNS の検証： org アクション custom-domain-validate を org_id とともに呼び出します。DNS のライブ検索を実行し、CNAME が正しいかどうかを返します。有効で、ステータスが pending の場合、ドメインは自動的に有効化されます。

削除： org アクション custom-domain-delete を org_id とともに呼び出します。既存の TLS 証明書は自然に期限切れになります（最長 90 日）。トラフィックへの即時の影響はありません。プランによる制限はなく、ダウングレードした組織でもドメインを削除できます。

必要なプラン： カスタムドメインを作成するには、Pro または Business プランが必要です。エージェントプランにはこの機能が含まれていません。組織がカスタムドメインに対応していないプランを利用している場合、作成時にサブスクリプションのアップグレードを求めるエラーが返されます。

組織の検出（重要）

利用可能なすべての組織を検出するには、エージェントは両方のアクションを呼び出す必要があります。

1. org アクション list -- 直接メンバーとなっている内部組織を返します（member: true）
2. org アクション discover-external -- ワークスペースのメンバーシップのみを通じてアクセスできる外部組織を返します（member: false）

org アクション list だけを確認するエージェントは、外部組織をまったく見つけられず、招待されたワークスペースも検出できません。 人間がエージェントを特定のプロジェクトに招待する場合、組織そのものではなくワークスペースにエージェントを追加するのが最も一般的なパターンです。

内部組織と外部組織

内部組織（member: true）-- 自分で作成した組織、またはメンバーとして参加するよう招待された組織です。組織レベルのアクセス権があり、すべてのワークスペースを確認でき（権限に従います）、管理者であれば設定を管理でき、組織のメンバーリストに表示されます。

外部組織（member: false）-- ワークスペースのメンバーシップを通じてのみアクセスできる組織です。組織名と基本的な公開情報は確認できますが、組織の設定を管理したり、ほかのワークスペースを確認したり、組織レベルでメンバーを追加したりすることはできません。アクセスできるのは、明示的に招待された特定のワークスペースに限られます。

例： 人間があなたのエージェントを、自分の「Q4 Reports」ワークスペースに招待します。そのワークスペースでは、ファイルのアップロード、AI クエリの実行、共同作業ができます。しかし、その人の組織に新しいワークスペースを作成したり、請求情報を確認したり、ほかのワークスペースにアクセスしたりすることはできません。この組織は org アクション list ではなく、org アクション discover-external を通じて表示されます。その後、人間が組織自体にも招待すると、その組織は外部から内部に移行します。

ワークスペース

ワークスペースは、組織内のファイルストレージコンテナーです。各ワークスペースには次のものがあります。

• ロール（オーナー、管理者、メンバー、ゲスト）が設定された独自のメンバー。メンバーのstatusはactiveまたはpendingです。保留中のメンバーは、まだサインアップしていない招待ユーザーです。メンバーリストにはすぐに表示され、タスク、承認、ToDoを割り当てられます。保留中のメンバーへの通知は、サインアップするまで抑制されます。サインアップすると、ステータスがactiveになり、すべての割り当てが引き継がれます。
• ファイルとフォルダーからなるストレージツリー（ストレージノード）。
• RAG を活用したチャット用のオプションのAI 機能。
• ワークスペース内で作成できる共有。
• アーカイブ／アーカイブ解除によるライフサイクル管理。
• 無料のエージェントプランに含まれる50 GB のストレージ。ファイルはアップロードごとに最大 1 GB です。
• ファイルのバージョン管理 -- 編集するたびに新しいバージョンが作成され、以前のバージョンを復元できます。
• キーワード検索とセマンティック検索 -- 名前や内容からファイルを検索できます。インテリジェンスを有効にすると、意味に基づく検索もできます。

ワークスペースは、19 桁の数値プロファイル ID で識別されます。

インテリジェンス：オンまたはオフ

ワークスペースには、AI 機能を有効にするかどうかを切り替える インテリジェンス のトグルがあります。

⚠️ コストに関する警告： インテリジェンスを有効にすると、取り込みに多額のコストがかかります（アップロードしたドキュメントは1ページあたり10クレジット）。数百ページ、数千ページあるワークスペースでは、コストがすぐに膨らみます。ユーザーが RAG チャットクエリまたはストレージ検索によるセマンティック検索を明確に必要としている場合を除き、インテリジェンスを有効にしないでください。 ほとんどのワークフロー（ファイルの保存、共有、共同作業、個別ファイルの分析）は、インテリジェンスなしで問題なく機能します。

インテリジェンスがオフ（推奨されるデフォルト） -- ワークスペースはファイルストレージ専用になります。AI チャットの会話にファイルを直接添付し（最大20ファイル、合計200 MB）、ファイルについて質問することは引き続き可能で、取り込みコストはかかりません。ファイルの保存、共有、共同作業、プロジェクトの調整、少数の特定ファイルの分析など、ほとんどのユースケースに適しています。

インテリジェンスがオン（必要な場合のみ） -- ワークスペースは AI を活用したナレッジベースになります。アップロードされたドキュメントとコードファイルはすべて、自動的に取り込まれ、要約され、インデックス化されます。次の2つの機能のいずれかをユーザーが必要とする場合にのみ有効にしてください。

1. 多数のドキュメントにまたがる RAG クエリ -- AI チャットの対象をフォルダー全体またはワークスペース全体に設定し、インデックス化されたすべてのコンテンツについて質問できます。AI は関連する箇所を取得し、出典を引用して回答します。大量のドキュメントがあり、そのすべてを横断して検索する必要がある場合に便利です。
2. ストレージ検索によるセマンティック検索 -- キーワードだけでなく、意味に基づいてファイルを検索できます。storage アクションの search を使って、ドキュメントを意味的に検索します。「補償条項を含む契約書を表示して」のような検索は、ファイル名にその正確な語句が含まれていなくても機能します。

インテリジェンスを有効にすると、自動要約やメタデータの自動抽出も利用できますが、これらだけでは取り込みコストを正当化できません。

近日公開： 画像、動画、音声ファイルの RAG インデックス化に対応予定です。現在、インデックス化されるのはドキュメントとコードのみです。

デフォルトの動作： MCP サーバーは、ワークスペースや共有を作成する際、インテリジェンスをデフォルトでオフにします。有効にするには、intelligence: "true" を明示的に指定する必要があります。ユーザーが RAG チャットクエリまたはストレージ検索によるセマンティック検索を明確に要求している場合を除き、インテリジェンスを有効にしないでください。「念のため」に有効にしないでください。後からいつでも有効にできますが、取り込みコスト（1ページあたり10クレジット）はすぐに発生し、返金されません。

エージェントのユースケース： プロジェクトまたはクライアントごとにワークスペースを作成します。保存と共同作業ではインテリジェンスをオフにしておきます。大量のドキュメントを横断して検索する必要がある場合にのみ有効にします。レポート、データセット、納品物をアップロードします。他のエージェントや関係者を招待します。すべてが整理され、検索可能で、バージョン管理されます。

AI チャットの種類、ファイルコンテキストモード、AI の状態、およびインテリジェンスがそれらに与える影響について詳しくは、下記の AI チャット セクションを参照してください。

共有

共有は、ワークスペース外の人とファイルをやり取りするために特化したスペースです。ワークスペース内に作成でき、次の3種類があります。

モード	機能	エージェントのユースケース
送信	受信者がファイルをダウンロードできます	レポート、エクスポート、生成したコンテンツを届ける
受信	受信者がファイルをアップロードできます	ドキュメント、データセット、ユーザーからの提出物を収集する
交換	アップロードとダウンロードの両方ができます	共同作業のワークフロー、レビューサイクル

ポータル

ポータルとは、ワークスペースフォルダーから作成されたSend共有（storage_mode=workspace_folder）です。ポータルは常にSend専用です。受信者はファイルを表示およびダウンロードできますが、アップロードはできません。ポータルにはリンク先のワークスペースフォルダーの最新の内容が表示されるため、フォルダーへの変更はすぐに反映されます。ポータルは、ファイルを複製せずにフォルダーの内容を外部に公開する場合（例：クライアントへの納品物フォルダー）に最適です。ポータルを作成するには、shareアクションのcreateを使用し、share_type: "send"、storage_mode: "workspace_folder"、およびfolder_node_id（またはcreate_folder: true）を指定します。

共有の機能

• パスワード保護 -- リンクへのアクセスにパスワードを必須にします
• 有効期限 -- 共有は設定した期間が経過すると自動的に期限切れになります
• ダウンロード制御 -- 3つのセキュリティレベルがあります。off（制限なし、デフォルト）、medium（ゲストはファイルをインラインでプレビューできますが、ダウンロードはできません）、high（ゲストによるダウンロードをすべてブロック）。作成／更新時にdownload_securityで設定します。
• アクセスレベル -- メンバーのみ、組織メンバー、登録ユーザー、または公開（リンクを知っているすべてのユーザー）
• カスタムブランディング -- 背景画像、グラデーションカラー、アクセントカラー、ロゴ
• ダウンロード後のメッセージ -- ダウンロード後にカスタムメッセージやリンクを表示します
• 共有ごとに最大3つのカスタムリンクを設定でき、補足情報や行動喚起に利用できます
• 匿名ファイルドロップ -- 登録なしでゲストがReceive／Exchange共有にファイルをアップロードできるようにします（「Anyone」アクセスでanonymous_uploads_enabledを有効にします）
• ゲストチャット -- 共有の受信者がリアルタイムで質問できるようにします
• AI による自動タイトル設定 -- 共有の内容に基づいて、適切なタイトルを自動生成します
• アクティビティ通知 -- ファイルの送信または受信時に通知を受け取ります
• コメント制御 -- コメントの閲覧や投稿ができるユーザー（所有者、ゲスト、または両方）を設定します

2つのストレージモード

shareアクションのcreateで共有を作成する際、storage_modeパラメーターでファイルの保存方法を指定します。

• independent（独立ストレージ、デフォルト）-- 共有は独自の分離されたストレージを持ちます。ファイルは共有に直接追加され、ワークスペースとは独立しています。これは自己完結型の共有を作成します。ワークスペース内のファイルを変更しても共有には影響せず、その逆も同様です。最終納品物、コンプライアンス用パッケージ、アーカイブ済みレポート、または変更されないスナップショットが必要なあらゆるケースで使用します。

• workspace_folder（ワークスペース連携）-- 共有はワークスペース内の特定のフォルダーに紐付けられます。共有にはそのフォルダーの最新の内容が表示されるため、ワークスペースフォルダー内でファイルを追加、更新、削除すると、共有にもすぐに反映されます。ファイルを複製しないため、追加のストレージコストもかかりません。ワークスペースフォルダーの共有を作成するには、共有の作成時にstorage_mode=workspace_folderとfolder_node_id={folder_opaque_id}を渡します。注： ワークスペースフォルダーの共有は内容が常に更新されるため、有効期限を設定できません。注： ワークスペースフォルダーの共有はインテリジェンスに対応していません。渡された値にかかわらず、intelligenceは常にfalseに設定されます。これらのファイルでAI機能を使用するには、代わりに親ワークスペースのAIエンドポイントを使用してください。

どちらのモードも、共有の受信者には同じように表示されます。ファイルのプレビュー、ダウンロード制御、すべての共有機能を備えた、ブランディング済みの共有ページです。違いは、内容がスナップショット（独立）か、最新の状態を表示するビュー（ワークスペースフォルダー）かという点です。

レスポンスフィールド： APIレスポンスには、storage_mode（independentまたはworkspace_folder）とshare_category（portalまたはshared_folder）の両方が含まれます。共有を作成する際はstorage_modeを使用してください。share_categoryはレスポンスでのみ使用される読み取り専用の分類です。

共有は19桁の数値プロファイルIDで識別されます。

エージェントのユースケース： 四半期レポートを作成し、クライアントのブランディングを適用したSend共有を作成して、30日後の有効期限を設定し、リンクを共有します。クライアントには、直接ダウンロードするためのリンクではなく、ファイルをすぐにプレビューできる、プロフェッショナルなブランディング済みページが表示されます。

ストレージノード

ファイルとフォルダーはストレージノードとして表されます。各ノードには不透明な ID（30 文字の英数字の文字列で、ハイフン付きで表示されます。例：f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4）があります。特別な値 root はワークスペースまたは共有のルートフォルダーを、trash はゴミ箱フォルダーを指します。

ストレージノードの主な操作：一覧表示、フォルダー作成、移動、コピー、名前変更、削除（ゴミ箱に移動）、完全削除、復元（ゴミ箱から復元）、検索、ファイル追加（アップロードのリンク）、リンク追加（共有参照の作成）。

ノードにはバージョンがあります。ファイルを変更するたびに新しいバージョンが作成されます。バージョン履歴を一覧表示でき、ファイルを以前のバージョンに復元できます。

ファイルの上書き（デフォルトで置換、同じノードでバージョン管理）

ファイルを「更新」するために、削除して再アップロードしてはいけません。 同じ親フォルダーに同じ名前でアップロードすると、既存のノードがその場で上書きされ、node_id は維持されます。以前の内容はバージョンとして保持され、いつでも復元できます。古いノードを先に削除するのは無駄な作業であり、他のエンティティ（コメント、タスク、承認、メタデータ、リンク）が保持している node_id 参照を壊し、ファイルがゴミ箱に残る可能性もあります。ファイルの内容を編集する際に、この方法を使うべきではありません。

ファイルを更新する正しい手順：

1. 既存のファイルと同じ parent_node_id および同じ filename（さらに profile_type、profile_id、filesize）を指定して、upload アクションの create-session を実行します。サーバーは競合を解決し、既存のノードを対象にします。
2. 新しいバイトデータを POST /blob で送信します（以下のアップロードのセクションを参照）。
3. blob_id を指定して upload アクションの chunk を実行し、続けて upload アクションの finalize を実行します（または、単一のストリーミングアップロードには stream モードを使用します）。
4. node_id は変わりません。以前の内容はバージョンエントリーになります。
5. storage アクションの version-list で履歴を確認します（ノードの全バージョンが返されます）。storage アクションの version-restore で以前の任意のバージョンに戻せます。

node_id による確実な上書き：ファイル名が変更されている可能性がある場合（例：以前に名前を変更した場合）、または親フォルダーを再解決せずに特定の node_id を確実に上書きしたい場合は、create-session に target_node_id を指定します。これにより更新対象が明示的に固定され、サーバーは action=update + file_id=<target_node_id> を使用します。parent_node_id は無視され、filename は省略可能です（省略すると現在の名前が維持され、新しい名前を指定すると置換時に名前が変更されます）。filename を省略した場合、ツールは現在の名前を取得するために追加で storage の details lookup を 1 回実行します（Fast.io API は更新モードでも引き続き name を必須とします）。この呼び出しを省略したい場合は、filename を明示的に指定してください。詳しくは、以下のアップロードのセクションにある target_node_id のドキュメントを参照してください。

実例 — ファイルの内容を編集し、以前のバージョンを復元する：

# Initial upload
upload create-session
  profile_type=workspace, profile_id=<ws_id>, parent_node_id=<folder_id>,
  filename="state.json", filesize=1024
POST /blob <bytes>
upload chunk upload_id=<id> chunk_number=1 blob_id=<blob>
upload finalize upload_id=<id>
# → new_file_id = f3jm5-zqzfx-...   (this is the stable node_id)

# Later, "edit" the file by re-uploading with the same name+parent
upload create-session
  profile_type=workspace, profile_id=<ws_id>, parent_node_id=<folder_id>,
  filename="state.json", filesize=2048
POST /blob <new_bytes>
upload chunk upload_id=<id2> chunk_number=1 blob_id=<blob2>
upload finalize upload_id=<id2>
# → new_file_id = f3jm5-zqzfx-...   (SAME node_id — overwritten in place)

# Inspect version history
storage version-list profile_type=workspace profile_id=<ws_id> node_id=f3jm5-zqzfx-...
# → [{version_id: v2, current: true}, {version_id: v1, ...}]

# Roll back if needed
storage version-restore profile_type=workspace profile_id=<ws_id>
  node_id=f3jm5-zqzfx-... version_id=v1

上書きの動作（名前が競合する場合、すべてデフォルトで置換）：

• アップロード（addfile） — 既存のファイルを通知なしで上書きします。以前の内容はバージョンエントリーとして保持され、storage アクションの version-list / version-restore で復元できます。ノード ID は維持されます。
• 移動 / コピー — 既存の競合ファイルをゴミ箱に移動してから、操作を完了します。古いファイルはゴミ箱から復元できます。
• ゴミ箱からの復元 — 既存の競合ファイルをゴミ箱に移動してから、復元します。
• フォルダーの競合と種類の不一致（ファイルとフォルダー）は、引き続き名前変更にフォールバックします（例：folder (2)）。

既存のファイルと同じ名前でファイルをアップロードすると、report (2).pdf のような名前に変更したコピーが作成されるのではなく、既存のファイルが上書きされます。同じ名前の複数のファイルを共存させる必要がある場合は、アップロードする前に名前を変更してください。

ノート

ノートは、サーバー上に Markdown コンテンツを直接保存するストレージノードの種類です（ファイルやフォルダーと並ぶ種類です）。ファイルと同じフォルダー階層にあり、他のノードと同様にバージョン管理され、ストレージの一覧では type: "note" として表示されます。

ノートの作成と更新

workspace アクション create-note でノートを作成し、workspace アクション read-note で読み取り、workspace アクション update-note で更新します。

ファイルとノートは、どちらも Markdown を格納できる場合でも、相互に置き換えられるものではありません。 ファイルアップロードのフローでアップロードした .md はファイル（type: "file"）であり、ノート（type: "note"）ではありません。Markdown ファイルを読み取るとテキストが返され、ノートのように「見えます」が、ノート専用 API（update-note、read-note）では Node is not a note（エラー 153548）で拒否されます。最初に適切な作成方法を選んでください。

• エージェントからコンテンツを段階的に編集する場合 → create-note を使用します。Markdown を content として直接渡してください。最初にファイルとしてアップロードしてはいけません。
• 静的な成果物（レポート、エクスポート、添付ファイル）の場合 → アップロードのフローを使用します。その後 update-note が機能しないことを受け入れてください。コンテンツを変更するには、upload アクション create-session を呼び出し、既存のファイルと同じ parent_node_id と同じ filename を指定して新しいバージョンをアップロードし、続けて chunk／finalize（または stream）を実行します。同名のアップロードはファイルをその場で上書きし、以前のコンテンツをバージョンとして保持します（storage アクション version-list／version-restore で復元できます）。

update-note が Node is not a note で失敗する場合、ほとんどの場合、そのノードはファイルです。復旧方法は 2 つあります。今後そのノードをどうするかに応じて選択してください。

• （a）ファイルのままにしてバイト列だけ変更する → 上記のアップロードのフローを使用します（同じ parent_node_id と filename を指定すると、その場で上書きされ、バージョンが記録されます）。ノード ID は変わらず、ノードはファイルのままです。
• （b）ノートに変換する（今後 update-note で段階的に編集する場合） → storage アクション delete でファイルを削除し、目的の parent_id に Markdown コンテンツを指定して create-note を呼び出します。これにより、type: "note" の新しいノードが作成されます。以後の編集には、新しい node_id を指定して update-note を使用します。

修正方法として、削除してから再アップロード（アップロードのフローを使用）してはいけません。これは別のファイルを作成するだけであり、次の update-note 呼び出しでも同じ Node is not a note エラーが発生します。呼び出し前にノードの種類を確認するには、storage アクション details を使用し、type フィールド（"file"、"note"、"folder"、"link"）を確認してください。

作成： workspace_id、parent_id（フォルダーの不透明な ID、または "root"）、name（末尾が .md であること。最大 100 文字）、および content（Markdown を直接指定。最大 100 KB）か blob_id（下記参照）のいずれか一方を指定します。

読み取り： workspace_id と node_id を指定します。ノートの Markdown コンテンツとメタデータが返されます。

更新： workspace_id、node_id、および name（末尾が .md であること）、content（最大 100 KB）、blob_id のいずれか 1 つ以上を指定します。content と blob_id の両方を渡すと、呼び出しはエラーになります。必ずどちらか一方だけを指定してください。

blob_id によるノートコンテンツの受け渡し（大きなノートに推奨）

create-note と update-note は、インラインの content の代替として、オプションの blob_id を受け付けます。

blob_id：オプションの文字列。POST /blob のレスポンスに含まれる Blob ID です。大きなノートコンテンツに推奨されます。base64 のオーバーヘッドと MCP の転送制限を回避できます。使用後に消費されます。バイト列は UTF-8 としてデコードされ、ノートコンテンツとして渡されます。（使用箇所：create-note、update-note の content／blob_id のいずれか）

この仕組みがある理由。 MCP は、ツールのパラメーターを JSON-RPC パイプ経由でインラインの JSON 文字列として転送します。ノートコンテンツを数 KB を超えて content パラメーター経由で送信すると、測定可能なほど遅くなります。文字列全体をツール呼び出し用にシリアライズし、転送経由で送信してから、サーバー上で再度解析する必要があるためです。POST /blob サイドカーは、MCP の転送を完全に迂回する独立した raw-HTTP 経路です。生のバイト列（最大 100 MB、1 回のみ使用可能、有効期間は 5 分）を POST すると、blob_id が返されるので、その blob_id をツールに渡します。サーバーは Blob を消費し、UTF-8 としてデコードしてサニタイズした後、ノートコンテンツとして使用します。upload アクションの chunk／stream と同じパターンです。

使い分け：

ノートのサイズ	推奨される方法
小さな編集（< 約 10 KB — 数段落、箇条書き、小さなセクション）	インラインの content
大きなノート（> 約 10 KB — 豊富なプロジェクトコンテキスト、トランスクリプト、長い Markdown ドキュメント）	POST /blob → blob_id

ノートはノードごとに最大 100 KB です。80 KB 以上の書き込みでは、上限に達する前にロールオーバーすることを推奨する、致命的ではない警告が _warnings（または create-note の withHints）に返されます。この警告は助言であり、書き込みは引き続き成功します。一般的なロールオーバー方法は、日付付きのアーカイブファイルを使うことです。ノートが約 80 KB を超えたら、archive-2026-04-14.md や notes-2026-W15.md のような名前の新しいノートを作成し、古い内容をそこに移して、「現行」のノートを小さく保ちます。

制約	上限
コンテンツのエンコーディング	有効な UTF-8（UTF8MB4）。無効なバイト列と制御文字（\t、\n、\r を除く \p{C}）は削除されます。
コンテンツのサイズ	最大 100 KB
ファイル名	1～100 文字で、.md で終わる必要があります
Markdown の検証	コードブロックと強調マーカーの対応が取れている必要があります
レート制限	10 秒あたり 2 回、60 秒あたり 5 回

長期的なナレッジの根拠としてのノート

インテリジェントなワークスペースでは、アップロードされたドキュメントと同様に、ノートも自動的に取り込まれてインデックス化されます。これにより、ノートは時間をかけて知識を蓄積する手段になります。ノートに保存された事実、コンテキスト、決定事項は、今後の AI クエリの根拠資料になります。

AI チャットでフォルダーの範囲が指定されている場合（またはワークスペース全体がデフォルトで指定されている場合）、その範囲内のノートもファイルとあわせて検索されます。AI はノートから関連する記述を取得し、回答内で引用します。

主な動作：

• ワークスペースのインテリジェンスが有効な場合、RAG 用にノートが取り込まれます
• フォルダーの範囲内にあるノートは、範囲指定されたクエリに含まれます
• ai_state: indexed のノートは RAG で検索できます
• files_attach を使って、ノートをチャットに直接添付することもできます（ストレージの詳細で ai.attach が true であることを確認してください）

ユースケース：

• プロジェクトのコンテキスト、決定事項、理由を保存します。数か月後に「なぜベンダー X を選んだのか」と尋ねると、AI がノートを取得します。
• 調査結果をノートに保存します。今後の AI チャットでは、その調査結果が根拠として自動的に使用されます。
• ワークスペース内の今後すべての AI クエリに役立つ参考ドキュメント（スタイルガイド、命名規則など）を作成します。

その他のノート操作

ノートでは、ファイルやフォルダーと同じストレージ操作をサポートしています。移動（storage アクション move）、コピー（storage アクション copy）、削除／ゴミ箱への移動（storage アクション delete）、復元（storage アクション restore）、バージョン履歴（storage アクション version-list）、詳細の取得（storage アクション details）が可能です。

ユーザーをノートにリンクする

• ワークスペースのコンテキスト内のノート（ノートパネルを開いた状態でワークスペースを開きます）：https://{domain}.fast.io/workspace/{folder_name}/storage/root?note={note_id}
• ノートのプレビュー（単独表示）：https://{domain}.fast.io/workspace/{folder_name}/preview/{note_id}

AI チャット

AI チャットでは、エージェントがワークスペースや共有に保存されているファイルについて質問できます。チャットには、ファイルのコンテキスト設定が異なる2つのタイプがあります。

AI チャットは読み取り専用です。 ファイルの内容を読み取り、分析、検索し、質問に回答できますが、ファイルの変更、ワークスペース設定の変更、メンバーの管理、イベントへのアクセスはできません。ファイル内容の読み取り以外の操作（アップロード、削除、ファイルの移動、設定の変更、共有の管理、イベントの読み取り）は、MCP ツールを直接使用して行う必要があります。ワークスペース管理用の汎用ツールとしてAI チャットを使用しないでください。

2種類のチャット

• chat — ワークスペースのインデックスからファイルのコンテキストを取得しない、基本的なAI 会話です。一般的な質問にのみ使用してください。
• chat_with_files — ファイルに基づいて回答するAI です。ファイルのコンテキストを指定する方法は、相互に排他的な2つのモードがあります。

自動昇格： type=chat を指定してチャットを作成した場合でも、files_scope、folders_scope、または files_attach を含めると、システムがタイプを自動的に chat_with_files に昇格させます。ファイル関連のパラメーターが指定されていれば意図は明確なため、タイプを厳密に設定する必要はありません。

• フォルダー／ファイルのスコープ（RAG） — 検索対象を制限します。インテリジェンスが有効になっている必要があり、ファイルのAI 状態が indexed である必要があります。
• ファイルの添付 — AI がファイルを直接読み取ります。インテリジェンスは不要です。ストレージの詳細でファイルの ai.attach: true が設定されている必要があります（ファイルはAI 分析に対応した形式である必要があります）。最大20ファイル、合計200 MBです。

どちらのタイプも、関連する場合はウェブ上の知識を回答に加えます。

ファイルのコンテキスト：スコープと添付ファイル

chat_with_files では、相互に排他的な次のいずれかの方法を選択してください。

機能	フォルダー／ファイルのスコープ（RAG）	ファイルの添付
動作	RAG の検索範囲を制限します	AI がファイルを直接読み取ります
インテリジェンスが必要	はい	いいえ
ファイルの準備要件	ai_state: indexed	ai.attach: true
最適な用途	多数のファイル、ナレッジの検索	特定のファイル、直接分析
参照の上限	フォルダー参照 100 件（サブフォルダーツリーの展開）またはファイル参照 100 件	20 ファイル／200 MB
デフォルト（スコープ未指定の場合）	ワークスペース全体	該当なし

スコープパラメーター（インテリジェンスが必要です。インテリジェンスがオフの場合はエラーになります）：

• folders_scope — カンマ区切りの nodeId:depth ペア（depth は 1～10、サブフォルダー参照は最大 100 件）。検索範囲を定義します。RAG バックエンドが、指定したフォルダー内のドキュメントを自動的に検索します。フォルダー ID と depth を渡すだけでよく、個々のファイルを列挙する必要はありません。ファイルが数千件あり、サブフォルダーが少ないフォルダーでも問題なく動作します。
• files_scope — カンマ区切りの nodeId:versionId ペア（最大 100 件）。RAG の対象を、インデックス登録済みの特定のファイルに制限します。nodeId は必須です。ペア形式では versionId も必須ですが、空のままにした場合（例：コロンの後に何もない nodeId:）、ノードの現在のバージョンに自動解決されます。versionId は、storage アクションの list または details レスポンスにあるファイルの version フィールドから取得してください。
• どちらも指定しない場合、デフォルトのスコープはワークスペース全体（インデックス登録済みのすべてのドキュメント）です。 これが推奨されるデフォルトです。検索範囲を絞り込む必要が特にない限り、スコープパラメーターは省略してください。

添付パラメーター（インテリジェンスは不要です）：

• files_attach — カンマ区切りの nodeId:versionId ペア（最大 20 件、合計 200 MB）。nodeId は必須です。versionId を空のままにした場合は、現在のバージョンに自動解決されます。ファイルは RAG 経由ではなく、直接読み取られます。ファイルのみ：フォルダーの nodeId を渡すと 406 エラーになります。 フォルダーの内容を AI のコンテキストに含めるには、代わりに folders_scope を使用してください（インテリジェンスが必要です）。ストレージの詳細で ai.attach: true となっているファイルのみ添付できます。使用前に確認してください。

フォルダーを検索したい場合は、フォルダーの内容を列挙して個々のファイル ID を files_scope に渡さないでください。代わりに、そのフォルダーの nodeId を指定して folders_scope を使用してください。files_scope は、特定の既知のファイルバージョンを対象とする場合にのみ使用します。

スコープと添付の違い： files_scope と folders_scope は RAG の検索範囲を絞り込み、ワークスペースでインテリジェンスが有効になっている必要があります。インテリジェンスが有効でないワークスペースではエラーになります。files_attach はインデックス登録を行わずにファイルを直接 AI に送信するため、インテリジェンスの設定にかかわらず動作しますが、指定できるのはファイルの nodeId のみで、フォルダーは指定できません。

files_scope／folders_scope と files_attach は相互に排他的です。両方を送信するとエラーになります。

インテリジェンスと AI の状態

ワークスペースのインテリジェンス切り替え（上記の「ワークスペース」を参照）では、アップロードされたドキュメントやコードファイルを自動的に取り込み、要約し、RAG 用にインデックス化するかどうかを制御します。各ファイルには、準備状況を示す ai_state があります。

状態	意味
disabled	AI 処理は行われていません（ファイル形式がサポートされていないか、AI が完全にオフになっています）
pending	AI 処理のキューに登録されています
in_progress	現在処理中です
ready	要約があり、AI チャットに添付できますが、ベクトルインデックスには登録されていません（インテリジェンスがオフ）
indexed	要約があり、ベクトルインデックスにも登録されています。RAG／セマンティック検索でファイルを検索できます（インテリジェンスがオン）
failed	処理に失敗しました

フォルダー／ファイルの範囲を指定した（RAG）検索に含まれるのは、ai_state: indexed のファイルだけです。ai_state: ready または indexed のファイルは、どちらも AI チャットに添付できます。ai.attach フィールドを確認してください。ファイルの状態は、storage アクションの details に profile_type: "workspace" を指定して確認します。

AI 処理の完了をポーリングする場合、インテリジェンスがオンなら indexed を、インテリジェンスがオフ（ただし AI 要約は有効）なら ready を待ちます。ワークスペースの capabilities.can_use_intelligence を確認すると、期待される最終状態がわかります。

添付可能性 — ai.attach フラグ

ストレージの一覧／詳細レスポンスに含まれるファイルノードには、次の 3 つのフィールドを持つ ai オブジェクトがあります。

フィールド	型	意味
ai.state	string	AI 処理の状態（disabled、pending、inprogress、ready、indexed、failed）
ai.attach	boolean	files_attach でファイルを使用できるかどうか
ai.summary	boolean	ファイルに AI 生成の要約がすでにあるかどうか

files_attach を使用する前に、ai.attach が true であることを確認してください。 ファイル形式が AI 分析に対応している（ドキュメント、コード、画像、PDF、スプレッドシートなど）場合、または以前の処理で要約がすでに作成されている場合、そのファイルは添付可能です。ai.attach: false のファイル（未対応の形式、破損したファイル、処理中のファイル）は API によって拒否されます。

このフラグはワークスペースのインテリジェンス設定とは独立しています。インテリジェンスがオフでも、ai.attach: true のファイルがあります。

インテリジェンスを有効にする場合： 多数のドキュメントを対象にした RAG チャットのクエリ（フォルダーまたはワークスペース全体を対象）や、storage アクションの search によるセマンティック検索が必要な場合です。自動要約やメタデータ抽出だけを目的に有効にしないでください。取り込みコスト（1 ページあたり 10 クレジット）は高額です。

インテリジェンスを無効にする場合（推奨されるデフォルト）： ワークスペースをストレージ、共有、コラボレーションに使用する場合、または添付ファイルを使って特定のファイルだけを分析する場合です。ほとんどのユースケースがこれに該当します。クレジットを大幅に節約できます。必要になれば、いつでもインテリジェンスを有効にできます。

インテリジェンスがオフでも、ai.attach: true のファイルであれば、ファイルを添付した chat_with_files は引き続き使用できます。

質問の表現方法

フォルダー／ファイルの範囲指定（RAG）の場合： インデックス化されたファイル内の内容と一致しそうな質問を作成します。AI は指定範囲を検索し、該当箇所を取得して引用します。

• 良い例：「ベンダー契約の支払い条件は何ですか？」
• 良い例：「第 3 四半期の分析レポートから主な調査結果を要約してください」
• 悪い例：「これらのファイルについて教えてください」— 曖昧すぎて、一致させる具体的な内容がありません
• 悪い例：「このワークスペースには何がありますか？」— 「すべて」を意味のある形で検索できません

ファイルを添付する場合： 直接的に指示します。AI はファイルの内容全体を読み取ります。検索ステップはありません。

• 「この画像を詳しく説明してください」
• 「この請求書から日付と金額をすべて抽出してください」
• 「この CSV データを要約テーブルに変換してください」

応答のスタイル： personality パラメーターで、AI の応答のトーンと長さを制御します。チャットの作成時またはメッセージの送信時に指定します。

• concise — 短く簡潔な回答
• detailed — 背景と根拠を含む包括的な回答（デフォルト）

簡単な事実、はい／いいえの回答、または短い要約が必要な場合は、concise を使用します。裏付けとなる根拠や引用を含む詳細な分析が必要な場合は、detailed を使用するか、パラメーターを省略します。フォローアップメッセージごとにスタイルを上書きすることもできます。

質問で応答の詳しさを調整する方法： 質問の表現によっても、応答の詳しさを指定できます。

• 「このレポートの主な結論を 1 文で教えてください」
• 「GDPR への準拠に言及しているファイル名だけを列挙してください。説明は不要です」
• 「簡単に要約してください。箇条書きは最大 2～3 項目で」

personality: "concise" と直接的な質問を組み合わせると、回答が最も短くなり、AI クレジットの使用量も最小限になります。

チャットのパラメーター

ai アクション chat-create（profile_type: "workspace" を指定）または ai アクション chat-create（profile_type: "share" を指定）でチャットを作成します。

• type（必須）— chat または chat_with_files
• query_text（workspace では必須、share では任意）— 初期メッセージ。2～12,768 文字
• personality（任意）— concise または detailed（デフォルト：detailed）
• privacy（任意）— private または public（デフォルト：public）
• files_scope（任意）— nodeId:versionId,...（最大 100 件。chat_with_files と intelligence が必要）。nodeId は必須です。空の場合、versionId は自動解決されます。インデックス化されたすべてのドキュメントを検索する場合は省略してください（推奨デフォルト）。
• folders_scope（任意）— nodeId:depth,...（深さは 1～10、サブフォルダー参照は最大 100 件。chat_with_files と intelligence が必要）。フォルダー範囲は検索境界であり、ファイルの列挙ではありません。インデックス化されたすべてのドキュメントを検索する場合は省略してください（推奨デフォルト）。
• files_attach（任意）— nodeId:versionId,...（最大 20 件／200 MB。nodeId は必須です。空の場合、versionId は自動解決されます。scope パラメーターとは相互排他的です）

フォローアップメッセージ

ai アクション message-send（profile_type: "workspace" または "share" を指定）でフォローアップを送信します。チャットの種類は親チャットから引き継がれます。フォローアップごとに、範囲、添付ファイル、応答のスタイルの各パラメーターを更新できます。

AI の応答を待つ

チャットの作成後またはメッセージの送信後、AI の応答は非同期で返されます。メッセージの状態は ready → in_progress → complete（または errored）の順に進みます。

推奨： 返された message_id を指定し、ai アクション message-read（profile_type: "workspace" または "share" を指定）を呼び出します。ツールが自動的にポーリングします（最大 15 回、間隔は 2 秒、約 30 秒）。その時間内に応答の処理が完了しない場合は、読み取りアクションをループで呼び出すのではなく、workspace/share ID を指定して event アクション activity-poll を使用してください。セクション 7 の「アクティビティのポーリング」を参照してください。

応答の引用

完了した AI の応答には、ソースファイルを指す引用が含まれます。

• nodeId — ストレージノードの不透明 ID
• versionId — ファイルバージョンの不透明 ID
• entries[].page — ページ番号
• entries[].snippet — テキストの抜粋
• entries[].timestamp — 音声／動画のタイムスタンプ

ユーザーを AI チャットにリンクする

ワークスペースのストレージ URL に ?chat={chat_opaque_id} を追加します。

https://{domain}.fast.io/workspace/{folder_name}/storage/root?chat={chat_id}

AI チャットを共有する

共有でも、同等の機能を備えた AI チャットを利用できます。すべてのワークスペース AI エンドポイントには、profile_type: "share" を指定して ai アクションからアクセスできる共有版があります。

AI の共有／エクスポート

外部の AI ツール（ChatGPT、Claude など）に貼り付けられる、Markdown 形式の一時的なダウンロード URL を生成します。ai アクションの share-generate を使用します（profile_type: "workspace" または "share" を指定）。URL の有効期限は 5 分です。制限：ファイルは最大 25 個、1 ファイルあたり 50 MB、合計 100 MB です。

プロファイル ID

組織、ワークスペース、共有はすべて、19 桁の数値プロファイル ID で識別されます。これらは、ツールのパラメーター内で workspace_id、share_id、org_id、profile_id、member_id として使われます。

ほとんどのエンドポイントでは、識別子としてカスタム名も使用できます。

プロファイルの種類	数値 ID	カスタム名
ワークスペース	19 桁の ID	フォルダー名（例：my-project）
共有	19 桁の ID	URL 名（例：q4-financials）
組織	19 桁の ID	ドメイン名（例：acme）
ユーザー	19 桁の ID	メールアドレス（例：[email protected]）

QuickShares

QuickShares は、ワークスペース内の個別ファイルに対する一時的な公開ダウンロードリンクです（共有では利用できません）。認証なしでアクセスできます。作成から数秒後に期限切れになります（デフォルトは 10,800 秒＝3 時間、最大は 604,800 秒＝7 日）。または、expires_at を使用して ISO 8601 形式の日時を指定できます。ファイルサイズの上限は 1 GB です。各クイック共有には、メタデータの取得とファイルのダウンロードに使用する不透明な識別子があります。

ファイルのプレビュー

Fast.io にアップロードされたファイルは、自動的にプレビューが生成されます。人間が共有やワークスペースを開くと、コンテンツがすぐに表示されるため、「ダウンロードして別のアプリで開く」という手間がありません。

プレビューに対応する形式：

• 画像 — 自動回転とズームに対応したフル解像度表示
• 動画 — HLS アダプティブストリーミング（未加工動画より読み込みが 50～60％高速）
• 音声 — インタラクティブな波形表示
• PDF — ページ移動、ズーム、テキスト選択
• スプレッドシート — 複数シートに対応したグリッド表示
• コードとテキスト — 構文のハイライト表示、Markdown のレンダリング

プレビュー URL を生成するには、storage アクションの preview-url を使用します（profile_type: "workspace" または "share" を指定）。画像のリサイズ、切り抜き、形式変換には、storage アクションの preview-transform を使用します（profile_type: "workspace" または "share" を指定）。

エージェントのユースケース： 生成した PDF レポートは、単なるダウンロードリンクとして表示されるわけではありません。人間はブラウザーを離れることなく、インラインでレンダリングされたレポートを確認し、ページをめくったり、拡大したり、特定のセクションにコメントしたりできます。

コメントと注釈

人間とエージェントは、reference パラメーターを使って特定のコンテンツに紐付け、ファイルに直接フィードバックを残せます。

• 画像コメント — 空間領域（正規化された x/y/幅/高さの座標）に紐付け
• 動画コメント — 空間領域の選択を含め、タイムスタンプに紐付け
• 音声コメント — タイムスタンプまたは時間範囲に紐付け
• PDF コメント — 任意でテキストスニペットを選択し、特定のページに紐付け
• テキストに紐付けたコメント — exact、prefix、suffix、start_offset、end_offset フィールドを使用して、Markdown／ノート内の選択テキストに紐付け（type: "document" または type: "text" を使用）
• スレッド形式の返信 — スレッド化は 1 階層のみです。返信への返信は親コメントに自動的に統合されます
• 絵文字リアクション — ユーザーごと、コメントごとに 1 件のリアクションを設定できます。新しいリアクションを追加すると、以前のリアクションは置き換えられます
• メンションタグ — 括弧構文を使用して、ユーザーやファイルをインラインで参照します：@[profile:id]、@[user:opaqueId:Display Name]、@[file:fileId:filename.ext]。ID はメンバー一覧、ユーザー詳細、またはストレージ一覧から取得します。プロファイルタグでは表示名の部分は任意ですが、ユーザータグとファイルタグでは推奨されます コメントでは JSON リクエストボディ（Content-Type: application/json）を使用します。他のほとんどのエンドポイントではフォームエンコードデータを使用します。

コメントの一覧表示： ファイルごとのコメントには comment アクション list を、ワークスペースまたは共有内のすべてのコメントには comment アクション list-all を使用します。どちらも sort、limit（2～200）、offset、include_deleted、reference_type フィルター、include_total に対応しています。

コメントの追加： profile_type、profile_id、node_id、text を指定して comment アクション add を使用します。返信の場合は任意で parent_comment_id を含め、特定の位置に紐付ける場合は reference を含めます。本文内のメンションタグに対応しています。文字数制限は2つあります。タグを含む本文全体は最大8,192文字、表示テキスト（@[...] タグを除いた本文）は最大500文字です。作成時にコメントをタスクまたは承認に紐付けるには、任意で linked_entity_type と linked_entity_id を含めます。

コメントの削除： comment アクション delete は再帰的です。親コメントを削除すると、すべての返信も削除されます。comment アクション bulk-delete は再帰的ではありません。削除されたコメントへの返信は保持されます。

コメントの紐付け： コメントはワークフローエンティティ（タスクまたは承認）に紐付けられます。各コメントが同時に持てる紐付けは1つです（null を指定できます）。既存のコメントをタスクまたは承認に紐付けるには comment アクション link を、紐付けを解除するには comment アクション unlink を、指定したエンティティに紐付いたすべてのコメントを逆引きするには comment アクション linked を使用します。add アクションに linked_entity_type と linked_entity_id を渡せば、作成時に紐付けることもできます。コメントのレスポンスには linked_entity_type と linked_entity_id フィールドが含まれます（紐付けがない場合は null）。

コメントへのユーザーのリンク： プレビュー URL を開くと、コメントのサイドバーが自動的に開きます。ディープリンクのクエリパラメーターを使うと、特定のコメントや位置を指定できます。

パラメーター	形式	目的
?comment={id}	コメントの不透明 ID	特定のコメントまでスクロールし、2秒間ハイライト表示します
?t={seconds}	例：?t=45.5	音声／動画のコメントのタイムスタンプに移動します
?p={pageNum}	例：?p=3	PDF コメントのページに移動します

ワークスペース：https://{org.domain}.fast.io/workspace/{folder_name}/preview/{file_opaque_id}?comment={comment_id}

共有：https://go.fast.io/shared/{custom_name}/{title-slug}/preview/{file_opaque_id}?comment={comment_id}

パラメーターは組み合わせて使用できます。たとえば、?comment={id}&t=45.5 を使うと、動画の特定のタイムスタンプにあるコメントへディープリンクできます。共有では、コメントが有効になっている場合のみコメントのサイドバーが開きます。

エージェントのユースケース： デザインのモックアップを生成します。人間が画像内の特定の領域に「ヘッダーの色を変更してください」とコメントします。コメントを読み、reference.region の座標から対象の領域を正確に確認して、再生成します。

テキストに紐付けるコメント（markdown／notes）： markdown または notes ファイル内の特定のテキストにコメントを紐付けるには、type: "document"（またはエイリアスの "text"）とテキスト選択フィールドを指定して reference パラメーターを使用します。

• exact（文字列、最大500文字）— 選択したテキストをそのまま指定します
• prefix（文字列、最大100文字）— 選択範囲の前にある、区別のための約30～50文字のコンテキスト
• suffix（文字列、最大100文字）— 選択範囲の後にある、区別のための約30～50文字のコンテキスト
• start_offset（整数）— ドキュメントの先頭からの文字オフセット（曖昧な一致を解決するためのヒント）
• end_offset（整数）— 選択範囲の末尾の文字オフセット（曖昧な一致を解決するためのヒント）

最低限、exact を指定してください。同じテキストが複数回現れる場合、prefix／suffix フィールドを使うと選択範囲を特定しやすくなります。start_offset／end_offset フィールドは任意のヒントで、ドキュメントの編集後は維持されない場合があります。

例 — markdown ファイル内のテキストに紐付けるコメント：

{
  "action": "add",
  "profile_type": "workspace",
  "profile_id": "1234567890123456789",
  "node_id": "abc123-def456-ghi789",
  "text": "This section needs a citation",
  "reference": {
    "type": "document",
    "exact": "Studies show a 40% improvement",
    "prefix": "In the results section, ",
    "suffix": " compared to the baseline.",
    "start_offset": 1250,
    "end_offset": 1280
  }
}

URL インポート

エージェントは、ファイルをローカルにダウンロードすることなく、URL から直接インポートできます。Fast.io のサーバーがファイルを取得して処理し、ワークスペースまたは共有に追加します。

• すべての HTTP/HTTPS URL に対応しています
• OAuth で保護されたソースに対応しています：Google Drive、OneDrive、Dropbox
• ファイルは通常と同じ処理パイプラインを通ります（プレビューの生成、インテリジェンスが有効な場合の AI インデックス作成、ウイルススキャン）

upload アクションの web-import を使い、ソース URL、対象プロファイル、親ノード ID を指定します。進行状況を確認するには upload アクションの web-status を、実行中のインポートジョブを一覧表示するには upload アクションの web-list を使います。

エージェントのユースケース： ユーザーが「この Google ドキュメントをプロジェクトに追加して」と言います。upload アクションの web-import を URL とともに呼び出します。Fast.io がサーバー側でファイルをダウンロードし、プレビューを生成して AI 用にインデックスを作成すると、ワークスペースに表示されます。ローカル I/O は発生しません。

メタデータ

メタデータを使うと、ワークスペース内のファイルに構造化データを付与できます。このシステムではテンプレートベースの方式を採用しています（UI では「ビュー」と呼ばれます）。管理者がフィールド（名前、型、制約）を定義するテンプレートを作成し、そのテンプレートをワークスペースに割り当てます。ファイルには、テンプレートの各フィールドに対応するメタデータ値を設定できます。

主なポイント：

• すべてのプランで利用可能 — メタデータテンプレートは Pro/Business 限定ではなくなりました。Free と Agent のユーザーも最初のテンプレートを作成できます。

• プランごとの上限 — 各プランでは、ワークスペースごとに作成できるテンプレート数と、各テンプレートに登録できるファイル（ノード）数の両方に上限があります：

  プラン	ワークスペースごとのテンプレート数	テンプレートごとのノード数
  Agent	1	10
  Free	1	10
  Pro	2	10
  Business	10	1,000
  上限は、自動マッチング、手動追加、一覧表示のすべてに適用されます。ダウングレード時、上限を超えた行はストレージに保持されますが、一覧には表示されません。

• metadata-template-preview-match の切り捨て通知 -- レスポンスには plan_node_limit（-1 = 無制限）と would_truncate_at（上限が適用される場合は min(total_matched, plan_node_limit)、それ以外の場合は total_matched）が含まれます。ドキュメントで推奨されているフロントエンドのヒューリスティック：would_truncate_at < total_matched の場合はユーザーに警告します。プランの上限によって、サンプルの一致件数が制限されています。MCP の metadata-template-preview-match ハンドラーは、この警告を自動的に _warnings に出力します。UI では plan_node_limit = -1 を「上限なし」として扱ってください。

• metadata-template-list と metadata-template-details の切り捨て通知 -- ライブ AI カテゴリー概要には、「一覧、詳細、プレビューの各エンドポイントは plan_node_limit、is_truncated、フィルタリング前の件数を、表示される（上限適用後の）件数とともに返すため、利用側でアップセルメッセージを表示できます」と記載されています。ライブリファレンスにある現在のレスポンス例には、これらのフィールドが明示されていないため、実行時に正確なフィールド名を確認してください。フィルタリング前の件数フィールドは、テンプレート単位の nodes/ 一覧エンドポイントでは total_count_unfiltered という名前です。ドキュメントでは list／details のフィールド名が確定しておらず、異なる場合があります。どちらかのエンドポイントで is_truncated が true の場合は、アップセルの案内を表示してください。

• metadata-template-suggest-fields の同時実行 -- サーバーはユーザーとワークスペースの組み合わせごとに同時呼び出しをレート制限し、別の suggest-fields 呼び出しが進行中の場合は 409 Conflict を返します。数秒待ってから再試行してください。（以前の内部メモには誤って 406 と記載されていましたが、ライブドキュメントが正しく、409 です。）

• nodes/add/ の上限超過（REST エンドポイント。MCP アクションとしては公開されていません）-- **400（Fast.io エラーコード 1605、「Invalid Input」）**を返し、「上限を超える」ことを示す構造化メッセージが含まれます。同時呼び出しによって合計が上限を超えることはありません。事前に確認するには、テンプレート単位の nodes 一覧エンドポイントを読み取り、plan_node_limit - total_count_unfiltered で残り枠を計算してください。

• 自動マッチングでは通知なく上限が適用されます -- サーバー側の auto-match エンドポイント（現在、MCP アクションとしては公開されていません）は、マッチ可能なファイルがさらにある場合でも、plan_node_limit で上限を適用します（クレジットと LLM コストを節約するためです）。auto-match もテンプレート単位の nodes/ 一覧も現在 MCP ツールから操作できないため、自動マッチング後にマッピングされたファイル数を正確に把握する必要があるエージェントは、これらの REST エンドポイントを直接呼び出すか、この制約をユーザーに伝える必要があります。

• MCP ツールの対応範囲 -- workspace MCP ツールは、テンプレートの CRUD（metadata-template-{create,delete,list,details,update,clone}）、ワークスペースへの割り当て（metadata-template-{assign,unassign,resolve,assignments}）、ビュー作成フロー（metadata-template-{preview-match,suggest-fields}）、ユーザーごとの保存済みビュー（metadata-view-{get,save,delete}、metadata-views-list）、保存済みビューの TSV エクスポート（metadata-view-export）、メタデータ値のキーワード検索（metadata-search）、ファイル単位のメタデータ（metadata-{get,set,delete,extract}、metadata-list-files、metadata-list-templates-in-use、metadata-versions）を公開しています。現在、nodes/add、nodes/remove、テンプレート単位の nodes/ 一覧、auto-match、extract-all、/metadata/eligible/ は公開していません。これらのワークフローが必要なエージェントは、この制約をユーザーに伝える必要があります。

• テンプレートカテゴリー -- legal、financial、business、medical、technical、engineering、insurance、educational、multimedia、hr。

• フィールドタイプ -- string、int、float、bool、json、url、datetime。各タイプには任意の制約（min、max、default、fixed_list、can_be_null）を設定できます。

• 2 種類のメタデータ -- テンプレートメタデータはテンプレートのフィールド定義に準拠します。カスタムメタデータは、どのテンプレートにも紐付かない自由形式のキーと値のペアです。

• システムテンプレート -- ワークスペースに割り当てると自動的に複製される、事前構築済みのテンプレートです。そのため、カスタマイズがグローバル定義に影響することはありません。

• AI 抽出 -- extract アクションは AI を使用してファイルの内容を分析し、メタデータフィールドに値を自動入力します。抽出された値には is_auto: true のフラグが付けられます。AI クレジットを消費します。

• バージョン履歴 -- メタデータの変更はバージョンスナップショットとして追跡され、versions アクションからアクセスできます。

• テンプレート ID は、mt_ を接頭辞とする英数字の文字列です（例：mt_abc123def456）。

所有権の移譲

エージェントが価値を提供する主な方法は、何かを構築してから人間に引き渡すことです。また、エージェントのプランのクレジットが尽きて API 呼び出しが 402 Payment Required を返し始めた場合にも、推奨される対応です。アップグレードできる人間に組織を移譲してください。

重要：アカウント種別の制限。 移譲／取得のワークフロー（org アクションの transfer-token-create、transfer-token-list、transfer-token-delete、transfer-claim）は、エージェントが **エージェントアカウント**（authアクションのsignup を使用）を作成し、そのエージェントアカウントが組織を所有している場合にのみ利用できます。エージェントが **人間のアカウント**（authアクションのsignin` を使用）でサインインしている場合、移譲／取得 API は利用できません。人間が所有する組織は、人間が Fast.io ダッシュボードから直接アップグレードする必要があります。

手順：

1. エージェントが auth アクションの signup でエージェントアカウントを作成し、org アクションの create で組織を作成します。org アクションの create-workspace でワークスペースを設定し、ファイルをアップロードして、共有を設定します
2. エージェントが org アクションの transfer-token-create で移譲トークンを生成します（有効期間は 72 時間です）
3. エージェントが人間に取得 URL を送ります：https://go.fast.io/claim?token=<token>
4. 人間がリンクをクリックし、自分のアカウントで組織を取得します

移譲するタイミング：

• 組織が人間による利用の準備を終えたとき（ワークスペースの設定、ファイルのアップロード、共有の設定が完了している）
• エージェントのプランのクレジットが尽きたとき（402 Payment Required）――人間がアップグレードできるよう、移譲します
• 人間が組織の引き継ぎを明示的に依頼したとき

移譲トークンの管理：

• org アクションの transfer-token-list -- 新しいトークンを作成する前に、既存の保留中トークンを確認します
• org アクションの transfer-token-delete -- 移譲が不要になった場合にトークンを取り消します
• org アクションの transfer-claim -- トークンを使用して組織を取得します（取得する人間のエージェントが使用します）

移譲後の動作：

• 人間が組織とすべてのワークスペースの所有者になります
• エージェントは管理者アクセス権を維持します（引き続きファイルや共有を管理できます）
• 人間は無料プランを利用できます（クレジット制で、試用期間はありません）
• 人間はいつでも Pro または Business にアップグレードできます

エージェントのユースケース： ユーザーが「チーム用のプロジェクトワークスペースを設定して」と言います。エージェントは組織を作成し、ワークスペースの構成を整え、テンプレートをアップロードし、クライアント向け成果物の共有を設定して、チームメンバーを招待し、最後に所有権を移譲します。人間は、設定がすべて完了したプラットフォームをすぐに利用できます。エージェントは管理者として残り、引き続き管理を行います。

402 Payment Required のユースケース（エージェントアカウント）： 作業中に、エージェントのクレジット上限に達します。org アクションの transfer-token-create を呼び出し、取得 URL を人間に送って、作業を続けるにはアップグレードが必要だと説明します。エージェントは管理者アクセス権を維持し、人間がアップグレードした後に作業を再開します。

402 Payment Required のユースケース（人間のアカウント）： エージェントは組織を移譲できません。代わりに、組織のクレジットが尽きたことと、請求プランのアップグレードが必要であることをユーザーに伝えてください。Fast.io ダッシュボードに案内するか、org アクションの billing-create を使用して有料プランに更新してください。

ワークフロー（タスク、作業ログ、承認、ToDo）

ワークスペースと共有では、構造化されたタスク管理、アクティビティログ、承認ゲート、簡易チェックリストを追加するオプションのワークフローレイヤーを利用できます。ワークフロー機能は切り替え式で、利用する前に明示的に有効にする必要があります。共有では、ワークフローにアクセスできるのは管理者または指定メンバーのロールのみです。ゲストや閲覧のみのユーザーは、ワークフロー機能にアクセスできません。

ワークフローの有効化

• ワークスペース： workspace アクションの enable-workflow と workspace_id を使用します
• 共有： share アクションの enable-workflow と share_id を使用します

ワークフローが有効かどうかは、workspace アクションの details または share アクションの details で確認できます。レスポンスに workflow: true が含まれているかを確認してください。

ワークフローを無効にすると（workspace アクションの disable-workflow または share アクションの disable-workflow）、すべてのワークフローデータにアクセスできなくなりますが、データは保持されます。再度有効にすると、アクセスが復元されます。

タスクリストとタスク

タスクはリストごとに整理されます。各ワークスペースまたは共有領域には複数のタスクリストを作成でき、各リストには個々のタスクが含まれます。

• タスクリストには名前と任意の説明があります。task アクション create-list で作成し、task アクション list-lists で一覧表示します。
• タスクにはタイトル、説明、ステータス、優先度、担当者、依存関係、および任意のノードリンクがあります。task アクション create-task で作成し、task アクション list-tasks で一覧表示します。
• ステータス： pending、in_progress、complete、blocked
• 優先度： 0 = なし、1 = 低、2 = 中、3 = 高、4 = 緊急
• 担当者にはプロフィール ID を指定します（保留中のメンバーを含む、ワークスペースまたは共有領域のメンバー）。割り当てまたは割り当て解除には、task アクション assign-task を使用します。保留中のメンバー（招待済みで、まだ登録していないメンバー）にもタスクを割り当てられ、登録後も割り当ては維持されます。
• 一括操作： task アクション bulk-status は、一度に最大 100 件のタスクのステータスを変更します。
• タスクの移動： task アクション move-task は、同じプロフィール内でタスクを別のリストに移動します。移動元の list_id、task_id、および target_task_list_id が必要です。任意で sort_order を指定すると、移動先リスト内の位置を制御できます（デフォルト：0）。
• 並べ替え： task アクション reorder-tasks は、リスト内のタスクの表示順を設定します。task アクション reorder-lists は、プロフィール内のタスクリストの表示順を設定します。希望する順序で ID の配列を渡すと、サーバーが API 用の {id, sort_order} オブジェクトに変換します。
• 作成者の追跡： タスクとタスクリストには、作成者のプロフィール ID を示す created_by フィールドが含まれます。
• フィルター付きリスト： task アクション filtered-list は、カテゴリでフィルターしたタスクを返します。「assigned」（自分に割り当てられたタスク）、「created」（自分が作成したタスク）、または「status」（ステータス別。status パラメーターが必要）を指定できます。対象はワークスペースまたは共有領域です。
• 概要： task アクション summary は、タスクの合計数、ステータス別の内訳、自分に割り当てられたタスク数、自分が作成したタスク数といった簡易的な集計を返します。
• Markdown 出力： format: "md" を渡すと、JSON の代わりに人が読みやすい Markdown が返されます。

作業ログ

作業ログは、タスク、タスクリスト、ストレージノード、またはプロフィールに関連付けられた、追記専用の時系列アクティビティログです。エントリーは作成後に編集または削除できません。

• エントリー： 通常のログエントリーは worklog アクション append で追記します。進捗報告、決定事項、判断理由、ステータスの変更に使用します。
• 割り込み： 優先度の修正は、worklog アクション interject で作成します。割り込みは常に緊急として扱われ、他の参加者による確認が必要です。
• 確認： worklog アクション acknowledge は、割り込みを確認済みとしてマークします。worklog アクション unacknowledged は、まだ確認が必要な割り込みを一覧表示します。エントリーには acknowledgable ブール値が含まれます。値が true の場合、そのエントリーは確認可能な未確認の割り込みです。
• 応答フィールド： エントリーには acknowledged（ブール値）、acknowledgable（ブール値）、updated（YYYY-MM-DD HH:MM:SS UTC 形式のタイムスタンプ）、および created（YYYY-MM-DD HH:MM:SS UTC 形式のタイムスタンプ）が含まれます。
• プロフィール単位の一覧表示： worklog アクション profile-list は、ワークスペースまたは共有領域レベルのすべての作業ログエントリーを一覧表示します（エンティティ単位の list とは異なります）。
• フィルター付きリスト： worklog アクション filtered-list は、カテゴリでフィルターした作業ログを返します。「authored」（自分が作成した作業ログ）または「interjections」（自分宛ての割り込み）を指定できます。任意で type によるサブフィルター（「info」または「interjection」）も指定できます。
• 概要： worklog アクション summary は、エントリーの合計数、エントリー種別ごとの内訳、自分が作成したエントリー数、保留中の割り込み数といった簡易的な集計を返します。
• Markdown 出力： 人が読みやすい形式で出力するには、format: "md" を渡します。

コメントとディスカッション -- クイックスタート

使用する場面： ファイルにフィードバックを残す、コンテナレベルのディスカッションを開始する、またはワークフローの承認／タスクにメモを添付する場合です。

コメントは JSON です -- リクエストボディには必ず JSON を使用してください（Content-Type: application/json）。コメント API で 406 エラーが発生する原因の第 1 位です。

3 つの関連付けモード -- 呼び出す前に 1 つ選んでください：

1. ノードに関連付ける（特定のファイル／フォルダーのスレッド）：

• comment アクションの add に、profile_type、profile_id、node_id、text を指定します（アンカー用の省略可能な reference、返信用の parent_comment_id も指定できます）。
• POST /comments/{entity_type}/{parent_id}/{node_id}/ を呼び出します。list アクションで一覧表示します。

2. ワークスペース／共有に関連付ける（コンテナのトップレベルスレッド）：

• node_id が必要な comment アクションの add では公開されていません。コンテナレベルのコメントを追加するには、execute 経由で基盤のエンドポイントを呼び出します：JSON ボディ {body, parent_id?} を指定して POST /comments/{entity_type}/{parent_id}/ を呼び出します。comment アクションの list-all で一覧表示します。

3. ワークフローにリンクする（既存のコメントを承認またはタスクに添付）：

• ステップ A：モード 1 または 2 でコメントを作成します。
• ステップ B：comment アクションの link に、comment_id、linked_entity_type: "task" | "approval"、linked_entity_id を指定します。
• comment アクションの linked で逆引きします。comment アクションの unlink でリンクを解除します。コメントには同時に最大 1 つのワークフローリンクを設定できます。

有効な entity_type／profile_type の値：

• 作成／一覧表示エンドポイント："workspace" または "share" のみ。
• リンク／リンク解除／逆引きエンドポイント："task" または "approval" のみ（worklog_entry、node、share は不可）。

スレッド化： 1 階層のみです。parent_comment_id（ボディフィールド：parent_id）にはトップレベルコメントの ID を指定します。返信への返信は自動的に同じ階層の返信として扱われます。

リアクション： comment アクションの reaction-add に、comment_id と emoji を指定します。ユーザーごとにコメントあたり 1 つのリアクションのみ設定でき、新しいリアクションを追加すると以前のものが置き換わります。

避けるべきパターン：

• 作成エンドポイントに entity_type: "approval"（または "task"）を渡さないでください。受け付けるのは "workspace" または "share" のみです。承認にコメントするには、まず親のワークスペース／共有にコメントを作成し、その後リンクします。
• /approvals/{id}/comments/ や /tasks/{id}/comments/ を独自に作成しないでください。このようなパスは存在しません。
• フォームエンコードされたボディを使用しないでください。コメントはどこでも JSON です。コードモードでは fastio.post() ではなく fastio.postJson() を使用します。
• 異なるワークスペース／共有の node_id と parent_id を組み合わせないでください。ノードは指定した親の配下に存在する必要があります。404 は通常、親の指定が間違っていることを意味します。
• worklog_entry へのリンクを試みないでください。リンク先として使えるのは task と approval のみです。

ワークフロー承認 -- クイックスタート

使用するタイミング： ファイル、フォルダー、またはタスクについて、1 人以上のレビュー担当者による正式な承認が必要な場合です。

承認はエンティティに直接紐づきます -- 共有には紐づきません。よくある間違いは、承認を保持するために共有を作成することです。作成しないでください。共有は配布（送信／受信／交換）のためのもので、承認はエンティティ自体に設定されるレビューゲートです。

ステップ 1 -- ワークスペースでワークフローを有効にする（ワークスペースごとに一度）：

• workspace アクション enable-workflow に workspace_id を指定します。

ステップ 2 -- 対象ノードにレビュー担当者ごとに 1 件の承認を作成する：

• approval アクション create に以下を指定します。
  • profile_type: "workspace"（または "share"）、profile_id: <workspace_id_or_share_id>
  • entity_type: "node"（ファイルまたはフォルダーの場合）
  • entity_id: <node_id>
  • description（レビュー依頼。1～65535 文字）
  • approver_id: <user_id> -- レビュー担当者（プロファイルのメンバーである必要があります。参加保留中のメンバーも指定できます）
• レビュー担当者が複数いる場合は、approver_id の値を変えてこの呼び出しを N 回繰り返します。一括作成モードはありません。

有効な entity_type の値： node（ファイル／フォルダー）、task、worklog_entry、share。ファイル／フォルダーのレビューには node を使用します。

解決： approval アクション resolve に approval_id と resolve_action: "approve" | "reject" を指定します（comment は任意です）。

避けるべきアンチパターン：

• ファイルの共有を作成しないでください -- 承認はノードに直接設定します。
• ファイルの承認を保持するためだけにタスクを作成しないでください -- entity_type: "node" を使用します。
• ToDo を作成しないでください -- ToDo はチェックリストであり、レビューゲートではありません。
• approver_id に指定できるのは 1 人のユーザーであり、グループではありません。レビュー担当者が 3 人の場合は、3 回呼び出します。

承認

タスク、ストレージノード、作業ログエントリー、または共有を対象とする正式な承認依頼です。明示的な承認が必要な判断に使用します。

• 作成： approval アクション create に、profile_type、profile_id、entity_type（"task"、"node"、"worklog_entry"、または "share"）、entity_id、description（1～65535 文字）、および任意で approver_id（単一のプロファイル ID。エンティティのメンバーである必要があります。参加保留中のメンバーも指定できます）を指定します。
• 解決： approval アクション resolve に、profile_type、profile_id、approval_id、および resolve_action: "approve" または "reject" を指定し、必要に応じてコメントを追加します。解決できるのは指定された承認者のみです。
• 一括操作： approval アクション bulk-create は、共有内のすべてのファイルとノートを対象に承認依頼を作成します（ノードは最大 50 件）。approval アクション bulk-approve は、共有内の保留中の承認をすべて解決します（version_match=false の古い承認はスキップします）。approval アクション bulk-reject は、共有内の保留中の承認をすべて却下します。
• バージョン追跡： 承認では version_id と version_match を追跡します。承認の作成後にノードが変更されると、version_match は false（古い状態）になります。一括操作では、古いコンテンツに対する解決を防ぐため、古い承認をスキップします。
• フィルター済みリスト： approval アクション filtered-list は、カテゴリ（"pending"、"created"、"assigned"、"resolved"）でフィルターした承認を返します。profile_type／profile_id を指定してワークスペースまたは共有の範囲に限定するか、両方を省略してプロファイルをまたぐユーザーレベルのビューを取得します。
• 概要： approval アクション summary は、簡易的な件数を返します。自分が作成した承認と自分に割り当てられた承認について、保留中／承認済み／却下の内訳を確認できます。
• 更新： approval アクション update に profile_type、profile_id、approval_id を指定すると、保留中の承認を変更できます。説明、承認者、期限、ノード参照、またはメタデータを変更できます。更新できるのは保留中の承認のみです。
• 削除： approval アクション delete に profile_type、profile_id、approval_id を指定すると、承認を完全に削除します（ステータスは問いません）。approval アクション bulk-delete は、共有内のすべての承認を完全に削除します（最大 500 件）。
• ステータス： pending、approved、rejected
• Markdown 出力： 人が読みやすい形式で出力するには、format: "md" を指定します。

Todos

ワークスペースと共有に限定された、シンプルなフラット形式のチェックリストです。ネストには対応しておらず、チェックを付けられる項目のリストのみです。

• 作成： タイトルを指定して todo アクション create を実行します。assignee_id は省略可能で、招待中のメンバーも指定できます。
• 切り替え： todo アクション toggle は、単一の todo の完了状態を切り替えます。todo アクション bulk-toggle は、最大 100 件の todo の完了状態を一度に設定します。
• 更新／削除： todo アクション update はタイトルまたは担当者を変更します。todo アクション delete は todo を論理削除します。
• 作成者の追跡： Todo には created_by フィールド（作成者のプロフィール ID）が含まれます。
• フィルター済みリスト： todo アクション filtered-list は、カテゴリでフィルターした todo を返します。カテゴリは「assigned」（自分に割り当て済み）、「created」（自分が作成）、「done」（完了）、「pending」（未完了）です。
• 概要： todo アクション summary は、合計、完了、未完了、自分に割り当て済み、自分が作成した項目の簡潔な件数を返します。
• Markdown 出力： 人が読みやすい形式で出力するには、format: "md" を渡します。

エージェントのナレッジレイヤーとしてのノート

ノート（type: "note"）は、ワークスペースのストレージに保存される Markdown ファイルです（上記のノートを参照）。ワークフロー機能と組み合わせることで、ノートはナレッジレイヤーになります。

• AI による自動インデックス作成： ワークスペースインテリジェンスが有効な場合、アップロードされたファイルと同様に、ノートが取り込まれて RAG 用にインデックス化されます。
• タスクをノートにリンク： タスクでは、ノートを含むストレージノードを参照できます。プロジェクトの背景、要件、参考資料のコンテキストノートを作成し、それらのノートにリンクしたタスクを作成すると、全体のコンテキストを把握できます。
• 推論のための作業ログ： 作業ログのエントリを使って、決定事項、進捗、時間の経過に伴う推論を記録します。時系列のログによって、構造化されたタスクリストを補完する経緯が構築されます。
• AI による全コンテキストの検索： インテリジェンスが有効な場合、AI チャットはノート、作業ログ、タスクの説明、アップロードされたファイルを横断して検索でき、プロジェクトの全履歴に基づいた包括的な回答を提供します。

推奨パターン： プロジェクトのコンテキストと要件についてノートを作成します。作業フェーズごとにタスクリストを作成します。タスクを関連するノートにリンクします。作業ログで進捗を記録します。決定事項について承認を依頼します。これにより、AI はこれらすべての成果物を横断して検索し、「なぜこのアプローチを選んだのですか？」といった質問に回答できます。

権限パラメーターの値

いくつかのツールでは、使用できる値が定められた権限パラメーターを使用します。ツールを呼び出すときは、次の文字列をそのまま使用してください。

組織の作成（org アクション create）

パラメーター	使用可能な値	デフォルト
perm_member_manage	Owner only、Admin or above、Member or above	Member or above
industry	unspecified、technology、healthcare、financial、education、manufacturing、construction、professional、media、retail、real_estate、logistics、energy、automotive、agriculture、pharmaceutical、legal、government、non_profit、insurance、telecommunications、research、entertainment、architecture、consulting、marketing	unspecified
background_mode	stretched、fixed	stretched

ワークスペースの作成（org アクション create-workspace）と更新（workspace アクション update）

パラメーター	使用可能な値	デフォルト
perm_join	Only Org Owners、Admin or above、Member or above	Member or above
perm_member_manage	Admin or above、Member or above	Member or above

共有の作成（share アクション create）

パラメーター	許可される値	デフォルト
type	send、receive、exchange	exchange
storage_mode	independent、workspace_folder	independent
access_options	Only members of the Share or Workspace、Members of the Share, Workspace or Org、Anyone with a registered account、Anyone with the link	Only members of the Share or Workspace
invite	owners、guests	owners
notify	never、notify_on_file_received、notify_on_file_sent_or_received	never
display_type	list、grid	grid
intelligence	true、false	false（workspace_folder 共有では常に false）
comments_enabled	true、false	true
download_security	off、medium、high	off
guest_chat_enabled	true、false	false
anonymous_uploads_enabled	true、false	false
workspace_style	true、false	true
background_image	0～128	0

共有の制約：

• Receive 共有と Exchange 共有では、Anyone with the link のアクセスを使用できません。このオプションは Send 共有でのみ利用できます。
• パスワード保護（password パラメーター）は、access_options が Anyone with the link の場合にのみ許可されます。
• 有効期限（MySQL 形式 YYYY-MM-DD HH:MM:SS の expires パラメーター）は、workspace_folder 共有では設定できません。
• workspace_folder 共有ではインテリジェンスはサポートされません。ワークスペースフォルダー共有を作成すると、渡された値にかかわらず、intelligence=false が常に設定されます。intelligence=true を指定してワークスペースフォルダー共有を更新すると、エラーが返されます。ファイル／フォルダーをスコープとする AI チャットおよびセマンティック検索は、ワークスペースフォルダー共有では利用できません。代わりに親ワークスペースの AI エンドポイントを使用してください。基本的なチャットと files_attach（ファイルの直接添付）は引き続き利用できます。
• custom_name、title、description のフィールド長および形式の制約については、以下のプロフィールフィールドの制約テーブルに記載されています。
• 色のパラメーター（accent_color、background_color1、background_color2）には、JSON 文字列を指定します。
• storage_mode='workspace_folder' と併用すると、create_folder は共有用の新しいワークスペースフォルダーを作成します。
• anonymous_uploads_enabled を有効にすると、ゲストはアカウントを作成せずに Receive／Exchange 共有にファイルをアップロードできます。「Anyone」アクセスレベルが必要です。Send 共有およびポータルには適用されません。

プロフィールフィールドの制約

すべてのプロフィールフィールドはサーバー側で検証されます。これらの制約に違反するリクエストは、400 エラーで拒否されます。

エンティティ	フィールド	API キー	最小	最大	パターン	必須	null 許容
Org	ドメイン	domain	2	63	^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$	はい（作成時）	いいえ
Org	名前	name	3	100	制御文字なし	はい	いいえ
Org	説明	description	10	1000	制御文字なし	いいえ	はい
Workspace	フォルダー名	folder_name	4	80	^[\p{L}\p{N}-]+$（文字、数字、ハイフン）	はい（作成時）	いいえ
Workspace	名前	name	2	100	制御文字なし	はい	いいえ
Workspace	説明	description	10	1000	制御文字なし	いいえ	はい
Share	カスタム名	custom_name	4	80	^[\p{L}\p{N}]+$（文字、数字のみ）	はい（作成時）	いいえ
Share	カスタム URL	custom_url	10	100	—	はい	はい
Share	タイトル	title	2	80	制御文字なし	はい	はい
Share	説明	description	10	500	制御文字なし	いいえ	はい

• 「制御文字なし」 = Unicode 制御文字（\p{C}）を拒否します
• Org のドメイン：小文字の ASCII 英数字とハイフンを使用します。ハイフンで始めたり、終えたりすることはできません
• Workspace の folder_name：Unicode の文字、数字、ハイフンを使用します。全体で一意であり、Org ごとのスコープではありません。重複を避けるため、{org_id}-{name} の形式を推奨します（名前が使用済みの場合、create-workspace によって自動的に適用されます）
• Share の custom_name：Unicode の文字と数字のみを使用します（ハイフンや特殊文字は使用できません）
• Share の description の最大値は 500 です（Org／Workspace は 1000）

---

4. エージェントプラン — 無料プラン

エージェントプランは、AI エージェント向けに設計された無料プランです。クレジットカード不要、トライアル期間なし、有効期限なしです。価値を構築して実証するのに十分なリソースがあり、Org が有料プランを利用する人間に移管された際には、さらに拡張できます。

リソース上限

リソース	含まれる内容
価格	$0 — クレジットカード不要、トライアル期間なし、有効期限なし
ストレージ	50 GB
最大ファイルサイズ	1 GB
月間クレジット	5,000（30 日ごとにリセット）
Workspace	5
Share	50
Workspace ごとのメンバー数	5
Share ごとの招待数	10
アカウントの自動削除	なし

クレジットの消費量

プラットフォーム上のすべてのアクティビティで、月間 5,000 クレジットの上限からクレジットを消費します。

リソース	消費量
ストレージ	100 クレジット/GB
帯域幅	212 クレジット/GB
AI チャットトークン	100 トークンあたり 1 クレジット
取り込みドキュメントページ	10 クレジット/ページ
取り込み動画	5 クレジット/秒
取り込み音声	0.5 クレジット/秒
取り込み画像	5 クレジット/画像
ファイル変換	25 クレジット/変換

クレジットがなくなると、Org は機能が制限された状態になり、API 呼び出しは 402 Payment Required を返します。Org が削除されることはありません。現在のクレジット使用量と残高を確認するには、org のアクション limits を使用してください。

402 が発生した場合、またはクレジットが少なくなった場合：

• エージェントアカウント（auth のアクション signup で作成）： Org を人間に移管します。org のアクション transfer-token-create を呼び出して移管トークンを生成し、次のクレーム URL を人間に送信します：https://go.fast.io/claim?token=<token>。Org のクレームが完了すると、有料プランにアップグレードして無制限のクレジットを利用できます。管理者アクセス権は維持され、アップグレード後すぐに作業を再開できます。これは想定されているワークフローです。エージェントは無料プランで構築し、準備が整った段階で料金を支払う人間に引き継ぎます。
• 人間のアカウント（auth のアクション signin でサインイン）： 移管／クレーム API は使用できません。Org の請求プランを直接アップグレードする必要があることをユーザーに伝えてください。Fast.io ダッシュボードからアップグレードするか、org のアクション billing-create を呼び出してサブスクリプションを有料プランに更新できます。

Transfer 後 -- 人間向けプランの選択肢

エージェントが組織を人間に移管すると、人間は無料プラン（クレジット制、試用期間なし）を利用でき、アップグレードもできます。

機能	エージェント（無料）	無料（人間）	Pro	Business
月間クレジット	5,000	5,000	無制限	無制限
ストレージ	50 GB	50 GB	1 TB	5 TB
最大ファイルサイズ	1 GB	1 GB	25 GB	50 GB
ワークスペース	5	5	10	1,000
共有	50	50	1,000	50,000

移管の流れは、エージェントが価値を提供するための主要な方法です。エージェント向け無料プランですべてを設定してから、引き渡します。人間は準備ができた時点でアップグレードし、エージェントは管理者アクセスを維持して引き続き管理できます。

---

5. ツールのカテゴリ

19 個のツールは、アクションベースのルーティングを使用します。各ツールは Fast.io プラットフォームの特定の領域を扱い、複数のアクションを提供します。

auth

認証、サインイン／サインアップ、二要素認証、API キー管理、OAuth セッション管理を行います。あらゆるエージェントとのやり取りは、常にここから始まります。

アクション： signin、signout、signup、check、session、status、set-api-key、email-check、email-verify、password-reset-request、password-reset、2fa-verify、2fa-status、2fa-enable、2fa-disable、2fa-send、2fa-verify-setup、pkce-login、pkce-complete、api-key-create、api-key-update、api-key-list、api-key-get、api-key-delete、oauth-list、oauth-details、oauth-revoke、oauth-revoke-all

user

現在のユーザープロフィールの取得と更新、連絡先の検索、招待の管理、ユーザーアセット（プロフィール写真）のアップロードと削除、アカウント利用資格の確認、ユーザーが所属する共有の一覧表示、個人用 AI 指示（プラットフォームが AI 機能に適用する Markdown 形式のガイダンス）の管理を行います。

アクション： me、update、search-contacts、close、details-by-id、profiles、allowed、org-limits、list-shares、invitation-list、invitation-details、accept-all-invitations、asset-upload、asset-delete、asset-types、asset-list、instructions-get、instructions-set、instructions-clear

search-contacts は個人の連絡先リスト（過去のやり取り）を検索し、{email: name} のみを返します。user_id もコンテキストの範囲も含まれません。特定のワークスペース／共有／組織のメンバーを探すには、org action=members、workspace action=members、または share action=members を使用してください。

AI 指示：instructions-get／instructions-set／instructions-clear は、/user/me/instructions/ にある、自分だけが対象の単一の Markdown スロットを管理します（最大 65536 バイトの UTF-8、set は全置換、ソフトクリアでは監査レコードが保持されます）。ユーザープロフィールには me スコープのバリエーションはありません。すでに自分専用だからです。初回の読み取りでは 404 ではなく、タイムスタンプが null の content: "" が返されます。

org

組織の CRUD、メンバー管理、請求とサブスクリプションの操作、ワークスペースの作成、招待ワークフロー、アセット管理（アップロード、削除）、組織の検索、所有権の移転、カスタムドメインの管理、AI 指示（組織全体およびユーザーごとのスロット）。

アクション: list、details、create、update、close、public-details、limits、list-workspaces、list-shares、create-workspace、billing-plans、billing-create、billing-cancel、billing-details、billing-activate、billing-reset、billing-members、billing-meters、members、invite-member、remove-member、update-member-role、member-details、leave、transfer-ownership、join、invitations-list、invitation-update、invitation-delete、transfer-token-create、transfer-token-list、transfer-token-delete、transfer-claim、discover-all、discover-available、discover-check-domain、discover-external、asset-upload、asset-delete、asset-types、asset-list、custom-domain-get、custom-domain-create、custom-domain-delete、custom-domain-validate、instructions-get、instructions-set、instructions-clear

AI 指示: instructions-get／instructions-set／instructions-clear は、省略可能な scope パラメーターを受け付けます。profile（デフォルト。組織全体のスロット — owner／admin のみ。非管理者にはコード 1680 の 403）または me（ユーザーごとのスロット — すべてのメンバーが利用可能）。2 つのスコープは独立しており、サーバー側では結合されません。まとめて表示したい場合は、クライアント側で連結してください。content の最大サイズは UTF-8 で 65536 バイトです。set は全置換され、ソフトクリアでは監査行が保持されます。

workspace

ワークスペースレベルの設定、ライフサイクル操作（更新、削除、アーカイブ、アーカイブ解除）、共有の一覧表示とインポート、ワークスペースのアセット管理、ワークスペースの検索、ノート（作成、読み取り、更新）、クイックシェア管理、メタデータ操作（テンプレートの CRUD、割り当て、ファイルメタデータの取得／設定／削除、AI 抽出）、ワークフローの切り替え（タスク、作業ログ、承認、ToDo の有効化／無効化）、AI 指示（ワークスペース全体およびユーザーごとのスロット）。

アクション: list、details、update、delete、archive、unarchive、members、list-shares、import-share、available、check-name、create-note、read-note、update-note、quickshare-get、quickshare-delete、quickshares-list、metadata-template-create、metadata-template-delete、metadata-template-list、metadata-template-details、metadata-template-update、metadata-template-clone、metadata-template-preview-match、metadata-template-suggest-fields、metadata-template-assign、metadata-template-unassign、metadata-template-resolve、metadata-template-assignments、metadata-view-get、metadata-view-save、metadata-view-delete、metadata-views-list、metadata-view-export、metadata-search、metadata-get、metadata-set、metadata-delete、metadata-extract、jobs-status、metadata-list-files、metadata-list-templates-in-use、metadata-versions、enable-workflow、disable-workflow、enable-import、disable-import、instructions-get、instructions-set、instructions-clear

AI 指示: instructions-get／instructions-set／instructions-clear は、省略可能な scope パラメーターを受け付けます。profile（デフォルト。ワークスペース全体のスロット — owner／admin のみ。非管理者にはコード 1680 の 403）または me（ユーザーごとのスロット — ゲストを除くすべてのメンバーが利用可能）。2 つのスコープは独立しており、サーバー側では結合されません。まとめて表示したい場合は、クライアント側で連結してください。content の最大サイズは UTF-8 で 65536 バイトです。set は全置換され、ソフトクリアでは監査行が保持されます。

share

共有の CRUD、公開情報の取得、アーカイブ、パスワード認証、アセット管理、共有名の空き状況確認、ワークフローの切り替え（タスク、作業記録、承認、ToDo の有効化／無効化）、AI 指示（共有全体およびユーザーごとのスロット）に対応します。

アクション： list, details, create, update, delete, public-details, archive, unarchive, password-auth, members, available, check-name, quickshare-create, enable-workflow, disable-workflow, instructions-get, instructions-set, instructions-clear

AI 指示：instructions-get／instructions-set／instructions-clear は省略可能な scope パラメーターを受け付けます。profile（デフォルト。共有全体のスロット。オーナー／管理者のみ利用可能。管理者以外はコード 166463 の 403）または me（ユーザーごとのスロット。登録済みメンバーのみ利用可能。匿名ユーザー／リンク経由のゲストはコード 185733 の 403）を指定します。2 つのスコープは独立しており、サーバー側では統合されません。統合した表示が必要な場合は、クライアント側で連結してください。content は UTF-8 で最大 65536 バイトです。set は全体を置き換え、ソフトクリアでは監査行が保持されます。

storage

ワークスペースおよび共有内のファイルとフォルダーを操作します。一覧表示、すべてのフォルダーを対象とした最近更新されたファイルの一覧表示、フォルダーの作成、移動、コピー、削除、名前変更、完全削除、復元、検索（インテリジェンスが有効な場合はキーワード検索またはセマンティック検索）、アップロードからのファイル追加、共有リンクの追加、ノードの転送、ゴミ箱の管理、バージョン操作、ファイルロック、プレビュー／変換 URL の生成に対応します。profile_type パラメーター（context_type も使用可能）が必要です（workspace または share）。

アクション： list, recent, details, search, trash-list, create-folder, copy, move, delete, rename, purge, restore, add-file, add-link, transfer, version-list, version-restore, lock-acquire, lock-status, lock-release, preview-url, preview-transform

upload

ファイルのアップロード操作に対応します。チャンク分割アップロードのライフサイクル（セッションの作成、プレーンテキスト、Base64 エンコードされたバイナリ、または BLOB 参照でのチャンクのアップロード、確定、ステータス確認、キャンセル）、1 回の呼び出しによるストリーミングアップロード（stream-upload はストリームセッションを作成し、バイト列をストリーミングして 1 回の呼び出しで自動的に確定します）、多数の小さなファイルの一括アップロード（1 往復で実行する batch）、外部 URL からのウェブインポート、アップロード制限とファイル拡張子の制限、セッション管理に対応します。大きなバイナリデータは POST /blob サイドカー（BLOB あたり 100 MB の上限）を経由します。エージェントが /blob にアクセスできない場合（サンドボックス環境）の小さなバイナリには、代わりに content_base64 を使用してください。サーバー側でデコードされ、上限は MCP トランスポートのメッセージサイズのみです。

アクション： create-session, stream-upload, batch, chunk, stream, finalize, status, cancel, list-sessions, cancel-all, chunk-status, chunk-delete, web-import, web-list, web-cancel, web-status, limits, extensions, blob-info

download

ワークスペースのファイル、共有ファイル、クイック共有リンクのダウンロード URL と ZIP アーカイブ URL を生成します。MCP ツールはバイナリデータをストリーミングできないため、これらのアクションはブラウザーで開くか、ダウンロードユーティリティに渡せる URL を返します。file-url および zip-url アクションには profile_type パラメーター（context_type も使用可能）が必要です（workspace または share）。応答には resource_uri フィールド（例：download://workspace/{id}/{node_id}）が含まれ、MCP クライアントは MCP リソースを通じてファイルの内容を直接読み取ることができます。直接ダウンロード URL には ?error=html が含まれており、ブラウザーではエラーが人間にも読みやすい HTML として表示されます。

アクション： file-url, zip-url, quickshare-details

ai

ワークスペースおよび共有で、AI を活用した RAG チャット、ドキュメント分析、共有可能な要約を利用できます。チャットの作成、メッセージの送信、AI 応答の読み取り（ポーリングあり）、チャットの一覧表示と管理、プライベートチャットの公開、AI 共有用 Markdown の生成、AI トークン使用量の追跡、自動タイトル生成に対応します。profile_type パラメーター（context_type も使用可能）が必要です（workspace または share）。

アクション： chat-create, chat-list, chat-details, chat-update, chat-delete, chat-publish, message-send, message-list, message-details, message-read, share-generate, transactions, autotitle

comment

コメントは {entity_type}/{parent_id}/{node_id} のスコープに属します。entity_type は workspace または share、parent_id は19桁のプロフィール ID、node_id はストレージノードの不透明な ID です。ファイル上のコメントを一覧表示し（ノード単位およびプロフィール全体を対象に、sort／limit／offset／filter パラメーターで指定）、任意の参照位置指定（画像の領域、動画／音声のタイムスタンプ、テキスト選択範囲付きの PDF ページ、Markdown／メモ内のテキスト選択範囲）を付けてコメントを追加し、1階層のスレッド形式の返信、単一コメントの再帰削除、一括コメントの非再帰削除、コメント詳細の取得、絵文字リアクション（コメントごとにユーザーあたり1つ）、ワークフローとのリンク（コメントとタスクまたは承認のリンク／リンク解除、逆引き検索）を行います。コメントでは JSON リクエストボディを使用します。

アクション： list、list-all、add、delete、bulk-delete、details、reaction-add、reaction-remove、link、unlink、linked

event

カテゴリ、サブカテゴリ、イベント名で詳細にフィルタリングして、監査／イベントログを検索します（分類の全容については、セクション7のイベントフィルタリングのリファレンスを参照してください）。AI によるアクティビティの要約、個々のイベントの全詳細の取得、最近のアクティビティの一覧表示、アクティビティの変更をロングポーリングできます。

アクション： search、summarize、details、activity-list、activity-poll

member

ワークスペースと共有のメンバーを管理します。メンバーの追加、削除、ロールの更新、所有権の移譲、退出、参加、招待経由での参加を行います。メンバー一覧には、アクティブなメンバーと保留中のメンバー（招待済みで、まだ登録していないメンバー）の両方が含まれます。保留中のメンバーには status: "pending" と、id、created、expires フィールドを含む invite オブジェクトが設定されます。entity_type パラメーター（workspace または share）が必要です。

アクション： add、remove、details、update、transfer-ownership、leave、join、join-invitation

invitation

ワークスペースと共有の招待を管理します。招待の一覧表示、状態別の一覧表示、更新、削除／取り消しを行います。保留中のメンバーの招待を削除すると、そのメンバーはメンバー一覧からも削除され、ワークフロー項目（タスク、承認、ToDo）の割り当ても解除されます。entity_type パラメーター（workspace または share）が必要です。

アクション： list、list-by-state、update、delete

asset

組織、ワークスペース、共有、ユーザーのアセット管理（アップロード、削除、一覧表示、読み取り）を行います。entity_type パラメーター（org、workspace、share、または user）が必要です。

アクション： upload、delete、types、list、read

task

ワークスペースと共有のタスクリストおよびタスクを管理します。タスクリストを作成して管理し、その中にステータス、優先度、担当者、依存関係を設定したタスクを作成します。ステータスの一括変更、並べ替え、Markdown 出力に対応しています。タスクとリストには created_by（作成者のプロフィール ID）が含まれます。対象のエンティティでワークフローが有効になっている必要があります。

アクション： list-lists、create-list、list-details、update-list、delete-list、list-tasks、create-task、task-details、update-task、delete-task、change-status、assign-task、bulk-status、move-task、reorder-tasks、reorder-lists、filtered-list、summary

worklog

エージェントの作業を追跡するアクティビティログです。アップロード、タスクの変更、共有の作成、その他の重要な操作の後に、実施した内容とその理由を記録すると、人間と AI が検索できる監査証跡を作成できます。確認応答が必要な緊急割り込みも作成できます。エントリは追記専用で、永続的に保存されます。対象のエンティティでワークフローが有効になっている必要があります。

アクション： append、list、interject、details、acknowledge、unacknowledged、profile-list、filtered-list、summary

approval

タスク、ストレージノード、worklog エントリ、共有のスコープに属する正式な承認リクエストです。指定した承認者を含む承認リクエストを作成し、承認または却下の判断で解決します。対象のエンティティでワークフローが有効になっている必要があります。

アクション： list、create、details、resolve、bulk-create、bulk-approve、bulk-reject、filtered-list、summary、update、delete、bulk-delete

todo

ワークスペースと共有ごとのシンプルなフラット形式のチェックリストです。Todo を個別または一括で作成、更新、削除、切り替えできます。Todo には created_by（作成者のプロフィール ID）が含まれます。ネストには対応していません。対象のエンティティでワークフローを有効にする必要があります。

アクション: list、create、details、update、delete、toggle、bulk-toggle、filtered-list、summary

apps

インタラクティブな MCP App ウィジェットの検出と起動を行います。利用可能なウィジェットの一覧表示、特定のウィジェットの詳細取得、ワークスペースまたは共有のコンテキストでのウィジェットの起動、特定のツールドメインに関連付けられたウィジェットの検索ができます。

アクション: list、details、launch、get-tool-apps

---

6. 共通のワークフロー

1. アカウントを作成してサインインする

自分の状況に合った方法については、セクション 2 の適切な方法の選択を参照してください。

方法 1 -- 自律型エージェント（新規アカウント）:

1. （任意）auth アクション email-check — これは参考情報にすぎないため、結果によって処理を制限しないでください。email-check が available: false を返しても、その後の signup ではメールアドレスが受け付けられる場合があります。必ず signup を呼び出し、そのエラーを正式な結果として扱ってください。
2. first_name、last_name、email、password を指定して auth アクション signup を実行します。エージェントアカウントとして登録され（agent=true が自動的に送信されます）、すぐにサインインします。
3. email を指定して auth アクション email-verify を実行し、確認コードを送信します。次に、email と email_token を指定して auth アクション email-verify を実行し、コードを検証します。ほとんどのエンドポイントを使用する前に必要です。
4. org アクション create を実行してエージェントプランで新しい組織を作成するか、org アクション list を実行して既存の組織を確認します。

方法 2 -- 人間を支援する（API キー）:

1. 人間が https://go.fast.io/settings/api-keys で API キーを作成し、エージェントに提供します。
2. API キーを指定して auth アクション set-api-key を呼び出します。キーが API で検証され、セッションに保存されます。以降のツール呼び出しはすべて自動的に認証されます。アカウントを作成する必要はありません。
3. org アクション list と org アクション discover-external を実行して、利用可能なすべての組織を検出します（組織の検出を参照）。

方法 3 -- 人間の組織に招待されたエージェント:

1. auth アクション signup を実行してエージェントアカウントを作成します（方法 1 と同じです）。
2. org アクション invite-member または member アクション add（entity_type: "workspace" を指定）を使って、人間に招待してもらいます。
3. user アクション accept-all-invitations を実行して招待を承諾します。
4. org アクション list と org アクション discover-external を実行して、利用可能なすべての組織を検出します（組織の検出を参照）。人間から組織ではなくワークスペースにのみ招待された場合、そのワークスペースは discover-external でのみ表示されます。

再度利用するユーザー:

1. email と password を指定して auth アクション signin を実行します。
2. two_factor_required: true の場合は、2FA の code を指定して auth アクション 2fa-verify を呼び出します。
3. org アクション list と org アクション discover-external を実行して、利用可能なすべての組織を検出します（組織の検出を参照）。

2. ファイルを閲覧してダウンロードする

1. org アクション list と org アクション discover-external を実行して、利用可能なすべての組織を検出します（組織の検出を参照）。org_id の値を控えてください。
2. org_id を指定して org アクション list-workspaces を実行し、組織内のワークスペースを取得します。workspace_id の値を控えてください。
3. profile_type: "workspace"、profile_id（ワークスペース ID）、node_id: "root" を指定して storage アクション list を実行し、ルートフォルダーを閲覧します。ファイルとサブフォルダーの node_id の値を控えてください。
4. profile_type: "workspace"、profile_id、node_id を指定して storage アクション details を実行し、特定のファイルの詳細（名前、サイズ、種類、バージョン）を取得します。
5. profile_type: "workspace"、profile_id、node_id を指定して download アクション file-url を実行し、トークンが埋め込まれた一時的なダウンロード URL を取得します。レスポンスには resource_uri（例：download://workspace/{id}/{node_id}）も含まれており、MCP クライアントはこれを使ってファイルの内容を直接読み取れます。ダウンロード URL をユーザーに返すか、リソース URI を使って MCP 経由でファイルを読み取ります。

3. ワークスペースにファイルをアップロードする

バイナリデータには、デフォルトで POST /blob サイドカーを使用してください。 MCP トランスポートの制限を回避でき、base64 によるオーバーヘッドがなく、最大 100 MB までのあらゆるサイズのテキストファイルとバイナリファイルに対応します。（インラインのテキストには content を使用します。/blob にアクセスできないサンドボックス環境で小さなインラインのバイナリを扱う場合は、MCP トランスポートのメッセージサイズが上限となる、インバンドの代替手段として content_base64 を使用します。）

オプション A：web-import（URL でアクセス可能なファイルに推奨） ファイルに URL（HTTP/HTTPS、Google Drive、OneDrive、Box、Dropbox）がある場合は、upload アクションの web-import を使用します。1 回の呼び出しで完了し、チャンク分割は不要です。以下のワークフロー 4 を参照してください。

オプション B：POST /blob サイドカー（その他すべてのファイル：テキストまたはバイナリ）

1. profile_type、profile_id、parent_node_id、filename、filesize を指定して、upload アクションの create-session を実行します。レスポンスには、そのまま使用できる curl コマンド blob_upload.curl_command が含まれます。
2. blob_upload.curl_command の curl コマンドを実行し、@<file> をファイルパスに置き換えます。{ "blob_id": "<uuid>", "size": <bytes> } が返されます。
3. upload_id、chunk_number: 1、blob_id: "<blob_id>" を指定して、upload アクションの chunk を実行します。
4. 追加のチャンクがある場合（大きなファイルを分割する場合）は、手順 2～3 を繰り返します。
5. upload_id を指定して、upload アクションの finalize を実行します。

重要： blob_upload.session_id は、この接続の MCP セッション ID です。/blob に POST する際は、Mcp-Session-Id ヘッダーに必ずこの正確なセッション ID を使用してください。異なるセッション ID（別途確立した MCP 接続のものなど）を使用すると、別の場所に blob がステージングされ、chunk アクションで見つけられません。

チャンクデータを渡す方法は 3 つあります（必ず 1 つだけ指定してください）。

• blob_id — POST /blob のレスポンスに含まれる blob ID。すべてのファイルで標準となるアップロード方法で、base64 も MCP トランスポートの制限もありません。（後方互換性のため、blob_ref としても受け付けます。）
• content — 小さなテキスト文字列（コードスニペットや短い JSON など）専用です。UTF-8 バイトとしてそのまま保存されます。ここに base64 を渡さないでください。base64 エンコードされたテキストファイルとして保存されます。大きなテキストファイルには、POST /blob と blob_id を使用してください。
• content_base64 — base64 エンコードされた文字列として、小さなバイナリコンテンツを渡す方法です。サーバーは書き込む前にデコードします。エージェントの環境で JSON 内の base64 を生成できるものの、POST /blob サイドカーにアクセスできない場合（ネットワークや認証トークンのないサンドボックス内のエージェントなど）に便利です。空白や改行は自動的に削除されます。実用上の上限は MCP トランスポートのメッセージサイズ（数 MB）によって決まります。より大きなバイナリファイルには、POST /blob と blob_id を使用してください。

upload_id を指定して upload アクションの finalize を実行すると、ファイルの組み立てが開始され、保存が完了するまで状態がポーリングされます。成功すると、status: "stored" または "complete"（new_file_id を含む）の最終セッション状態が返され、失敗するとエラーがスローされます。終端の失敗状態は assembly_failed（チャンクを組み立てられなかった）と store_failed（組み立てたファイルを保存できなかった。詳細は status_message を確認）です。ファイルはセッション作成時に指定した対象ワークスペースとフォルダーに自動的に追加されるため、別途ファイルを追加する呼び出しは不要です。

アップロードの状態：

状態	意味	終端状態？
ready	セッションが作成され、チャンクを待機中	いいえ
uploading	チャンクを受信中	いいえ
assembling	組み立て中	いいえ
complete	組み立てが完了し、ストレージへのインポートを待機中	いいえ
storing	ストレージにインポート中	いいえ
stored	完了。ファイルはストレージにあり、new_file_id を利用可能	はい（成功）
assembly_failed	組み立てエラー	はい（失敗）
store_failed	ストレージへのインポートに失敗	はい（失敗）

注： storage アクションの add-file が必要なのは、セッション作成時に指定した場所とは別の場所にアップロードをリンクする場合のみです。 同名アップロード（その場で置換、バージョン管理）： 対象フォルダーに同じ名前のファイルがすでに存在する場合、アップロードによって既存のノードがその場で上書きされます。node_id は維持され、以前の内容はバージョンとして保持されます。ファイルを「編集」する方法はこれです。削除して再アップロードしないでください。 同名ファイルを上書きすると、以前の内容は storage アクションの version-list（バージョン一覧の取得）と version-restore（version_id を指定して復元）で復元できます。node_id はバージョン間で変わらないため、コメント、タスク、承認、メタデータなどからの参照は引き続き機能します。上書きせずに両方のファイルを残すには、アップロード前に名前を変更してください。詳しい手順と実例については、セクション 4 のファイルの上書きを参照してください。

node_id による確実な上書き： ファイル名が変わっている可能性がある場合や、親フォルダーを再度特定せずに済ませたい場合は、create-session で target_node_id を指定して、上書き対象のノードを固定します。設定すると、parent_node_id は無視され、filename は省略できます（既存の名前を維持するには省略し、置換時に名前を変更するには新しい名前を指定します）。filename を省略すると、ツールが既存の名前を API に渡せるよう、storage の details 参照が 1 回追加で実行されます（更新モードでは引き続き name が必要です）。この追加のやり取りを省略するには filename を指定してください。サーバーは内部で action=update と file_id=<target_node_id> を使用します。node_id は維持され、新しいバージョンは storage アクションの version-list に表示されます。一般的な手順：storage アクションの list／details でノードを検索 → target_node_id を指定して upload アクションの create-session を実行 → POST /blob → chunk／stream → finalize。

4. URL からファイルをインポートする

ファイルの URL（HTTP/HTTPS、Google Drive、OneDrive、Box、Dropbox）があり、ローカルにダウンロードせずにワークスペースへ追加する場合に使用します。

1. url（ソース URL）、profile_type: "workspace"、profile_id（ワークスペース ID）、parent_node_id（対象フォルダーまたは "root"）を指定して、upload アクションの web-import を実行します。upload_id が返されます。
2. upload_id を指定して upload アクションの web-status を実行し、インポートの進捗を確認します。サーバーがファイルをダウンロードしてスキャンし、プレビューを生成し、AI 向けにインデックスを作成します（インテリジェンスが有効な場合）。
3. ジョブが完了すると、ファイルがワークスペースのストレージツリーに表示されます。

5. クライアントにファイルを届ける

ブランドに合わせたプロフェッショナルな共有を作成して、ファイルを外部に届けます。これにより、直接ダウンロードリンク、メール添付ファイル、S3 の署名付き URL を置き換えられます。

1. ファイルをワークスペースにアップロードします（ワークフロー 3 または 4 を参照）。
2. workspace_id、name、type: "send" を指定して share アクションの create を実行し、Send 共有を作成します。share_id が返されます。
3. share_id を指定して share アクションの update を実行し、次の項目を設定します。
   • password — アクセスにパスワードを必須にします
   • expiry_date — 指定した期間の経過後に共有を自動的に期限切れにします
   • access_level — メンバーのみ、組織メンバー、登録ユーザー、または一般公開を設定します
   • download_security — ゲストのダウンロードを制御します：off（制限なし）、medium（プレビューのみ）、high（ブロック）
   • ブランディングオプション：background_color、accent_color、gradient_color
   • post_download_message と post_download_url — ダウンロード後にメッセージを表示します
4. entity_type: "share"、entity_id（共有 ID）、email_or_user_id を指定して member アクションの add を実行し、受信者を追加します。Fast.io アカウントを持っていない場合は、招待が送信されます。
5. entity_type: "share" と entity_id（共有 ID）を指定して asset アクションの upload を実行し、ブランディング用のロゴや背景画像を追加します。
6. 受信者には、直接ダウンロードリンクではなく、ファイルをすぐにプレビューできるブランド仕様のページが表示されます。

6. ユーザーからドキュメントを収集する

Receive 共有を作成すると、メール添付やクラウドドライブのリンクを使わずに、ユーザーがファイルを直接アップロードできます。公開収集（求人への応募、フォームの送信など）では、anonymous_uploads_enabled を有効にすると、ゲストがアカウントを作成せずにアップロードできます。

1. share アクション create を実行し、workspace_id、name（例：「税務書類をこちらにアップロードしてください」）、type: "receive" を指定します。share_id が返されます。匿名でのアップロードを受け付ける場合は、anonymous_uploads_enabled: true も指定し、access_options を「登録済みアカウントを持つ全員」またはそれより広い範囲に設定します。
2. share アクション update を share_id とともに実行し、必要に応じてアクセスレベル、有効期限、ブランディングを設定します。
3. member アクション add を実行し、entity_type: "share"、entity_id（共有 ID）、email_or_user_id を指定して、アップロードするユーザーを招待します（匿名でアップロードできる共有の場合、この手順は省略します）。
4. ユーザーは、シンプルでブランドに合わせたインターフェースからファイルをアップロードします。
5. ファイルがワークスペースに表示されます。インテリジェンスが有効な場合は、AI によって自動的にインデックスが作成されます。
6. ai アクション chat-create を profile_type: "share" とともに実行し、Receive 共有のフォルダーを対象に、「必要な書類はすべて揃っていますか？」などの質問をします。

7. ナレッジベースを構築する

RAG クエリに備えて、すべてのコンテンツのインデックスが自動的に作成されるインテリジェントなワークスペースを作成します。

1. org アクション create-workspace を実行し、org_id、name、intelligence: "true" を指定します（このワークフローで RAG を利用するには、インテリジェンスが必須です）。
2. 参考ドキュメントをアップロードします（ワークフロー 3 または 4 を参照）。アップロード時に、AI がすべてのドキュメントのインデックスを自動的に作成し、要約します。
3. ai アクション chat-create を実行し、profile_type: "workspace"、profile_id（ワークスペース ID）、query_text、type: "chat_with_files"、folders_scope（カンマ区切りの nodeId:depth の組）を指定して、フォルダー全体またはワークスペース全体を検索します。
4. ai アクション message-read を profile_type: "workspace"、profile_id、chat_id、message_id とともに実行し、AI の応答が完了するまでポーリングします。特定のファイル、ページ、抜粋を参照する response_text と citations が返されます。
5. storage アクション search を profile_type: "workspace"、profile_id、クエリ文字列とともに実行します。インテリジェンスが有効な場合、ファイル名だけでなく意味に基づいてファイルを見つけるセマンティック検索が実行されます。
6. 回答には、特定のページやファイルへの引用が含まれます。出典を添えてユーザーに回答を返します。

8. ファイルについて AI に質問する

ワークスペースでインテリジェンスが有効かどうかによって、2 つの方法があります。

インテリジェンスが有効な場合（永続インデックス）：

1. ai アクション chat-create を、profile_type: "workspace"、profile_id（ワークスペース ID）、query_text、type: "chat_with_files"、および files_scope（カンマ区切りの nodeId:versionId ペア）または folders_scope（カンマ区切りの nodeId:depth ペア、深度の範囲は 1～10）とともに実行します。重要： files_scope と files_attach は併用できません。両方を送信するとエラーになります。chat_id と message_id が返されます。
2. ai アクション message-read を、profile_type: "workspace"、profile_id、chat_id、message_id とともに実行します。AI の応答が完了するまで、API を最大 15 回（2 秒間隔、約 30 秒）ポーリングします。response_text と citations が返されます。ヒント： 組み込みのポーリング時間が切れた場合は、message-read を繰り返し呼び出す代わりに、ワークスペース ID を指定して event アクション activity-poll を使用してください。上記の「アクティビティのポーリング」セクションを参照してください。
3. 追加の質問をするには、ai アクション message-send を、profile_type: "workspace"、profile_id、chat_id、query_text とともに実行します。新しい message_id が返されます。
4. 新しい message_id を指定して、再度 ai アクション message-read を実行し、追加の質問への応答を取得します。

インテリジェンスが無効な場合（ファイル添付）：

1. ai アクション chat-create を、profile_type: "workspace"、profile_id、query_text、type: "chat_with_files"、および特定のファイルを指定する files_attach（カンマ区切りの nodeId:versionId、最大 20 ファイル／200 MB）とともに実行します。ファイルには ai.attach: true が設定されている必要があります（storage アクション details で確認してください）。AI は永続インデックスを作成せず、添付ファイルを直接読み取ります。
2. ai アクション message-read を実行して、応答を取得します。取り込みクレジットはかからず、チャットのトークンクレジットのみが消費されます。

9. 人間に引き継ぐためのプロジェクトを設定する

エージェントから人間への引き継ぎを行うワークフロー全体です。これは、エージェントが Fast.io で価値を提供するための主要な方法です。

1. org アクション create を実行し、エージェントの請求プランで新しい組織を作成します。エージェントがオーナーになります。エージェントプランのサブスクリプション（無料、50 GB、月 5,000 クレジット）が自動的に作成されます。
2. org アクション create-workspace を org_id と name とともに実行し、プロジェクト領域ごとにワークスペースを作成します。
3. storage アクション create-folder を profile_type: "workspace" とともに実行し、フォルダー構造（テンプレート、成果物、参考資料など）を作成します。
4. 各ワークスペースにファイルをアップロードします（ワークフロー 3 または 4 を参照）。
5. クライアントに成果物を送る場合は type: "send"、ファイルの受け取りや収集には type: "receive" を指定して、share アクション create を実行します。
6. share アクション update を実行し、各共有項目のブランド設定、パスワード、有効期限、アクセスレベルを設定します。
7. org アクション invite-member、または entity_type: "workspace" を指定した member アクション add を実行し、チームメンバーを招待します。
8. org アクション transfer-token-create を org_id とともに実行し、有効期間 72 時間の譲渡トークンを生成します。申請 URL（https://go.fast.io/claim?token=<token>）を人間に送信します。
9. 人間がリンクをクリックして組織を引き継ぎます。人間がオーナーになり、エージェントは管理者アクセスを維持します。人間には無料プランが適用されます。

10. 組織の請求を管理する

1. org アクション billing-plans を実行し、料金と機能を含む利用可能な請求プランをすべて一覧表示します。
2. org アクション billing-create を org_id と、必要に応じて billing_plan とともに実行し、サブスクリプションを作成または更新します。新しいサブスクリプションの場合は、Stripe Setup Intent が作成されます。
3. org アクション billing-details を org_id とともに実行し、現在のサブスクリプションの状態、Stripe の顧客情報、支払い情報を確認します。
4. org アクション limits を org_id とともに実行し、ストレージ、転送、AI トークン、請求期間の情報など、プランの上限に対するクレジット使用状況を確認します。

11. ワークスペースでタスクを管理する

構造化されたタスクリストとタスクで作業を追跡します。

1. workspace アクション enable-workflow を workspace_id とともに実行します。タスク、作業ログ、承認、または ToDo ツールを使用する前に、ワークフロー機能を有効にする必要があります。
2. task アクション create-list を profile_type: "workspace"、profile_id（ワークスペース ID）、および name とともに実行して、タスクリストを作成します。list_id が返されます。
3. task アクション create-task を list_id、title、および任意の description、priority（0～4）、assignee_id、dependencies、node_id、status とともに実行して、リストにタスクを追加します。
4. task アクション list-tasks を list_id とともに実行して、すべてのタスクを表示します。status または assignee で絞り込むこともできます。
5. task アクション change-status を list_id、task_id、および status とともに実行して、タスクの進捗を更新します（pending → in_progress → complete）。
6. task アクション assign-task を list_id、task_id、および assignee_id とともに実行して、チームメンバーに作業を割り当てます。
7. task アクション bulk-status を list_id、task_ids、および status とともに実行して、一度に最大100件のタスクのステータスを一括更新します。

12. エージェントの完全なワークフロー（タスク＋作業ログ＋承認）

作業を計画し、記録しながら実行し、承認によって判断を管理する、エージェント型ワークフローの完全なパターンです。

1. workspace アクション enable-workflow を workspace_id とともに実行して、ワークスペースのワークフロー機能を有効にします。
2. workspace アクション create-note を実行して、プロジェクトの背景、要件、参考資料を含むコンテキストノートを作成します。
3. task アクション create-list を実行して、各作業フェーズ（例：「調査」、「実装」、「レビュー」）のタスクリストを作成します。
4. task アクション create-task を実行して、コンテキストに関連付けられたタスクを追加します。内容が伝わるタイトルを付け、説明には参考ノートの node_id を含めます。
5. task アクション change-status を status: "in_progress" とともに実行して、タスクの開始を記録します。
6. worklog アクション append を entity_type（"task"、"task_list"、または "profile"）、entity_id（対応するエンティティの不透明な ID、または entity_type が "profile" の場合はプロフィールの19桁 ID）、および content とともに実行して、作業中の進捗、決定事項、推論を記録します。時系列に沿った経過を記述します。
7. 優先度の修正が必要な場合は、worklog アクション interject を実行します。ほかの参加者による確認が必要な緊急エントリーが作成されます。
8. 作業を続ける前に、worklog アクション unacknowledged を実行して、未確認の割り込みがないか確認します。
9. worklog アクション acknowledge を実行して、割り込みを確認済みにします。
10. 決定に承認が必要な場合は、approval アクション create を profile_type、profile_id、entity_type（"task"、"node"、または "worklog_entry"）、entity_id、description、および任意の approver_id とともに実行して、正式な承認を申請します。
11. approval アクション resolve を resolve_action: "approve" または "reject" と任意の comment とともに実行します。承認者が申請に対する判断を確定します。
12. task アクション change-status を status: "complete" とともに実行して、タスクの完了を記録します。
13. todo アクション create を実行して、メインのタスクフローに加えて、簡単なチェックリスト項目を追跡します。
14. インテリジェンス機能が有効な場合は、ai アクション chat-create を実行します。AI はノート、タスクの説明、作業ログを横断して検索し、プロジェクトに関する質問に回答できます。

---

7. 主なパターンと注意事項

アクション名の形式

アクション名では、区切り文字としてハイフンを使用します（例：create-session、list-shares）。アンダースコアも使用でき、create_session と create-session は同等です。標準形式はハイフンです。

パラメーターの別名

ワークスペースや共有を操作するツールでは、標準のパラメーター名として profile_type と profile_id を使用します。旧名称の context_type と context_id は、すべてのツールで別名として使用できます。どちらの形式も相互に置き換え可能で、同じ動作になります。

ID 形式

プロフィール ID（組織、ワークスペース、共有、ユーザー）は、19 桁の数字文字列です。ほとんどのエンドポイントでは、識別子としてカスタム名も使用できます。たとえば、ワークスペースのフォルダー名、共有 URL の名前、組織のドメイン名、ユーザーのメールアドレスです。URL パスパラメーターでは、どちらの形式も相互に使用できます。

その他すべての ID（ノード ID、アップロード ID、チャット ID、コメント ID、招待 ID など）は、30 文字の英数字からなる不透明な ID です（ハイフン付きで表示されます）。これらに数値検証を適用しないでください。

ページネーション

エンドポイントに応じて、2 種類のページネーション方式が使用されます。

カーソルベース（ストレージのリストエンドポイント）： sort_by、sort_dir、page_size、cursor を使用します。さらに結果がある場合、レスポンスには next_cursor の値が含まれます。次のページを取得するには、このカーソルを次の呼び出しに渡します。ページサイズは通常 100、250、または 500 です。使用箇所：storage アクション list（profile_type: "workspace" または "share"）。

limit/offset（その他すべてのリストエンドポイント）： limit（1～500、デフォルトは 100）と offset（デフォルトは 0）を使用します。使用箇所：org アクション list、members、list-workspaces、list-shares、billing-members、discover-all、discover-external、share アクション list、members、workspace アクション list、members、list-shares、user アクション list-shares、storage アクション search。

バイナリのダウンロード

MCP ツールはダウンロード URL を返します。バイナリコンテンツを直接ストリーミングすることはありません。download アクション file-url（profile_type: "workspace" または "share"）と download アクション quickshare-details は、/requestread/ エンドポイントを呼び出して一時トークンを取得し、完全なダウンロード URL を構築します。エージェントは、これらの URL をユーザーに返すか、ダウンロードユーティリティに渡してください。

download アクション zip-url（ワークスペースと共有）は、必要な Authorization ヘッダー値とともに URL を返します。

アップロード

ほとんどのファイルアップロードは、正規の大容量ファイル用経路である POST /blob サイドカーエンドポイントを経由します。MCP トランスポートの制限を回避でき、base64 によるオーバーヘッドがなく、最大 100 MB までのあらゆるサイズのテキストファイルとバイナリファイルに対応します。（インラインの代替手段：小さなテキストには content、エージェントが /blob にアクセスできない場合の小さなバイナリには content_base64 を使用します。どちらも MCP トランスポートメッセージのサイズ制限を受けます。）

URL からアクセスできるファイルには、web-import を優先してください。 ファイルがいずれかの URL（HTTP/HTTPS、Google Drive、OneDrive、Box、Dropbox）からアクセスできる場合は、分割アップロードではなく upload アクション web-import を使用してください。これは 1 回のツール呼び出しで完了し、分割もセッション管理も不要です。

アップロード制限 API

upload アクション limits を呼び出すと、プランのアップロード制限を取得できます。任意のパラメーター：action_context（"create" または "update"）、instance_id（対象のワークスペース／共有 ID）、file_id（更新の場合）、org（組織 ID）。

レスポンスフィールド：

フィールド	説明	Free/Agent	Pro	Business
chunk_size	チャンクの最大サイズ	100 MB	100 MB	100 MB
size	アップロードごとの最大ファイルサイズ	1 GB	25 GB	50 GB
chunks	セッションあたりのチャンクの最大数	35	550	550
sessions	同時セッションの最大数	150	7,500	7,500
sessions_size_max	全セッションの合計最大サイズ	6.6 GB	160 GB	320 GB

注： API が返すのは最大制限です。**最小チャンクサイズ（1 MB）**は固定のシステム定数で、このエンドポイントからは返されません。すべてのプランに等しく適用されます。

アップロード方法の選択

単一ファイルのアップロードがデフォルトの方法です。バッチは「複数の小さなファイルを一度に」アップロードする場合に限った特殊な方法です。それ以外の場合は、単一ファイル用の方法を使用してください。

ファイルの種類	サイズが判明しているか	推奨される方法
URL があるファイル	該当なし	upload アクション web-import（1 ステップ）
URL のないテキストまたはバイナリ	はい	POST /blob サイドカー → blob_id を指定して chunk → finalize
URL のない生成コンテンツ／パイプされたコンテンツ	いいえ	POST /blob → blob_id を指定して upload アクション stream-upload（1 回の呼び出しでセッションを作成し、バイト列をストリーム送信して、自動的に確定します）
特殊なケース： 一度に複数の小さなファイル（各 ≤4 MB）	はい	ファイルごとに POST /blob → files[] マニフェストを指定して upload アクション batch（1 回の往復で最大 200 ファイル。単一ファイルのアップロードには使用せず、上記の単一ファイル用の方法を使用してください）

バッチアップロード — 多数の小さなファイルを1回の往復でアップロード

複数の小さなファイル（AI の出力、レポート一式、エクスポートした CSV、領収書など）をアップロードする場合、upload アクション batch ではマニフェスト全体を1つのリクエストで送信します。これにより、ファイルごとのアップロードレート制限枠を N 件分消費せずに済み、小さなファイルを処理する場合の実時間を通常は桁違いに短縮できます。

ハードリミット（リクエスト送信前にクライアント側で適用されます）：

• 1 回の呼び出しにつき ≤ 200 ファイル。 これを超える数を指定すると、分割を求めるエラーが返されます。
• ファイルごとに ≤ 4 MB。 4 MB を超えるファイルがあると、チャンク方式（create-session → chunk → finalize）を案内するエラーが返され、バッチ全体が拒否されます。バッチアップロードとチャンク方式のアップロードは混在できません。
• 解決後のバイト数の合計が ≤ 100 MB。 マルチパートの生データを対象とし、base64 による増加分は含みません。（マルチパートのフレーミングによるオーバーヘッドはわずかですがゼロではありません。サーバーはフレーミング後のボディサイズを測定するため、生データがちょうど 100 MB になるバッチでも拒否されることがあります。大きなバッチでは数百 KB の余裕を持たせてください。）
• 認証が必要です。 匿名の呼び出しは HTTP 401（コード 10011）で拒否されます。認証なしで公開受信／公開交換の共有アップロードを行う場合は、代わりに単一ファイル用の create-session フローを使用してください。
• relative_path の形式。 末尾にスラッシュが必要です（ない場合は自動的に正規化されます）。先頭にスラッシュは付けられません。. または .. のセグメントも使用できません。違反はエントリーごとのエラーとしてクライアント側で拒否されるため、バッチ全体を失わずに該当するファイルを修正できます。

一般的な流れ：

1. ファイルごとに、ファイルのバイト列を指定して POST /blob を実行します（下記の blob セクションを参照するか、upload アクション blob-info を呼び出します）。返された blob_id の値を収集します。
2. 次の値を指定して upload アクション batch を呼び出します。
   • profile_type と profile_id — 対象のワークスペースまたは共有
   • folder_id（任意）— 対象フォルダーの OpaqueId または "root"（バッチ単位で指定され、この呼び出しのすべてのファイルがこのフォルダーに格納されます）。インスタンスのルートを対象とする場合は省略します。ファイルごとに格納先を変える場合は、別々のバッチを実行してください。そのために relative_path を不適切に使用しないでください。
   • files[] — ファイルごとに1つのエントリーを指定します。{filename, blob_id}、{filename, content}（空でないインラインテキスト）、または {filename, content_base64}（小さなバイナリ。サーバー側でデコードされ、空白は自動的に除去されます）。filename は 1～255 文字です（サーバーは拡張子を保持したまま、100 文字を超える名前を切り詰めます）。エントリーごとに relative_path を指定することもできます（1～8192 文字。末尾にスラッシュが必要で、自動的に正規化されます。先頭の / および .／.. のセグメントは使用できません）。指定すると、folder_id の下にサブフォルダーが作成されます。エントリーごとに hash（16 進文字列）と hash_algo（md5、sha1、sha256、sha384 のいずれか）を指定することもできます。呼び出し元が指定したダイジェストはそのまま転送され、サーバーが検証します。デフォルトでは、ハッシュが指定されていないエントリーに対し、ツールがクライアント側で SHA-256 を計算します。計算をスキップするには、呼び出しで include_hash: false を設定してください。
   • creator（任意）— レスポンスにそのまま返されます（1～150 文字の英数字またはハイフン）。 レスポンス形式：

• batch_id、count_total、count_succeeded、count_errored、partial（成功したエントリとエラーになったエントリがどちらもある場合は true）、all_failed（すべてのエントリがエラーになった場合は true）、creator（そのまま返されます）。
• results[] — ファイルごとに 1 つのエントリが含まれ、index、filename、status（"ok" または "error"）を持ちます。ok の場合は upload_id（監査の照合に使うハンドル）と node_id（null の場合があります。以下を参照）が含まれます。error の場合は error_code と error_message が含まれます。
• errors[] — 利便性のため、エラーになったエントリのみを事前に抽出したビューです。

⚠️ 重要な意味上の注意点が 3 つあります：

1. 成功時でも node_id は null になることがあります。 非同期でストレージを確定するワークスペースでは、"status": "ok" と "node_id": null が返されます。ストレージノードは後からアセンブルワーカーによって割り当てられます。これは失敗ではなく、成功です。 null の node_id をエラーとして扱わないでください。最終的なノード ID が必要な場合は、少し待ってから対象フォルダーに対して storage アクションの list を呼び出すか、アップロードイベントをサブスクライブしてください。

2. 部分的な成功は通常の動作です。 エントリの一部でファイルごとの検証エラー（ハッシュ不一致、許可されていない拡張子など）が発生した場合、HTTP 200 と count_errored > 0 が返されます。バッチ全体を再試行しないでください。 results[] を確認し、ステータスごとに分けて、error_code が再試行可能なエントリだけを再試行してください。

3. すべて失敗した場合も HTTP 200 が返されます。 すべてのエントリでエラーが発生すると、ツールはレスポンスに all_failed: true を設定します。アップロードされたものはありません。何が問題だったか（ハッシュ不一致、拡張子のブロックなど）を確認するには、results[]／errors[] を調べ、入力を修正してから再送信してください。監査照会のため、batch_id は 1 時間保持されます。

レート制限： バッチエンドポイントは、ファイルごとの /upload/ バケットとは独立したバケットでレート制限されるため、一括アップロードで単一ファイル用の枠を消費することはありません。HTTP 429 の場合、ツールは x-ve-limit-expires ヘッダー（UTC の日時文字列。例："2026-04-24 23:49:04 UTC"）と、残りの x-ve-limit-avail／x-ve-limit-max クォータをエラーメッセージに表示します。その日時まで待ってから再試行してください。ツールはサーバーから送信されたエラーコードをそのまま報告します。

バッチ全体の拒否（HTTP 4xx で results[] がない場合）は、入力検証エラーです。folder_id が不正、instance_id がない、本文が大きすぎる、ファイル数が 200 を超えている、といったケースが該当します。再試行する前に入力を修正してください。

POST /blob エンドポイント — 標準のアップロード方法

JSON-RPC パイプの外部で生データを受け付けるサイドカー HTTP エンドポイントです。MCP トランスポートの制限を完全に回避できます。Base64 エンコードやパラメーターサイズの制約はありません。テキストファイルとバイナリファイルのどちらにも対応し、ファイルサイズの制限はありません。

エンドポイント URL とセッション ID の取得： create-session のレスポンスには、エンドポイント URL、セッション ID、すぐに使える curl コマンドを含む blob_upload オブジェクトが自動的に含まれます。blob-info の呼び出しは別途必要ありません。upload アクションの blob-info を個別に呼び出すこともできます。

チャンク化フロー（サイズが既知の場合）：

1. profile_type、profile_id、parent_node_id、filename、filesize を指定して、upload アクションの create-session を呼び出します。レスポンスには blob_upload.curl_command が含まれます。
2. curl（または任意の HTTP クライアント）を使用して、ファイルデータと blob_upload オブジェクト内のヘッダーを指定し、POST /blob を実行します。{ "blob_id": "<uuid>", "size": <bytes> }（HTTP 201）が返されます。
3. upload_id、chunk_number、blob_id: "<blob_id>" を指定して、upload アクションの chunk を呼び出します。
4. 追加のチャンクがある場合は（大きなファイルを分割している場合）、手順 2～3 を繰り返し、その後 upload アクションの finalize を呼び出します。 ストリームフロー（サイズ不明）—推奨される単一呼び出しの方法：
5. ファイルデータを指定して POST /blob を呼び出します（エンドポイントと curl コマンドについては、blob-info または任意の create-session レスポンスの blob_upload オブジェクトを参照してください）。{ "blob_id": "<uuid>", "size": <bytes> } が返されます。
6. profile_type、profile_id、parent_node_id、filename、blob_id: "<blob_id>" を指定して、upload の stream-upload アクションを呼び出します。必要に応じて max_size（以下のガイダンスを参照）、hash、hash_algo も指定できます。
7. 完了です。stream-upload はストリームセッションを作成し、バイトデータをストリーミングして、1 回の呼び出しで自動的にファイナライズします。ストリームが失敗した場合、未完了のセッションは自動的にキャンセルされます。

ストリームフロー（明示的な 2 ステップ — 呼び出しの間にセッション ID が必要な場合）：

1. profile_type、profile_id、parent_node_id、filename、stream=true を指定して、upload の create-session アクションを呼び出します。filesize は省略可能です。上限として max_size を指定するか（以下のガイダンスを参照）、プランのデフォルト値を使う場合は省略します。
2. ファイルデータを指定して POST /blob を呼び出します。{ "blob_id": "<uuid>", "size": <bytes> } が返されます。
3. upload_id と blob_id: "<blob_id>" を指定して、upload の stream アクションを呼び出します。検証用に hash と hash_algo を指定することもできます。
4. 完了です。ストリームは自動的にファイナライズされます。別途 finalize を呼び出す必要はありません。

max_size のガイダンス — 必ず多めに見積もり、少なく見積もらないでください。 max_size はストリーム本文の上限です。実際のバイト数がこれを超えると、転送の途中でアップロードが中断され、ファイルはエラーになります。大きめに設定しても問題ありません。最も安全なデフォルト設定は、max_size を省略することです。サーバーがプランのファイルサイズ上限を使用します。 注意：MCP 経由のストリーミングアップロードも POST /blob サイドカーによる制限（blob ごとに最大 100 MB）を受けます。100 MB に近いファイルや 100 MB を超えるファイルの場合は、チャンク分割フロー（create-session → chunk → finalize）に切り替え、まず upload の limits アクションを呼び出して、プランの最大ファイルサイズを確認してください。

ストリームの制約： ストリームセッションでは chunk／finalize は使用できません（406 で拒否されます）。チャンク分割セッションでは stream は使用できません（406 で拒否されます）。ストリームは 1 回限りです。同じセッションに対して 2 回ストリーミングすることはできません。

既存ファイルの上書き（削除してから再アップロードしないでください）。 同じ親フォルダーへの同名アップロードでは、既存ノードをその場で上書きします。node_id は維持され、以前の内容はバージョンエントリになります。ファイルのバイトデータを更新するには、既存ファイルと同じ parent_node_id と filename を指定して create-session を呼び出し、その後 POST /blob → chunk／stream → finalize の順に実行します。ファイル名が変更されている可能性がある場合や、親フォルダーの再解決を避けたい場合に確実に上書きするには、代わりに create-session で target_node_id を指定してください（サーバーは action=update と file_id=<target_node_id> を使用します。parent_node_id は無視され、filename は省略できるため、置き換え時に名前を変更できます）。同名で上書きした後は、storage の version-list アクション（バージョンの一覧表示）と version-restore アクション（version_id を指定して復元）を使って、以前の内容を復元できます。node_id はバージョン間で維持されます。詳しい例については、セクション 4 のファイルの上書きを参照してください。

Blob の制約：

• Blob は 5 minutes 後に期限切れになります。速やかにステージングして使用してください。
• 各 Blob は初回使用時に消費（削除）され、再利用できません。
• Blob の最大サイズ：100 MB。
• SSE トランスポートのクライアントでは、/blob URL に ?transport=sse を追加する必要があります。

イベントフィルタリングのリファレンス

event ツールの search アクションと summarize アクションでは、結果を絞り込むために category、subcategory、event パラメーターを指定できます。すべてのイベントを調べる代わりに、これらを使って特定のアクティビティを対象にしてください。

イベントカテゴリ

カテゴリ	対象
user	アカウントの作成、更新、削除、アバターの変更
org	組織のライフサイクル、設定、移管
workspace	ワークスペースの作成、更新、アーカイブ、ファイル操作
share	共有のライフサイクル、設定、ファイル操作
node	ファイルおよびフォルダー操作（プロファイルをまたぐ操作）
ai	AI チャット、要約、RAG インデックス作成
invitation	メンバーへの招待の送信、承諾、辞退
billing	サブスクリプション、トライアル、クレジットの使用
domain	カスタムドメインの設定
apps	アプリケーションとの連携
metadata	メタデータの抽出、テンプレート、キーと値の更新

イベントのサブカテゴリ

サブカテゴリ	対象
storage	ファイル／フォルダーの追加、移動、コピー、削除、復元、ダウンロード
comments	コメントの作成、更新、削除、メンション、返信、リアクション
members	組織、ワークスペース、共有へのメンバーの追加／削除
lifecycle	プロファイルの作成、更新、削除、アーカイブ
settings	設定と環境設定の変更
security	セキュリティ関連のイベント（2FA、パスワード）
authentication	ログイン、SSO、セッションのイベント
ai	AI による処理、チャット、インデックス作成
invitations	招待の管理
billing	サブスクリプションと支払いのイベント
assets	アバター／アセットの更新
upload	アップロードセッションの管理
transfer	プロファイル間のファイル転送
quickshare	クイック共有の操作
metadata	メタデータの操作

一般的なイベント名

ファイル操作（ワークスペース）： workspace_storage_file_added、workspace_storage_file_deleted、workspace_storage_file_moved、workspace_storage_file_copied、workspace_storage_file_updated、workspace_storage_file_restored、workspace_storage_folder_created、workspace_storage_folder_deleted、workspace_storage_folder_moved、workspace_storage_download_token_created、workspace_storage_zip_downloaded、workspace_storage_file_version_restored、workspace_storage_link_added

ファイル操作（共有）： share_storage_file_added、share_storage_file_deleted、share_storage_file_moved、share_storage_file_copied、share_storage_file_updated、share_storage_file_restored、share_storage_folder_created、share_storage_folder_deleted、share_storage_folder_moved、share_storage_download_token_created、share_storage_zip_downloaded

コメント： comment_created、comment_updated、comment_deleted、comment_mentioned、comment_replied、comment_reaction

メンバーシップ： added_member_to_org、added_member_to_workspace、added_member_to_share、removed_member_from_org、removed_member_from_workspace、removed_member_from_share、membership_updated

ワークスペースのライフサイクル： workspace_created、workspace_updated、workspace_deleted、workspace_archived、workspace_unarchived

共有のライフサイクル： share_created、share_updated、share_deleted、share_archived、share_unarchived、share_imported_to_workspace

AI： ai_chat_created、ai_chat_new_message、ai_chat_updated、ai_chat_deleted、ai_chat_published、node_ai_summary_created、workspace_ai_share_created

メタデータ： metadata_kv_update、metadata_kv_delete、metadata_kv_extract、metadata_template_update、metadata_template_delete、metadata_template_settings_update、metadata_view_update、metadata_view_delete、metadata_template_select

クイック共有： workspace_quickshare_created、workspace_quickshare_updated、workspace_quickshare_deleted、workspace_quickshare_file_downloaded、workspace_quickshare_file_previewed

招待： invitation_email_sent、invitation_accepted、invitation_declined

ユーザー： user_created、user_updated、user_deleted、user_email_reset、user_asset_updated

組織： org_created、org_updated、org_closed、org_transfer_token_created、org_transfer_completed

請求： subscription_created、subscription_cancelled、billing_free_trial_ended

クエリの例

• ワークスペース内の最近のコメント： workspace_id と subcategory: "comments" を指定して、event アクション search を実行します
• 共有にアップロードされたファイル： share_id と event: "share_storage_file_added" を指定して、event アクション search を実行します
• 組織全体のすべてのメンバー変更： org_id と subcategory: "members" を指定して、event アクション search を実行します
• ワークスペース内のAIアクティビティ： workspace_id と category: "ai" を指定して、event アクション search を実行します
• 共有からファイルをダウンロードしたユーザー： share_id と event: "share_storage_download_token_created" を指定して、event アクション search を実行します

アクティビティのポーリング

変更を検出する3つの方法を、推奨度の高い順に示します。

1. event アクション activity-poll — サーバーは最大95秒間接続を保持し、変更があるとすぐに応答します。次回のポーリング用に、アクティビティキー（例：ai_chat:{chatId}、storage、members）とlastactivityタイムスタンプを返します。AIチャットの完了を含め、「何かが起きるまで待つ」あらゆる場面で使用してください。
2. WebSocket — リアルタイムのプッシュイベント用です。ライブUIに最適です。
3. event アクション activity-list — 必要に応じて最近のアクティビティイベントを取得します。継続的な監視ではなく、一度限りのスナップショットが必要な場合に使用してください。

重要な理由： 詳細エンドポイント（ai アクション message-readなど）を短い間隔で繰り返しポーリングしないでください。代わりに、event アクション activity-pollを使って変更を検出してから、詳細を一度だけ取得してください。

AI メッセージの完了

ai アクション message-read（profile_type: "workspace" または "share" を指定）は、組み込みのポーリング（最大15回、2秒間隔）を実行します。その時間内に応答の処理が完了しない場合は、read アクションを繰り返し呼び出すのではなく、workspace または share の ID を指定して event アクション activity-poll を使用してください。

1. entity_id に workspace/share の ID を設定して、event アクション activity-poll を呼び出します。
2. 応答に自分のチャットと一致する ai_chat:{chatId} キーが含まれたら、ai アクション message-read を1回呼び出して、完了した応答を取得します。

アクティビティのポーリングワークフロー

1. API 呼び出し（例：ai アクション chat-create）を行い、応答内の server_date フィールドを記録します。
2. entity_id（workspace または share の ID）を指定し、lastactivity に server_date の値を設定して、event アクション activity-poll を呼び出します。
3. サーバーは接続を保持します。変更があると（または待機時間が終了すると）、アクティビティキーを返します。
4. キーを確認して何が変更されたかを判断し、該当する詳細（例：ai アクション message-read、storage アクション list）を取得します。
5. 次のポーリング呼び出しでは、ポーリング応答の新しい lastactivity 値（または最新の server_date）を使用します。必要に応じて繰り返します。

ゴミ箱、削除、完全削除

• storage アクション delete（profile_type: "workspace" または "share" を指定）は、項目をゴミ箱に移動します。復元できます。
• storage アクション restore は、項目をゴミ箱から復元します。
• storage アクション purge は、項目をゴミ箱から完全かつ不可逆的に削除します。

purge 操作を呼び出す前に、必ずユーザーに確認してください。

ノードの種類

ストレージノードには、ファイル、フォルダー、ノート、リンクがあります。種類はストレージ詳細の応答に示されます。ノートは、workspace アクション create-note で作成し、workspace アクション read-note で読み取り、workspace アクション update-note で更新する、Markdown コンテンツを含むノードです（独立したノードタイプであり、type: "note" です。どちらも Markdown テキストを保持できますが、type: "file" ではありません）。リンクは、storage アクション add-link で作成する共有参照ノードです。

テキストコンテンツと改行

すべてのテキストコンテンツ（ノート、コメント、作業ログ、ファイルアップロード、説明）では、改行に Unix 形式のラインフィード（\n、U+000A）を使用する必要があります。フロントエンドは保存前にすべての改行コードを \n に正規化します。Windows 形式の \r\n（CRLF）と旧 Mac 形式の \r（CR）は自動的に変換されます。コンテンツの比較や表示で不一致が起きないよう、エージェントは \n のみを使用してください。

エンコーディング規則：

• 改行： \n（U+000A）を使用してください。\r\n や \r のみを送信しないでください。
• 使用できる制御文字： サーバー側のサニタイズ後に残るのは、\t（U+0009）、\n（U+000A）、\r（U+000D）のみです。それ以外の Unicode 制御文字（\p{C}）はすべて削除されます。
• Markdown の空行： 段落を区切るには、連続する2つの \n 文字（\n\n）を使用してください。行のプレースホルダーとして、ノーブレークスペース（U+00A0）やその他の空白文字を使用しないでください。
• 末尾の改行： コンテンツの末尾には \n があってもなくてもかまいません。どちらの形式も有効なため、どちらかに決めつけないでください。

これは、workspace アクション create-note と update-note、upload アクション chunk（content パラメーターを使用）、comment アクション add、worklog アクション append と interject、および自由形式のテキストや Markdown コンテンツを受け付けるその他すべてのツールに適用されます。

エラーパターン

API 呼び出しに失敗すると、code（一意の数値エラー ID）と text（人が読める説明）の 2 つのフィールドを持つエラーがスローされます。ツールはこれらを MCP 応答のエラーテキストとして表示します。一般的な HTTP ステータスコードには、401（認証されていない）、403（アクセス禁止）、404（見つからない）、429（レート制限）が含まれます。

403 とスコープ付きキー： スコープ付き API キー（またはスコープ付き OAuth トークン）を使用している場合、403 エラーは多くの場合、ロールや権限の問題ではなく、対象のリソースがキーに付与されたスコープの範囲外であることを意味します。auth アクションの status を確認し、scopes_detail を見て、キーでアクセスできるエンティティを確認してください。スコープ付きキーでアクセスできるのは、付与された特定の組織、ワークスペース、共有のみです。それ以外のすべてのエンドポイントは 403 を返します。

読み取り専用スコープとツールのフィルタリング： 読み取り専用のスコープ付きキー（すべてのエンティティの付与が :r アクセスモード）で認証すると、サーバーは各ツールを自動的にフィルタリングし、読み取りアクションのみを公開します。書き込みアクションは、アクションの enum、説明、アノテーションから削除されます（アノテーションは readOnlyHint=true、destructiveHint=false に変更されます）。読み取り専用セッションで書き込みアクションを試みると、403 ではなくスキーマ検証エラーが返されます。読み書き可能なキー（またはスコープなしのキー）で再認証すると、すべてのアクションが再び利用できるようになります。

セッション状態

認証トークン、ユーザー ID、メールアドレス、トークンの有効期限、リフレッシュトークンはサーバーセッションに永続化されます。ツール呼び出しの間でトークンを受け渡す必要はありません。同じ MCP 接続内の複数のツール呼び出しにわたってセッションは維持されます。OAuth セッションは自動的にサイレント更新されます。内部アラームによって有効期限前にアクセストークンが更新されるため、ユーザーの操作なしでセッションを最長 30 日間（リフレッシュトークンの有効期間）維持できます。

人が利用する URL

MCP ツールは API 経由でデータを管理しますが、人はウェブブラウザーから Fast.io にアクセスします。ツールの応答にある web_url フィールドを必ず使用してください。 リソースにすぐアクセスできる、クリック可能な URL です。ワークスペース、共有、ファイル、ノート、転送を作成または参照する際は、必ず応答に含めてください。人は API 応答を直接見ることができません。提供する URL が、コンテンツにアクセスするための手段です。以下の URL パターンを使用するのは、web_url がない場合（例：共有コンテキストのストレージ操作）に限ります。

web_url フィールドの自動付与。 エンティティを返すすべてのツール応答には、リソースにすぐアクセスできる、人にとって分かりやすい URL である web_url フィールドが含まれます。URL を手動で作成してはいけません。必ずツールの応答にある web_url フィールドを使用してください。 次に示すものに含まれます：org list/details/create/update/public-details/discover-*、org list-workspaces/list-shares、workspace list/details/update/available/list-shares、share list/details/create/update/public-details/available、storage list/details/search/trash-list/copy/move/rename/restore/add-file/create-folder/version-list/version-restore/preview-url/preview-transform、quickshare create/get/list、upload finalize、download file-url/quickshare-details、AI chat-create/chat-details/chat-list、transfer-token create/list、notes create/update。以下の URL パターンを使用するのは、web_url がない場合（例：共有コンテキストのストレージ操作）に限ります。

Organization の domain 値はサブドメインになります。「acme」→ https://acme.fast.io/。ベースドメイン go.fast.io は、組織コンテキストを必要としない公開ルートを処理します。

認証済みリンク（ログインが必要）

人間が必要とするもの	URL パターン
ワークスペースのルート	https://{domain}.fast.io/workspace/{folder_name}/storage/root
特定のフォルダー	https://{domain}.fast.io/workspace/{folder_name}/storage/{node_id}
ファイルのプレビュー	https://{domain}.fast.io/workspace/{folder_name}/preview/{node_id}
特定のコメントが付いたファイル	https://{domain}.fast.io/workspace/{folder_name}/preview/{node_id}?comment={comment_id}
動画／音声の指定時間のファイル	https://{domain}.fast.io/workspace/{folder_name}/preview/{node_id}?t={seconds}
指定ページの PDF ファイル	https://{domain}.fast.io/workspace/{folder_name}/preview/{node_id}?p={page_num}
ワークスペース内の AI チャット	https://{domain}.fast.io/workspace/{folder_name}/storage/root?chat={chat_id}
ワークスペース内のノート	https://{domain}.fast.io/workspace/{folder_name}/storage/root?note={note_id}
ノートのプレビュー	https://{domain}.fast.io/workspace/{folder_name}/preview/{note_id}
ワークスペースを閲覧	https://{domain}.fast.io/browse-workspaces
共有設定を編集	https://{domain}.fast.io/workspace/{folder_name}/share/{custom_name}
組織の設定	https://{domain}.fast.io/settings
請求	https://{domain}.fast.io/settings/billing

公開リンク（ログイン不要）

人間が必要とするもの	URL パターン
公開共有	https://go.fast.io/shared/{custom_name}/{title-slug}
組織のブランド付き共有	https://{domain}.fast.io/shared/{custom_name}/{title-slug}
共有内のファイル	https://go.fast.io/shared/{custom_name}/{title-slug}/preview/{node_id}
コメント付きの共有内ファイル	https://go.fast.io/shared/{custom_name}/{title-slug}/preview/{node_id}?comment={comment_id}
QuickShare	https://go.fast.io/quickshare/{quickshare_id}
組織の移管を申請	https://go.fast.io/claim?token={transfer_token}
オンボーディング	https://go.fast.io/onboarding または https://go.fast.io/onboarding?orgId={org_id}&orgDomain={domain}

値の取得元

値	API ソース
domain	org の create または details アクションのレスポンス
folder_name	org の create-workspace または workspace の details アクションのレスポンス
node_id	storage の list、create-folder、または add-file アクションのレスポンス
custom_name	share の create または details アクションのレスポンス（{title-slug} は見た目上のもので、共有は custom_name のみで解決されます）
quickshare_id	workspace の quickshare-create アクションのレスポンス
transfer_token	org の transfer-token-create アクションのレスポンス
chat_id	ai の chat-create または chat-list アクションのレスポンス
note_id	workspace の create-note または storage の list アクションのレスポンス（ノードの不透明な ID）
comment_id	comment の add または list アクションのレスポンス
org_id	org の create または list アクションのレスポンス

次の場合は、必ず人間に URL を提示してください。

• ワークスペースを作成しましたか？ 回答にワークスペースの URL を含めてください。例：https://acme.fast.io/workspace/q4-reports/storage/root
• 共有を作成または設定しましたか？ 共有 URL を含めてください。例：https://go.fast.io/shared/q4-financials/Q4-Financial-Report -- これは人間（またはその共有先）が開くブランド付きページです。
• 移管トークンを生成しましたか？ 申請 URL を含めてください。例：https://go.fast.io/claim?token=abc123 -- これは人間が所有権を申請する唯一の方法です。
• ファイルをアップロードしたり、フォルダーを作成したりしましたか？ 作成した内容を人間が確認できるよう、該当フォルダーを示すワークスペース URL を含めてください。
• 人間から「これはどこで見られますか？」と尋ねられましたか？ すでに取得している API レスポンスのデータから URL を組み立てて提示してください。

重要： domain は組織のドメイン文字列（例：acme）であり、数値の組織 ID ではありません。folder_name はワークスペースのフォルダー名文字列（例：q4-reports）であり、数値のワークスペース ID ではありません。どちらも、それぞれの API ツールから返されます。

レスポンスヒント（_next、_warnings、_recovery）

ワークフローで重要なツールのレスポンスには、推奨される次のアクションを正確なツール名とアクション名で示す短い配列、_next フィールドが含まれます。次に何をすべきか推測するのではなく、これらのヒントに従ってワークフローを進めてください。例：

{
  "workspace_id": "...",
  "web_url": "https://acme.fast.io/workspace/q4-reports/storage/root",
  "_next": [
    "Upload files: upload action create-session + blob or web-import",
    "Create a share: share action create",
    "Query with AI: ai action chat-create"
  ]
}

破壊的、取り消し不能、または問題が発生する可能性のあるアクションでは、_warnings が表示されます。先に進む前に、必ず警告を読んでください。警告には、永続的な影響や重要な注意事項が示されています。_warnings が付くアクション：storage purge、storage bulk copy/move/delete/restore（部分的な失敗）、workspace details（intelligence=false）、workspace update（intelligence=false）、workspace archive/delete、org close、org billing-create、share delete、share archive、share update（type change）、ai chat-delete、download file-url（トークンの有効期限切れ）、download zip-url（認証が必要）、org transfer-token-create。

エラーレスポンス（isError: true の場合）には、_recovery ヒントが表示されます。これらのヒントは、HTTP ステータスコードとエラーメッセージのパターンマッチングに基づいて、復旧アクションを提示します。エラーメッセージには、失敗した操作を特定しやすくするため、アクションのコンテキスト（例：「during: org create」）も含まれます。

HTTP ステータス	復旧方法
400	必須パラメーターと ID の形式を確認してください
401	再認証してください：auth アクションの signin または set-api-key を実行します。エラーに「Session expired」と表示される場合、以前のセッションがタイムアウトしています。続行するには再認証してください。「Not authenticated」と表示される場合、まだセッションがありません。
402	クレジットが不足しています。残高を確認してください：org アクションの limits を実行します
403	権限がありません。ロールを確認してください：org アクションの details を実行します
404	リソースが見つかりません。ID を確認し、list アクションを使って有効な ID を調べてください
409	競合しています。リソースはすでに存在する可能性があります
413	リクエストが大きすぎます。ファイルまたはチャンクのサイズを小さくしてください
422	検証エラーです。フィールドの形式と制約を確認してください
429	レート制限に達しました。2〜4 秒待ってから、指数バックオフを使用して再試行してください
500/503	サーバーエラーです。2〜5 秒後に再試行してください

パターンに基づく復旧：エラーメッセージは、一般的なパターン（例：「email not verified」、「workspace not found」、「intelligence disabled」）とも照合されます。HTTP ステータスが汎用的な場合でも、具体的な復旧手順を提示できます。

ai_capabilities は、ワークスペース詳細のレスポンスに含まれます。ワークスペースの intelligence 設定に基づいて、利用可能な AI モードを示します。

• Intelligence が ON：files_scope、folders_scope、files_attach（インデックス化されたドキュメント検索を含むフル RAG）
• Intelligence が OFF：files_attach のみ（最大 20 ファイル、200 MB、RAG インデックス化なし）

ファイルに AI 処理状態がある場合、ストレージの list および search のレスポンスに _ai_state_legend が含まれます。状態：indexed（ベクトルインデックス化済み、RAG 検索可能 — intelligence ON）、ready（要約が利用可能で添付可能ですが、ベクトルインデックス化されていません — intelligence OFF）、pending（キュー待ち）、inprogress（処理中）、disabled（AI 処理なし）、failed（再アップロードが必要）。ai.attach のブール値について説明する _attach_field も含まれます。files_attach を使用する前に、このフラグを確認してください。

_context は、特定のレスポンスにコンテキストメタデータを提供します。現在は、アンカーが使われるコメント追加で使用され、画像領域、動画／音声のタイムスタンプ、PDF ページに必要な形式を示す anchor_formats を提供します。

すべてのツールアクションに _next ヒントが含まれるようになりました。 ツールが正常に応答するたびに、コンテキストに応じた次のステップの提案が含まれます。主なワークフローの移行先：auth → org list/create、org create → workspace create、workspace create → upload/share/AI、upload → AI chat/comment/download、share create → add files/members、AI chat create → message read。ヒントには、現在のレスポンスに含まれる正確なツール名、アクション名、関連する ID が記載されています。

ツールのアノテーション： ツールには MCP アノテーションのヒントが含まれます。readOnlyHint、destructiveHint、idempotentHint（download、event）、openWorldHint（org、user、workspace、share、storage）によって、クライアントはドキュメントを参照せずにツールの動作を理解できます。 破壊的な操作を示すタグ： 不可逆な操作（削除、完全消去、クローズなど）を実行するアクションでは、ツール一覧の説明行の末尾に [DESTRUCTIVE] が付加されます。これは destructiveHint アノテーションを補完するテキストレベルのシグナルです。安全な書き込みと、取り消せない操作を区別するために使用してください。

リソースの補完と一覧表示： ワークスペースと共有のダウンロード用リソーステンプレートは、動的な一覧表示（resources/list）とタブ補完（completion/complete）の両方をサポートします。動的な一覧表示では、クライアントのリソースピッカーに、すべてのワークスペースと共有にあるルートレベルのファイルが表示されます。タブ補完では、入力中に有効なワークスペース ID と共有 ID が候補として表示されます。

認証不要のツール

以下のアクションはセッションなしで動作します：auth アクションの signin、signup、set-api-key、pkce-login、email-check、password-reset-request、password-reset、および download アクションの quickshare-details。

レスポンス形式

すべてのツールのレスポンスは GitHub Flavored Markdown（CommonMark ＋ テーブル）です。JSON エンベロープはありません。

ほとんどのツールでは、API の JSON エンベロープを同じルールでクライアント側から Markdown にレンダリングします。このルールは、プラットフォームの ?output=markdown 修飾子と同じです。そのため、パススルー形式とレンダリング済みのレスポンスは同じ見た目になります。

一部の一覧／アクティビティアクションでは、トークンコストと詳細度を調整するために detail パラメーターも使用できます。

ツール	アクション	detail を受け付ける	デフォルト
event	search	terse | standard | full	standard
event	activity-list	terse | standard | full	standard
event	activity-poll	terse | standard | full	terse
comment	list	terse | standard | full	standard

各レベルで返される内容（累積形式。各レベルは前のレベルに内容を追加します）：

• terse：識別子、主要なラベル、タイムスタンプのみを返します。移動やカーソルの更新に必要な情報が得られます。
• standard：terse の内容に加え、一覧表示で一般的に必要となる操作上のコンテキスト（実行者、説明、フラグ、件数）を返します。
• full：standard の内容に加え、詳細なフィールド（完全な概要、メタデータ、スキーマの詳細）を返します。detail を省略した場合と同じです。

storage/share/org/workspace の一覧表示／検索操作（およびファイルやエンティティの一覧を返すその他のアクション）もローカルでレンダリングされた Markdown を返しますが、現時点では detail パラメーターを受け付けません。これらのエンドポイントはデフォルトで full 形式を返します。必要なフィルタリングは、他のアクションパラメーター（例：search クエリ、limit／offset）で指定してください。

汎用の Markdown 出力とは別に、tasks/todo/approval/worklog ツールは引き続き format: 'md' を受け付けます。これを指定すると、チェックボックス付きリスト、タイムライン、ステータステーブルなど、用途に特化したレンダラーが使用されます。これはここで説明するエンベロープ形式の Markdown とは異なります。どちらも Markdown を生成しますが、形式が異なります。

---

8. MCP Apps（インタラクティブ UI ウィジェット）

Fast.io MCP Server には、エージェントとの会話内にリッチな UI を直接表示する、インタラクティブな HTML5 ウィジェットが含まれています。ウィジェットはツール呼び出しを通じて MCP サーバーと通信し、ファイルブラウザー、ダッシュボード、ワークフローマネージャーなどを表示します。

利用可能なウィジェット

ウィジェット	リソース URI	説明
ファイルピッカー	widget://file-picker	会話に添付するファイルを閲覧・選択できます。フォルダーの移動、検索、プレビュー、エージェント用のファイル選択が可能です。ワークスペースと共有コンテキストでのファイル管理（アップロード、移動、コピー、削除）にも対応しています
ワークスペースピッカー	widget://workspace-picker	組織／ワークスペース／共有の検索機能付き選択、4 ステップのワークスペース作成ウィザード、5 ステップの共有作成ウィザードを利用できます
ファイルビューアー	widget://file-viewer	情報パネル（詳細、バージョン、AI による要約、メタデータ）を備えた統合ファイルプレビュー（画像、PDF、動画、音声、コード、スプレッドシート）を利用できます
ワークフローマネージャー	widget://workflow	タスクボード、タスク詳細、承認パネル、ToDo チェックリスト、作業ログビューアーを利用できます
コメントパネル	widget://comments	スレッド形式のコメント、リアクション、アンカー付きコメント（画像領域、タイムスタンプ）を利用できます
アップローダー	widget://uploader	ドラッグ＆ドロップによるワークスペースまたは共有へのファイルのアップロード、POST /blob サイドカー経由の分割アップロード、リアルタイムの進捗追跡に対応した Web URL のインポートが可能です

アップローダーウィジェット

アップローダーウィジェットでは、4 ステップでファイルをアップロードできます。

1. アップロード先を選択 -- 組織を選択し、次にワークスペースまたは共有を選択して、必要に応じてサブフォルダーに移動します
2. ファイルを選択 -- ウィジェットにファイルをドラッグ＆ドロップするか、ファイルピッカーボタンを使用してローカルファイルを参照します
3. 進捗を確認しながらアップロード -- ファイルはリアルタイムの進捗バーとともに自動でアップロードされます。すべてのファイルで分割アップロード（create-session、POST /blob、blob_id を使用したチャンク送信、finalize）が使用されます。Web URL では web-import が使用されます
4. チャットで参照 -- アップロード完了後、「チャットで参照」をクリックすると、アップロードしたファイルがエージェントとの会話に添付され、さらに議論したり AI による分析を行ったりできます

このウィジェットは、MCP ブリッジ経由で upload ツール（アクション：create-session、chunk、finalize、web-import、status、cancel、limits、extensions）と storage ツール（アクション：list）を使用します。

プロンプトから起動： デスクトップ MCP クライアントで App: Upload Files プロンプトを使用します。

ツールから起動：

apps action launch app_id uploader profile_type workspace profile_id <workspace_id>

apps ツールの使用

apps ツールでは、ウィジェットの検索と起動ができます。

1. アプリの一覧表示： apps アクション list -- メタデータとともに利用可能なすべてのウィジェットを返します
2. アプリの詳細： app_id を指定した apps アクション details -- 特定のウィジェットのメタデータ全体を返します
3. アプリの起動： app_id、profile_type（または context_type）、profile_id（または context_id）を指定した apps アクション launch -- コンテキスト付きでウィジェットを開きます
4. ツールに対応するアプリの検索： tool_name を指定した apps アクション get-tool-apps -- ツールとそのウィジェットを対応付けます

ウィジェットのコンテキスト

すべてのウィジェットで、ワークスペースまたは共有コンテキストを使用できます。

• profile_type: "workspace" + profile_id: "<workspace_id>"
• profile_type: "share" + profile_id: "<share_id>"

デザインシステム

ウィジェットでは、Fast.io のフロントエンドと一致する共通のデザインシステムを使用します。

• ライトモードとダークモードに対応（システム設定または明示的な data-theme 属性に従います）
• フロントエンドのテーマに基づいた、一貫性のあるタイポグラフィ、余白、色、アイコン
• レスポンシブレイアウト（デスクトップ、タブレット、モバイルのブレークポイント）

例：ファイルピッカーの起動

apps action launch app_id file-picker profile_type workspace profile_id <workspace_id>

例：ストレージ操作に対応するウィジェットの検索

apps action get-tool-apps tool_name storage

---

9. ツールの完全なリファレンス

機能ごとに分類した、19 個すべてのツールとそのアクションです。各項目にはアクション名と説明が記載されています。ワークフローツール（task、worklog、approval、todo）を使用するには、対象のワークスペースまたは共有でワークフローを有効にする必要があります。

auth

signin -- メールアドレスとパスワードを使用して Fast.io にサインインします。JWT 認証トークンを返します。アカウントで 2FA が有効になっている場合、2fa-verify を呼び出すまではトークンのスコープが制限されます。トークンはセッションに自動的に保存されます。 set-api-key -- Fast.io API キーを使用して認証します。キーは API に対して検証され、MCP セッションに保存されます。その後のすべてのツール呼び出しは自動的に認証されます。デフォルトでは、キーにはアカウント所有者と同じ権限が付与されます。スコープ付きキーでは、アクセスを特定のエンティティに制限できます（OAuth トークンと同じスコープシステムです）。付与されたスコープ外の操作は 403 を返します。スコープ付きキーが検出されると、アクセス可能なエンティティを示す scopes_detail がレスポンスに含まれます。スコープなしのキーは、取り消されない限り有効期限がありません。スコープ付きキーには、任意で有効期限を設定できます。

signup -- 新しい Fast.io エージェントアカウント（agent=true）を作成し、自動的にサインインします。account_type を "agent" に設定し、無料のエージェントプランを割り当てます。サインアップ後にメール認証が必要です。email-verify を呼び出してコードを送信し、次にコードを指定して再度呼び出すと認証できます。ほとんどのエンドポイントでは、メール認証が必要です。signup 自体に認証は必要ありません。

check -- 現在のセッショントークンがまだ有効かどうかを確認します。トークンに関連付けられたユーザー ID を返します。

session -- 認証済みユーザーの現在のセッション情報を取得します。名前、メールアドレス、アカウントフラグなどのプロフィール詳細が含まれます。

signout -- 保存されたセッションを消去してサインアウトします。認証済みの場合は、先にトークンを検証します。

2fa-verify -- 2FA コードを送信して、2 要素認証を完了します。signin が two_factor_required: true を返した後に呼び出してください。新しいフルスコープトークンは自動的に保存されます。

email-check -- メールアドレスが登録可能と思われるかどうかを示す参考情報を返します。確定情報ではありません： signup が後から受け付けたメールアドレスに対して、available: false が返されるケースが確認されています（上流の POST /user/email/ エンドポイントでのレスポンスキャッシュ、またはドメイン固有のポリシーが原因と考えられます）。email-check の結果にかかわらず、必ず signup に進み、signup のエラーを確定情報として扱ってください。認証は必要ありません。

password-reset-request -- パスワードリセットメールを要求します。セキュリティ上、メールアドレスが存在するかどうかは明らかにせず、常に成功を返します。認証は必要ありません。

password-reset -- メールで受け取ったリセットコードを使用して、新しいパスワードを設定します。認証は必要ありません。

email-verify -- メール認証コードを送信または検証します。email_token を省略すると、新しいコードが送信されます。指定した場合はコードが検証され、メールアドレスが認証済みとしてマークされます。

status -- ローカルのセッション状態を確認します。API 呼び出しは行われません。ユーザーが認証済みかどうかを返し、認証済みの場合は user_id、email、auth_method（"api_key"、"jwt"、または "oauth"）、トークンの有効期限、scopes（未加工の文字列）、scopes_detail（エンティティ名、ドメイン、親階層を含む展開済み配列。未取得の場合は null）、および agent_name（設定されている場合）を返します。

pkce-login -- ブラウザーを使用した PKCE ログインフローを開始します。ユーザーがブラウザーで開く URL を返します。サインインしてアクセスを承認すると、ブラウザーに認証コードが表示されます。ユーザーがコードをコピーして pkce-complete に渡すと、サインインが完了します。エージェントを介してパスワードが送信されることはありません。任意のパラメーター：scope_type（デフォルトはフルアクセスの "user"。スコープ付きアクセスには "org"、"workspace"、"all_orgs"、"all_workspaces"、または "all_shares" を使用）、agent_name（承認画面と監査ログに表示されます。デフォルトは MCP クライアント名です）。

pkce-complete -- 認証コードをアクセストークンと交換して、PKCE ログインフローを完了します。ユーザーがブラウザーでアクセスを承認し、画面に表示されたコードをコピーした後に呼び出してください。トークンはセッションに自動的に保存されます。スコープ付きアクセスが許可された場合、レスポンスには scopes（"org:123:rw" のような付与されたスコープ文字列の JSON 配列）と agent_name が含まれます。 api-key-create -- 新しい永続 API キーを作成します。キーの値全体が返されるのは作成時の一度だけです。安全に保管してください。任意のパラメーター：name（メモ／ラベル）、scopes（アクセスを制限する場合のスコープ文字列の JSON 配列。例：["org:123:rw", "workspace:456:r"]。フルアクセスの場合は省略）、agent_name（エージェント／アプリケーション名、最大 128 文字）、key_expires（ISO 8601 形式の有効期限日時。有効期限を設定しない場合は省略）、token（2FA コード。アカウントで 2FA が有効な場合に必要ですが、API キー認証では不要です）。スコープ付きキーには、v2.0 JWT トークンと同じスコープシステムが使用されます。

api-key-update -- 既存の API キーのメタデータを更新します。key_id が必要です。任意のパラメーター：name（メモ／ラベル）、scopes（スコープの JSON 配列。フルアクセスに戻すには空文字列を送信）、agent_name（クリアするには空文字列を送信）、key_expires（有効期限をクリアするには空文字列を送信）。指定したフィールドのみが更新されます。

api-key-list -- 認証済みユーザーのすべての API キーを一覧表示します。キーの値はマスクされます（末尾 4 文字のみ表示）。各キーのレスポンスには、scopes、agent_name、expires フィールドが含まれます。

api-key-get -- 特定の API キーの詳細を取得します。キーの値はマスクされます。レスポンスには、scopes、agent_name、expires フィールドが含まれます。

api-key-delete -- API キーを失効（削除）させます。この操作は取り消せません。任意のパラメーター：token（2FA コード。アカウントで 2FA が有効な場合に必要ですが、API キー認証では不要です）。

2fa-status -- 現在の二要素認証の設定状態（有効、未確認、または無効）を取得します。

2fa-enable -- 指定したチャネルで二要素認証を有効にします。TOTP の場合、QR コード表示用のバインド URI が返されます。2fa-verify-setup が呼び出されるまで、アカウントは「未確認」状態になります。

2fa-disable -- アカウントの二要素認証を無効化（解除）します。2FA が有効（確認済み）状態の場合、確認のため有効な 2FA コードが必要です。

2fa-send -- SMS、音声通話、または WhatsApp を使用して、ユーザーの電話に 2FA 確認コードを送信します。

2fa-verify-setup -- 2FA 設定コードを検証して、登録を確認します。2FA の状態を「未確認」から「有効」に切り替えます。

oauth-list -- 認証済みユーザーのすべてのアクティブな OAuth セッションを一覧表示します。

oauth-details -- 特定の OAuth セッションの詳細を取得します。

oauth-revoke -- 特定の OAuth セッションを失効させます（そのデバイスからログアウトします）。

oauth-revoke-all -- すべての OAuth セッションを失効させます。「他のすべての場所からログアウト」を有効にするため、現在のセッションを除外することもできます。

user

me -- 現在認証されているユーザーのプロフィール詳細を取得します。

update -- 現在のユーザーのプロフィール（名前、メールアドレスなど）を更新します。

search-contacts -- 名前またはメールアドレスの部分文字列で、個人の連絡先リスト（以前の招待、共有、チャットでのメンションを通じてやり取りした相手）を検索します。フラットな{email: name}マップを返します。user_idもコンテキストのスコープも含まれません。ワークスペース、共有、組織のメンバーシップを確認するには、workspace action=members、share action=members、またはorg action=membersを使用してください。

close -- 現在のユーザーアカウントを閉鎖／削除します（メールによる確認が必要です）。

details-by-id -- ユーザーIDを指定して、他のユーザーの公開プロフィール詳細を取得します。

profiles -- ユーザーがアクセスできるプロフィールの種類（組織、ワークスペース、共有）を確認します。

allowed -- ユーザーの国で共有や組織を作成できるかどうかを確認します。

org-limits -- 無料での組織作成の適格性、上限、クールダウンの状況を取得します。

list-shares -- 現在のユーザーがメンバーになっているすべての共有を一覧表示します。

invitation-list -- 現在のユーザーへの保留中の招待をすべて一覧表示します。

invitation-details -- IDまたはキーを指定して、特定の招待の詳細を取得します。

accept-all-invitations -- 保留中の招待をすべて一度に承諾します。

asset-upload -- ユーザーアセット（プロフィール写真など）をアップロードします。プレーンテキストのコンテンツか、base64エンコードされたcontent_base64のどちらかを指定してください（両方は指定できません）。

asset-delete -- ユーザーアセット（プロフィール写真など）を削除します。

asset-types -- ユーザーが利用できるアセットの種類を一覧表示します。

asset-list -- すべてのユーザーアセットを一覧表示します。

instructions-get -- /user/me/instructions/にある個人用AI指示スロットを読み取ります。未書き込みのスロットを初めて読み取ると、404ではなく、タイムスタンプがnullのcontent: ""が返されます。本人のみが対象です。meスコープのバリエーションはありません。

instructions-set -- 個人用AI指示を置き換えます（全体を置換、UTF-8で最大65536バイト）。書き込み後のペイロードを返すため、後続のinstructions-getは不要です。

instructions-clear -- 個人用AI指示をソフトクリアします（監査行は保持されます）。冪等です。

org

list -- 内部組織（ユーザーが直接メンバーになっている組織、member: true）を一覧表示します。各組織にはweb_urlが含まれます。メンバー組織のサブスクリプション状況、ユーザー権限、プラン情報を返します。管理者以外のメンバーには、サブスクリプションが有効な組織のみが表示されます。外部組織は含まれません。外部組織については、discover-externalを使用してください。

details -- 組織の詳細情報を取得します。web_urlを返します。返されるフィールドは呼び出し元のロールによって異なります。オーナーには暗号化キーとストレージ設定が、管理者には請求情報と権限が、メンバーには基本情報が表示されます。

members -- 組織のすべてのメンバーについて、ID、メールアドレス、名前、権限レベルを一覧表示します。

invite-member -- メールアドレスでユーザーを組織に招待します。メールアドレスは本文ではなくURLパスで渡します。ユーザーがすでにFast.ioアカウントを持っている場合は直接追加されます。アカウントを持っていない場合は、メールで招待が送信されます。オーナーとして追加することはできません。

remove-member -- 組織からメンバーを削除します。組織のperm_member_manage設定で指定されたメンバー管理権限が必要です。

update-member-role -- 組織内のメンバーのロール／権限を更新します。ロールを'owner'に設定することはできません。代わりにtransfer-ownershipを使用してください。

limits -- 組織のプラン上限とクレジット使用量を取得します。クレジット上限、使用状況の統計、請求期間、トライアル情報、ランレート予測を返します。管理者またはオーナーのロールが必要です。

list-workspaces -- 現在のユーザーがアクセスできる組織内のワークスペースを一覧表示します。各ワークスペースにはweb_urlが含まれます。オーナーと管理者にはすべてのワークスペースが表示され、メンバーには参加権限の設定に合致するワークスペースが表示されます。

list-shares -- 現在のユーザーがアクセスできる共有を一覧表示します。各共有にはweb_urlが含まれます。親組織とワークスペースの情報を含むすべての共有を返します。特定の組織に属する共有を識別するには、レスポンスのparent_orgを使用してください。 create -- 「agent」請求プランで新しい組織を作成します。domain（2～63 文字、小文字の英数字とハイフン）と name（3～100 文字、制御文字を含まない）が必要です。認証済みユーザーがオーナーになります。ストレージインスタンスと agent プランのサブスクリプション（無料、50 GB、月 5,000 クレジット）が自動的に作成されます。新しい組織とトライアルのステータスを返します。

update -- 組織の詳細を更新します。web_url を返します。指定されたフィールドのみが変更されます。組織情報、ブランディング、ソーシャルリンク、権限、請求先メールアドレスに対応しています。管理者またはオーナーのロールが必要です。

close -- 組織を閉鎖／削除します。アクティブなサブスクリプションをキャンセルし、削除を開始します。オーナーのロールが必要です。confirm フィールドは、組織のドメインまたは組織 ID と一致する必要があります。

public-details -- 組織の公開情報を取得します。web_url を返します。メンバーである必要はありません。公開レベルのフィールド（名前、ドメイン、ロゴ、アクセントカラー）のみを返します。組織が存在し、閉鎖または停止されていない必要があります。

create-workspace -- 組織内に新しいワークスペースを作成します。web_url を返します。組織の請求プランに基づき、ワークスペース機能の利用可否と作成上限を確認します。作成したユーザーがワークスペースのオーナーになります。名前空間： ワークスペースの folder_name は、プラットフォーム全体で一意である必要があります。指定された名前がすでに使用されていて、ハイフンを含まない場合、サーバーは自動的に組織 ID を先頭に付けます（例：reports → 3587676312889739297-reports）。ハイフンを含む名前はそのまま送信されます。最終的な folder_name はレスポンスで返されます。

billing-plans -- 料金、機能、プランのデフォルト設定を含む、利用可能な請求プランの一覧を取得します。サブスクリプションの作成に必要なプラン ID を返します。

billing-create -- 新しいサブスクリプションを作成するか、既存のサブスクリプションを更新します。新しいサブスクリプションの場合、Stripe Setup Intent を作成します。既存のサブスクリプションの場合、プランを更新します。管理者またはオーナーが必要です。

billing-cancel -- 組織のサブスクリプションをキャンセルします。オーナーのロールが必要です。プランによっては、キャンセル時に組織が閉鎖される場合があります。

billing-details -- Stripe の顧客情報、サブスクリプションのステータス、Setup Intent、Payment Intent、プラン情報など、請求とサブスクリプションの詳細を取得します。管理者またはオーナーが必要です。

billing-activate -- 請求プランを有効化します（開発環境のみ）。Stripe の支払い設定をシミュレートし、テスト用の支払い方法を使ってサブスクリプションを有効化します。

billing-reset -- 請求ステータスをリセットします（開発環境のみ）。Stripe の顧客情報を削除し、subscriber フラグを解除します。

billing-members -- 請求対象のメンバーと、各メンバーが所属するワークスペースの一覧を取得します。組織が誰の分を請求されているかを確認できます。管理者またはオーナーのロールが必要です。

billing-meters -- 使用量メーターの時系列データ（ストレージ、転送量、AI など）を取得します。コストとクレジットの計算値を含む、グループ化されたデータポイントを返します。管理者またはオーナーのロールが必要です。

leave -- 組織から退出します。現在のユーザー自身のメンバーシップを削除します。オーナーは退出できません。先に所有権を譲渡するか、組織を閉鎖する必要があります。

member-details -- 組織内の特定のユーザーについて、権限、招待ステータス、通知設定、有効期限など、詳細なメンバーシップ情報を取得します。

transfer-ownership -- 組織の所有権を別のメンバーに譲渡します。現在のオーナーは管理者に降格します。オーナーのロールが必要です。

transfer-token-create -- 組織の譲渡トークン（有効期間 72 時間）を作成します。クレーム URL https://go.fast.io/claim?token=<token> を人に送信してください。組織を引き継いでもらう場合、または agent プランで 402 Payment Required が発生した場合に使用します。オーナーのロールが必要です。

transfer-token-list -- 組織の有効な譲渡トークンをすべて一覧表示します。各トークンには web_url（クレーム URL）が含まれます。オーナーのロールが必要です。

transfer-token-delete -- 保留中の譲渡トークンを削除（取り消し）します。オーナーのロールが必要です。 transfer-claim -- 転送トークンを使用して組織の所有権を取得します。認証済みユーザーが新しいオーナーになり、以前のオーナーは管理者に降格されます。

invitations-list -- 組織の保留中の招待をすべて一覧表示します。招待の状態で絞り込むこともできます。組織のメンバーであれば実行できます。

invitation-update -- 組織の既存の招待を更新します。状態、権限、または有効期限を変更できます。

invitation-delete -- 組織の招待を取り消し、削除します。

join -- 招待または許可されたドメインの自動参加を通じて組織に参加します。招待キーとアクション（accept/decline）を指定することもできます。

asset-upload -- 組織のアセット（ロゴ、バナーなど）をアップロードします。プレーンテキストのコンテンツ、または base64 エンコードされた file_base64 のいずれかを指定します（両方は指定できません）。管理者またはオーナーのロールが必要です。

asset-delete -- 組織からアセットを削除します。管理者またはオーナーのロールが必要です。

asset-types -- 組織で利用できるアセットの種類を一覧表示します。

asset-list -- 組織のアセットをすべて一覧表示します。

discover-all -- アクセス可能な組織（参加済みおよび招待済み）をすべて一覧表示します。各組織には web_url が含まれます。ユーザーとの関係を示す user_status を含む組織データを返します。

discover-available -- 参加可能な組織を一覧表示します。各組織には web_url が含まれます。ユーザーがすでにメンバーである組織は除外されます。

discover-check-domain -- 組織のドメイン名が使用可能かどうかを確認します。形式を検証し、予約済みの名前と既存のドメインを確認します。

discover-external -- 外部組織（member: false）を一覧表示します。各組織には web_url が含まれます。ユーザーが組織の直接のメンバーではなく、ワークスペースのメンバーシップを通じてのみアクセスできる組織です。人間がエージェントを組織に招待せずにワークスペースへ招待した場合によく発生します。Organizations セクションの Internal vs External Orgs を参照してください。

custom-domain-get -- 組織の現在のカスタムドメインを取得します。hostname、status（pending または active）、cname_target を返します。カスタムドメインが設定されていない場合は { hostname: null } を返します。すべての組織メンバーが読み取れます。

custom-domain-create -- 組織にカスタムドメインを追加します。hostname（有効な FQDN。例：files.acme.com）が必要です。status: "pending" と cname_target を含む、作成されたドメインを返します。顧客は hostname を cname_target に向ける DNS CNAME レコードを追加する必要があります。管理者またはオーナーのロール、および Pro または Business プランが必要です。

custom-domain-delete -- 組織のカスタムドメインを削除します。既存の TLS 証明書は自然に失効します（最長 90 日）。管理者またはオーナーのロールが必要です。プランによる制限はありません。プランをダウングレードした組織でもドメインを削除できます。

custom-domain-validate -- 組織のカスタムドメインの DNS をリアルタイムで検証します。hostname、dns_valid（ブール値）、status、cname_target、cname_found を返します。DNS が正しく設定されており、ドメインの状態が pending の場合、自動的に有効化されます。すべての組織メンバーが実行できます。

instructions-get -- 組織の AI 指示を読み取ります。scope: "profile"（デフォルト）では、/org/{org_id}/instructions/ の組織全体のスロットを読み取ります。scope: "me" では、/org/{org_id}/instructions/me/ のユーザーごとのスロットを読み取ります。未書き込みのスロットを初めて読み取ると、404 ではなく、タイムスタンプが null の content: "" が返されます。各スコープの読み取りアクセスには、書き込み時に記載されているものと同じ認証条件が適用されます。セクション 5 の org の引用を参照してください。

instructions-set -- 組織の AI 指示を置き換えます（全体置換、UTF-8 で最大 65536 バイト）。scope: "profile"（デフォルト）にはオーナーまたは管理者の権限が必要です（管理者以外はコード 1680 の 403）。scope: "me" はユーザーごとのスロットに書き込みます（すべてのメンバーが実行可能）。2 つのスコープは独立しており、サーバー側では結合されません。結合した内容を表示する場合は、クライアント側で連結してください。

instructions-clear -- 組織の AI 指示をソフトクリアします（監査行は保持されます）。scope: "profile"（デフォルト）にはオーナーまたは管理者の権限が必要です。scope: "me" はユーザーごとのスロットをクリアします。冪等です。

workspace

list -- すべての組織にわたって、ユーザーがアクセスできるワークスペースをすべて一覧表示します。各ワークスペースには web_url が含まれます。 details -- 特定のワークスペースの詳細情報を取得します。web_urlを返します。

update -- 名前、説明、ブランディング、権限など、ワークスペースの設定を更新します。web_urlを返します。

delete -- ワークスペースを完全に閉鎖（ソフト削除）します。オーナー権限と確認が必要です。

archive -- ワークスペースをアーカイブします（変更を禁止し、データを保持します）。Admin 以上の権限が必要です。

unarchive -- アーカイブされたワークスペースを復元し、アクティブな状態にします。Admin 以上の権限が必要です。

members -- ワークスペースの全メンバーと、そのロールおよびステータスを一覧表示します。アクティブなメンバーと保留中のメンバーの両方が含まれます。保留中のメンバーはstatus: "pending"とinviteオブジェクト（{id, created, expires} — expiresはYYYY-MM-DD HH:MM:SS UTC、有効期限がない場合はnull）を持ち、アクティブなメンバーはstatus: "active"とinvite: nullを持ちます。保留中のメンバーは、まだサインアップしていない招待ユーザーです。タスク、承認、ToDoの割り当て先として有効です。保留中のメンバーへの招待を取り消すには、invitationアクションのdeleteでinvite.idを使用します。

list-shares -- ワークスペース内のすべての共有を一覧表示します。アーカイブ状態で絞り込むこともできます。各共有にはweb_urlが含まれます。

import-share -- ユーザーが所有する共有をワークスペースにインポートします。共有の唯一のオーナーである必要があります。

available -- 現在のユーザーが参加可能で、まだ参加していないワークスペースを一覧表示します。各ワークスペースにはweb_urlが含まれます。

check-name -- ワークスペースのフォルダー名が使用可能かどうかを確認します。ワークスペース名は全体で一意である必要があります。任意のcheck_org_idを渡すと、名前が使用済みの場合に組織IDを接頭辞にした代替候補（例：3587676312889739297-reports）を取得できます。

create-note -- ワークスペースのストレージに新しいMarkdownノートを作成します。content（インラインMarkdown）またはblob_id（POST /blobから取得。MCPトランスポートのオーバーヘッドを避けるため、約10 KBを超えるノートではこちらを推奨）のいずれか一方のみを指定します。web_url（ノートのプレビューリンク）を返します。80 KB以上の書き込みでは、100 KBの上限に達する前に新しいファイルへの切り替えを推奨する、処理を妨げない警告ヒントが含まれます。

update-note -- ノートのMarkdownコンテンツや名前を更新します（name、content、blob_idのいずれかが必須です）。content（インラインMarkdown）またはblob_id（POST /blobから取得。大規模な更新ではこちらを推奨）のいずれか一方のみを指定します。web_url（ノートのプレビューリンク）を返します。80 KB以上の書き込みでは、新しいファイルへの切り替えを提案する処理を妨げない_warningsエントリが含まれます。type: "note"のノードのみ受け付けます。 アップロードフローでアップロードされた.mdファイルはノートではなくファイルであり、このアクションではエラー153548 Node is not a noteが返され、拒否されます。ファイルのコンテンツを変更するには、既存ファイルと同じparent_node_idおよび同じfilenameを指定してuploadアクションのcreate-sessionを呼び出します（またはtarget_node_idを渡してIDで上書き対象を指定します）。その後、チャンクを送信して確定する（またはストリーミングする）と、同じ名前のアップロードで既存ファイルが上書きされ、以前のコンテンツはバージョンとして保持されます。呼び出す前にノードの種類を確認するには、storageアクションのdetailsを使用し、typeフィールドを確認してください。ファイルとノートの違いに関する詳しい説明は、Notesセクションを参照してください。

read-note -- ノートのMarkdownコンテンツとメタデータを読み取ります。ノートのコンテンツとweb_url（ノートのプレビューリンク）を返します。

quickshare-get -- ノードの既存のクイック共有の詳細を取得します。web_urlを返します。

quickshare-delete -- ノードのクイック共有リンクを無効化して削除します。

quickshares-list -- ワークスペース内のすべての有効なクイック共有を一覧表示します。各クイック共有にはweb_urlが含まれます。 metadata-template-create -- ワークスペースに新しいメタデータテンプレートを作成します。すべてのプランで利用できます（Agent/Freeでは最初のテンプレートを作成でき、Proではワークスペースごとに2つ、Businessでは10個まで作成できます）。名前、説明、カテゴリ（legal、financial、business、medical、technical、engineering、insurance、educational、multimedia、hr）、フィールド（フィールド定義をJSON形式でエンコードした配列）が必要です。各フィールドには、名前、説明、タイプ（string、int、float、bool、json、url、datetime）と、任意の制約（min、max、default、fixed_list、can_be_null、autoextract）があります。autoextract のデフォルトは true です。手動で管理するフィールド（ユーザーが入力するメモ、レビュー担当者のフラグなど）では false に設定してください。こうしたフィールドは行全体を対象とするAI抽出ではスキップされますが、metadata-set による書き込みは引き続き受け付けます。各テンプレートには autoextract:true のフィールドが少なくとも1つ必要です。そうでない場合、APIは1605（Invalid Input）を返します。プランごとのノード上限（Agent/Free/Proは10、Businessは1,000）は、テンプレート自体ではなくファイルマッピングに適用されます。

metadata-template-delete -- メタデータテンプレートを削除します。システムテンプレートとロックされたテンプレートは削除できません。template_idが必要です。

metadata-template-list -- メタデータテンプレートを一覧表示します。任意のtemplate_filter：enabled、disabled、custom（システム以外）、またはsystem。フィルターを指定しない場合、削除されていないすべてのテンプレートを返します。各エントリの fields 配列には、すべてのフィールドについて autoextract が常に含まれるようになりました（既存のテンプレートではデフォルトで true）。公開中のAIカテゴリ概要によると、レスポンスには plan_node_limit、is_truncated、およびフィルター適用前の件数も各エントリの表示件数と併せて含まれるはずです。ただし、公開中のレスポンス例にはこれらのフィールドが明記されていないため、依存する前に実行時に正確なフィールド名を確認してください。

metadata-template-details -- すべてのフィールド定義を含む、メタデータテンプレートの詳細を取得します。template_idが必要です。返される fields 配列には、すべてのフィールドについて autoextract が常に含まれるようになりました（既存のテンプレートではデフォルトで true）。公開中のAIカテゴリ概要によると、レスポンスには plan_node_limit、is_truncated、およびフィルター適用前の件数も含まれるはずです。ただし、公開中のレスポンス例にはこれらのフィールドが明記されていないため、実行時にフィールド名を確認してください。テンプレートごとの nodes/ 一覧エンドポイントにおけるフィルター適用前の件数フィールドは total_count_unfiltered ですが、details の対応フィールドは異なる場合があります。

metadata-template-update -- 既存のメタデータテンプレートを更新します。名前、説明、カテゴリ、フィールドの任意の組み合わせを更新できます。template_idが必要です。

metadata-template-clone -- 任意の変更を加えてメタデータテンプレートを複製します。既存のテンプレートを基に新しいテンプレートを作成します。パラメーターはmetadata-template-updateと同じです。template_idが必要です。 metadata-template-preview-match — 提案されたテンプレートを作成する前に、ワークスペース内でどのファイルが一致するかをプレビューします。テンプレートの用途を説明する name（1～255 文字）と description（1～2000 文字）が必要です。matched_files（一致したノードのサンプル。各項目には node_id、name、mimetype、短い要約が含まれます。ライブリファレンスではサンプル配列の長さは固定されていないため、件数を決めつけずに matched_files を反復処理してください）に加え、total_eligible、total_scanned、total_matched の各件数を返します。total_eligible に関する注意：ライブリファレンスによると、これは対象となるファイルのワークスペース全体の件数ではなく、対象ファイルのサンプルウィンドウのサイズです。ワークスペース内の対象ファイルがサンプルウィンドウに収まる数を超える場合、total_eligible は「さらに存在する」ことを示すために sample_ceiling + 1 に設定されます。返された値は、実際の総数ではなく下限値として扱ってください。また、plan_node_limit（ワークスペースの現在のプランにおけるテンプレートごとのノード上限。-1 は無制限）と、would_truncate_at（上限が適用される場合は min(total_matched, plan_node_limit)、それ以外の場合は total_matched）も返します。ドキュメントで推奨されている切り詰めのヒューリスティック：would_truncate_at < total_matched の場合はユーザーに警告してください。プランの上限によって一致件数のサンプルが制限され、自動一致処理で上限を超えた分が通知なくスキップされます。このヒューリスティックに該当する場合、MCP ハンドラーは実際の数値を含む警告を _warnings に自動で出力します。返された node_id を metadata-template-suggest-fields の入力として使うと、AI が提案する列を取得できます。

metadata-template-suggest-fields — ファイルのサンプルに基づいて、AI に 1～5 個のカスタムフィールドを提案させます。workspace_id、description（1～2000 文字。preview-match で使うものと同じビュー／テンプレートの説明）、node_ids（1～25 個のノード ID を含む JSON エンコード済み配列。通常は preview-match の結果を使用します。フォルダノードはサーバー側で除外されます）が必要です。省略可能な user_context は、作成するものについてのユーザーが記述した短いヒントです（最大 64 文字。英字、数字、スペースのみ。例："photo collection"、"contract tracker"）。以下を返します：（a）ファイル、説明、user_context に基づいて AI が提案するテンプレート／ビューの表示名 suggested_name、（b）AI が提案するテンプレートの説明 suggested_description、（c）{name, type, description, can_be_null, max?, fixed_list?, example_value?} オブジェクトの配列 suggested_fields（name／type／description／can_be_null／max／fixed_list キーは metadata-template-create の fields パラメーターとそのまま互換性があります。一方、example_value はそのフィールドに妥当な値を示すプレビュー専用のヒントで、宣言された type に一致する型になります（int には整数、datetime には ISO 8601、bool にはブール値。サーバー側で型変換され、256 文字が上限です。有効な値に変換できる例を AI が生成できなかった場合は省略されます）。metadata-template-create に配列を渡す前に example_value を削除してください）、（d）file_sample_count。テンプレート作成 UI では、事前入力されたデフォルトとして suggested_name と suggested_description を使用してください（ユーザーはそのまま使用するか、編集できます）。通常、呼び出しには 10～30 秒かかります。エラーケース：入力が無効またはクレジット不足の場合は 400、同じユーザーとワークスペースに対する別の suggest-fields 呼び出しが進行中の場合は 409 Conflict（数秒待ってから再試行してください）、一時的な LLM 障害の場合は 500（再試行してください）。

metadata-template-assign — メタデータテンプレートをワークスペースに割り当てます。各ワークスペースに割り当てられるテンプレートは最大 1 つです。システムテンプレートを割り当てると、自動的に複製されます。template_id が必要です。省略可能な node_id（ワークスペースレベルの割り当てでは null）も指定できます。

metadata-template-unassign — ワークスペースからテンプレートの割り当てを解除します。ワークスペース管理者の権限が必要です。

metadata-template-resolve — 指定されたノードに適用されるメタデータテンプレートを解決します。ワークスペースレベルのテンプレートを返します（node_id は受け付けますが、現在はワークスペースから継承されます）。テンプレートが割り当てられていない場合は null を返します。 metadata-template-assignments -- ワークスペース内のすべてのテンプレート割り当てを一覧表示します。

metadata-view-get -- テンプレートに対して呼び出し元が保存したビューを取得します。workspace_id と template_id が必要です。保存済みビューのレコード {id, user_id, template_id, config, created, updated} を返します。呼び出し元がそのテンプレートのビューを保存していない場合は、エラー 1609 を返します。保存済みビューは ユーザーごとに非公開 です。識別タプルは (workspace, user, template) であり、各タプルにつき保存済みビューは最大 1 つです。

metadata-view-save -- テンプレートに対して呼び出し元が保存したビューをアップサートします。workspace_id、template_id、および config（JSON でエンコードされた文字列）が必要です。MCP ツールは文字列化された JSON を受け取り、JSON の形式が正しいことを検証するために解析した後、再度文字列化した形式を config フィールドとして form-urlencoded のリクエストボディで API に転送します。config のスキーマ：version（1 と一致する必要があります）、columns（配列。順序は表示順です。各項目：必須の field 文字列、任意の visible? bool、任意の width? 正の整数）、sort（{field: string, dir: "asc" | "desc"}）、filters（最大 5 個の配列。AND 条件で連結されます。各項目：field 文字列、operator は = != < <= > >= のいずれか、value_type は string | int | float | bool のいずれか — json は拒否されます。value は宣言された value_type に一致する値）。config 内の未知のキーは、場所を問わずエラー 1605 で拒否されます。アップサートの動作：(workspace, user, template) に対するビューがすでに存在する場合は、既存の行を置き換えます。この場合、行の id と created は保持され、updated が更新されます。ビューが存在しない場合は、新しい行が挿入されます。保存されたビューを返します。

config の例：

{
  "version": 1,
  "columns": [
    { "field": "vendor", "visible": true, "width": 180 },
    { "field": "amount", "visible": true, "width": 120 },
    { "field": "notes", "visible": false }
  ],
  "sort": { "field": "amount", "dir": "desc" },
  "filters": [
    { "field": "vendor", "operator": "=", "value_type": "string", "value": "Acme" },
    { "field": "amount", "operator": ">=", "value_type": "float", "value": 100.0 }
  ]
}

metadata-view-delete -- テンプレートに対して呼び出し元が保存したビューを削除します。workspace_id と template_id が必要です。呼び出し元自身の保存済みビューのみが対象です（同じテンプレートに対する他のユーザーのビューには影響しません）。

metadata-views-list -- ワークスペース内のテンプレート全体にわたって、呼び出し元が保存したすべてのビューを一覧表示します。workspace_id が必要です。{items, count} を返します。items は保存済みビューのレコードの配列であり、呼び出し元がビューを保存しているテンプレートごとに 1 件ずつ含まれます。 metadata-view-export -- 呼び出し元がテンプレート用に保存したビューを非同期でファイルに書き出し、TSV ファイルとしてワークスペースストレージに保存します。workspace_id と template_id が必要です。任意の parent_node_id は保存先フォルダーの OpaqueId です。省略するか空の値を渡すと、ワークスペースのルートに書き込まれます。このエンドポイントは処理をキューに追加してすぐに応答します。実際の TSV はバックグラウンドワーカーによって保存先フォルダーに書き込まれます。応答形式は次の 2 種類です。(a) queued — {result:true, job_id, status:"queued", filename, message}。filename は保存済みビューの name から生成されます（ファイルシステムで使用できない文字をサニタイズし、.tsv 拡張子を付けます。サニタイズ後の名前が空の場合は metadata_view_{partialViewId}.tsv にフォールバックします）。(b) duplicate — {result:true, status:"duplicate", filename, message}。同じ (workspace, user, template, destination_folder) のエクスポートがすでにキューに追加されているか処理中の場合、job_id は含まれません。同じビューでも、別のフォルダーへのエクスポートは重複扱いになりません。前提条件：呼び出し元がビューを保存済みである必要があります（先に metadata-view-save を実行してください。そうでない場合は 404 View not found）。また、ワークスペースの組織でメタデータ機能が有効になっている必要があります（無効の場合は 403。課金機能の制御で、Free／Pro／Business はすべて対象です）。完了を確認するには、保存先フォルダーを storage アクションの list でポーリングするか、親フォルダーに対して storage アクションの details を実行し、返された filename と一致する name のノードを探します。フォルダー内を確認する方法は、重複分岐では追跡する job_id がないため、確実です。ほとんどのエクスポートは数秒以内に完了します。同時エクスポートは、ワークスペース全体で共有される Redis ミューテックスによって直列化されます。同じワークスペース内の異なるビューをエクスポートする 2 人の呼び出し元は、1 件ずつ処理されます。スナップショットの意味：TSV に反映されるのは、リクエスト時点ではなく、ワーカーの実行時点でのメタデータの状態です。ファイル名や列はカスタマイズできません。どちらも保存済みビューから取得されます。変更するには、先に metadata-view-save でビューを更新してください。ビューはユーザーごとに保存されます。ワークスペース管理者が「チームのビュー」をエクスポートすることはできません。エクスポートされるのは、呼び出しユーザーが保存したビューです。このエンドポイントには、ユーザー単位およびワークスペース単位のレート制限が適用されます（X-Rate-Limit-* ヘッダー）。 metadata-search — ワークスペースのテンプレートおよびカスタムメタデータフィールドの値を対象に、語句による検索を行います。クエリのキーワードを含むメタデータフィールド値を持つワークスペースファイルを、関連度順に返します。workspace_id と q（検索キーワード。前後の空白は除去されます。空の場合は拒否されます。最大1024文字）が必要です。省略可能な template_id を指定すると、そのテンプレートが提供した値を少なくとも1つ持つノードに結果を限定します（このフィルターを設定すると、カスタムフィールドは除外されます）。ページネーションには省略可能な limit（1～100、デフォルトは100）と offset（デフォルトは0）を使用します。offset+limit は10000を超えられません。検索の仕様：複数トークンのクエリ（例：q=foo bar）では、すべてのトークンが必要です（アナライザーでトークン化したうえでAND検索）。大文字と小文字は区別されません。64文字以下のクエリでは部分文字列検索が適用されます。それより長いクエリでは、完全な単語／トークンの一致のみが適用されます（200文字の文章クエリは部分文字列としてではなく、単語ごとに照合されます）。{results, pagination} を返します。各結果エントリーは {node_id, score (BM25 — 相対的な並び順の目安にすぎず、クエリ間で比較できません), template_ids (値を提供したテンプレート。空の配列はカスタムフィールドのみの一致を意味します), node (完全にハイドレートされたノードのペイロード。storageアクションのdetails と同じ形式で、ハイドレート時にゴミ箱内のノードは除外されます)} です。ページネーションの形式は {total, limit, offset, has_more} です。total は ES のヒット数（インスタンスフィルター適用後、ゴミ箱フィルター適用前）です。「X件の結果」などのUI表示にはこの値を使用してください。has_more = (offset+limit) < total です。インデックス反映の遅延：メタデータの書き込みはイベントキューを介して非同期で検索インデックスに反映されるため、メタデータ編集（テンプレート抽出、自動照合、手動編集）後、新しい値が検索可能になるまで1～2秒かかることがあります。書き込み直後の検索を正しさの確認に使わないでください。競合が発生します。「保存したばかりの内容を表示する」フローでは、検索ではなくメタデータテンプレートのエンドポイントから直接読み取ってください。テナント分離：サーバーは常に、基盤となる ES フィルターに instance_id = workspace_id を注入するため、別のワークスペースとして扱うことはできません。別のワークスペースの template_id を渡しても、ヒット数がゼロになるだけで、情報が漏れることはありません。この機能でできないこと：構造化フィルターではありません（where field = value には metadata_filters を指定して metadata-list-files を使用してください）。セマンティック検索／ベクトル検索ではありません（語句検索のみのため、"house" は "residence" に一致しません）。ファイル内容の検索には使えません（その場合は storage アクションの search を使用してください）。結果のスニペット／ハイライトは API から返されません。一致した node_id を使って metadata-get からメタデータを取得し、クライアント側で部分文字列照合してください。

ノード一覧エンドポイントでの保存済みビューの自動適用。 テンプレートごとのノード一覧エンドポイント（GET /workspace/{id}/metadata/templates/{tid}/nodes/）では、対応するクエリパラメーター（sort_field／filters）が省略されると、呼び出し元の保存済み config.sort と config.filters が自動適用されます。クエリパラメーターを明示的に指定した場合は、常にそちらが優先されます。ステートレスなクエリパラメーターと保存済みビューの状態がサーバー側でマージされることはありません。columns はサーバー側で自動適用されません。クライアントは保存済みの columns 配列から、列の順序／表示状態／幅を自ら描画する必要があります。フィールド名には注意が必要です。ステートレスな filters クエリパラメーターでは、各エントリーにレガシー仕様の key を使用します（仕様に変更はありません）。一方、保存済みビューの config.filters エントリーでは field を使用します。保存済みビューを自動適用する際、サーバーは内部で field を key に変換します。このエンドポイントは現在、MCP の workspace アクションとして公開されていません（上記の「MCP ツールの対応範囲」の箇条書きを参照）。自動適用を試すには、コードモードの execute から fastio.get() を使用してエンドポイントを呼び出してください。 metadata-get -- 1 つ以上のファイルのメタデータをすべて取得します。テンプレートに準拠するメタデータとカスタム（自由形式）のキーと値のペアの両方が対象です。単一 ID 形式では、node_id を渡します。ノードの詳細、template_id、template_metadata 配列、custom_metadata 配列、およびトップレベルの autoextractable ブール値が返されます（autoextractable は template_id と同じ階層にあり、どちらのメタデータ配列にもネストされません）。autoextractable が true になるのは、ノードがファイル（フォルダーではない）で、ゴミ箱に移動されておらず、AI による要約が完了している場合のみです。これは抽出パイプラインが内部で使用するシグナルと同じです。「今すぐ抽出」や「再抽出」の UI 操作を有効にするかどうかの判断に使用してください。値が false の場合、metadata-extract を呼び出すと失敗するか、何も行われません（先に AI による要約の完了を待ってください）。一括形式（1 回の呼び出しで 1～25 個の ID）： ノード ID の JSON エンコードされた配列として node_ids を渡します（すべて同じワークスペース内の ID にしてください。ワークスペースをまたぐ ID は ID ごとのエラー 191049 として返されます）。上限数のカウント前に重複は除外されます。一括レスポンスの形式は {format:"multi", objects, templates, errors, object_count, template_count, error_count, requested_count} です。objects 内の各エントリーは、単一 ID 形式の本文と同じ構造（instance_id、object_id、template_id、node_id、template_metadata、custom_metadata、autoextractable）で、templates マップ（template_id をキーとします）には、各テンプレートの定義が各オブジェクト内で繰り返されることなく、それぞれ 1 回だけ格納されます。各行の表示には、templates マップから obj.template_id に対応するテンプレートを参照してください。一括呼び出しは、対象数にかかわらずスロットリングのカウントが 1 回分なので、フォルダーやピッカーのビューで複数のファイルのメタデータが必要な場合は、ファイルごとにループして呼び出すよりも一括形式を優先してください。ID ごとのエラーコード（errors[] 内）：147196 無効な ID 形式、196136 ルートのセンチネルが指定された、191049 ノードが見つからない（ワークスペースをまたぐ ID に対しても返されます）、190770 ノード取得時の一時的なバックエンドエラー、150183 ノードは存在するがファイルでもノートでもない（フォルダーなど）、157684 メタデータ行取得時の一時的なバックエンドエラー。147196/196136/150183/191049 は確定的なエラーです。再試行しないでください。再試行する価値があるのは 190770/157684 のみです。25 件を超える ID を指定すると、サーバーへのラウンドトリップは発生せず、明確なエラーがクライアント側で返されます。

metadata-set -- ファイルのメタデータのキーと値のペアを設定または更新します。値はテンプレートのフィールド定義に準拠している必要があります。node_id、template_id、および key_values（キーと値のペアを含む JSON オブジェクト）が必要です。

metadata-delete -- ファイルのメタデータを削除します。特定のエントリーを削除するには、削除するキー名を含む keys（JSON 配列）を指定します。すべてのメタデータを削除する場合は省略してください。フォルダーではなく、ファイルとノートでのみ使用できます。node_id が必要です。 metadata-extract -- ファイルの AI 駆動メタデータ抽出をキューに登録します。このエンドポイントは非同期（HTTP 202）です。バックグラウンドジョブをキューに登録し、約 500ms で job_id、status（queued/in_progress/completed/errored）、status_uri、node_id、template_id、fields（要求された範囲、または全行の場合は null）を返します。レスポンスに抽出値は含まれません。node_id が必要です。template_id は省略可能です（デフォルトはワークスペースのテンプレート）。extract_fields は省略可能で、一部のフィールドだけを抽出する場合はフィールド名の JSON エンコード済み配列（例：["vendor","amount"]）を指定します。全行を抽出する場合は省略します。自動抽出との連動：extract_fields を省略すると、実際の抽出対象は autoextract:true のテンプレートフィールドに限定されます。テンプレート内のすべてのフィールドで自動抽出がオプトアウトされている場合、エンドポイントは成功を返しますが、job_id は返されず、ジョブもキューに登録されません。自動抽出がオプトアウトされているフィールドを強制的に抽出するには、extract_fields で明示的に指定してください。明示的なリストは手動での上書きとして、そのまま適用されます。事前チェック：実行前に、対象ノードの autoextractable フラグ（metadata-get が返します）を確認してください。false の場合、抽出は失敗するか何も行われません。AI 要約が完了するまで待ってください。冪等性：最初の呼び出しが実行中に同じ (node_id, template_id, fields) タプルで再度抽出を実行すると、同じ job_id が返されます（重複ジョブはキューに登録されません）。異なる template_id または異なる extract_fields を指定した場合は、個別のジョブが作成されます。抽出値には is_auto: true のマークが付けられ、AI クレジットを消費します。新しいエージェントのフローは次のとおりです：(1) metadata-get で autoextractable:true を確認します。(2) metadata-extract を呼び出し、返された job_id があれば保存します（すべてのフィールドがオプトアウトされたテンプレートでは、成功しても job_id は返されません。この場合は、手動で上書きするため明示的な extract_fields を渡すか、ポーリングを省略してください）。(3) jobs-status をポーリングし、metadata_extract 配列から kind:"single" かつ自分の node_id と一致するエントリを絞り込みます。(4) エントリの status:"completed" を確認したら、metadata-get を呼び出して値を読み取ります。status:"errored" の場合は、エントリの error_message を通知します。完了またはエラーから約 1 時間以上経過した古いエントリは、jobs-status から自動的に非表示になります。ポーリングではなくイベントへの反応を希望するサブスクライバー向けに、各状態遷移でアクティビティイベント EVENT_METADATA_KV_EXTRACT_STARTED／EVENT_METADATA_KV_EXTRACT／EVENT_METADATA_KV_EXTRACT_ERRORED が発行されます。

jobs-status -- ワークスペースの非同期ジョブの状態を取得します。workspace_id が必要です。実行中の非同期ジョブを分類した配列で返します（現在は metadata_extract 配列が含まれます。AI インデックス作成など、その他のバックグラウンド処理のカテゴリが追加される場合があります）。metadata_extract 配列には、単一ノードのエントリ（kind:"single"。node_id、job_id、template_id、fields_scope、status、progress_percent、started_at、updated_at、completed_at、error_message を含む）とバッチエントリ（kind:"batch"。total_files、eligible_files、processed、skipped、failed、progress_percent などを含む）が混在します。kind フィールドで判別してください。完了またはエラー状態の古いエントリは約 1 時間後に自動的に非表示になるため、エントリが見つからない場合は「アクティブではなくなった」と扱ってください。ポーリング間隔は 1〜3 秒で問題ありません。このエンドポイントには十分なレート制限が設定されています。

metadata-list-files -- 特定のテンプレートのメタデータを持つファイルを、オプションのフィルタリングや並べ替えとともに一覧表示します。node_id（検索対象のフォルダー）と template_id が必要です。metadata_filters（JSON エンコード済み）、order_by（フィールドキー）、order_desc は省略可能です。

metadata-list-templates-in-use -- フォルダー内で使用されているメタデータテンプレートと、テンプレートごとの使用数を一覧表示します。node_id が必要です。

metadata-versions -- ファイルのメタデータのバージョン履歴を取得します。メタデータの変更スナップショットを時系列で返します。node_id が必要です。

enable-workflow -- ワークスペースでワークフロー機能（タスク、作業ログ、承認、ToDo）を有効にします。ワークスペースでワークフローツールを使用する前に呼び出す必要があります。 disable-workflow -- ワークスペースのワークフロー機能を無効にします。ワークフローのデータはすべて保持され、再度有効にするまでアクセスできなくなります。

enable-import -- ワークスペースのクラウドインポート機能（外部ストレージプロバイダー）を有効にします。インポート ID をプロビジョニングする前に呼び出す必要があります。

disable-import -- ワークスペースのクラウドインポート機能を無効にします。既存のインポートソースは同期を停止しますが、データは保持されます。

instructions-get -- ワークスペースの AI 指示を読み取ります。scope: "profile"（デフォルト）では、/workspace/{ws_id}/instructions/ のワークスペース全体のスロットを読み取ります。scope: "me" では、/workspace/{ws_id}/instructions/me/ のユーザーごとのスロットを読み取ります。未書き込みのスロットを初めて読み取ると、タイムスタンプが null の content: "" が返されます（404 にはなりません）。

instructions-set -- ワークスペースの AI 指示を置き換えます（全体置換、UTF-8 で最大 65536 バイト）。scope: "profile"（デフォルト）では、オーナーまたは管理者である必要があります（管理者以外にはコード 1680 の 403）。scope: "me" では、ユーザーごとのスロットに書き込みます（ゲストを除くすべてのメンバーが対象）。2 つのスコープは独立しており、サーバー側では結合されません。統合した表示が必要な場合は、クライアント側で連結してください。

instructions-clear -- ワークスペースの AI 指示をソフトクリアします（監査行は保持されます）。scope: "profile"（デフォルト）では、オーナーまたは管理者である必要があります。scope: "me" では、ユーザーごとのスロットをクリアします（ゲストを除く）。冪等です。

share

list -- 認証済みユーザーがアクセスできる共有を一覧表示します。各共有には web_url が含まれます。

details -- 特定の共有の詳細をすべて取得します。web_url が返されます。

create -- ワークスペースに新しい共有を作成します。

update -- 共有の設定を更新します（一部更新）。

delete -- 共有を削除（閉鎖）します。確認のため、共有 ID またはカスタム名が必要です。

public-details -- 公開されている共有情報を取得します（メンバーシップは不要ですが、認証は必要です）。

archive -- 共有をアーカイブします。ゲストのアクセスをブロックし、変更を制限します。

unarchive -- 以前にアーカイブした共有を復元し、アクティブな状態にします。

password-auth -- 共有パスワードで認証します。共有用のスコープ付き JWT が返されます。

members -- 共有のメンバーをすべて一覧表示します。アクティブなメンバーと保留中のメンバーの両方について、status フィールドと invite フィールドが含まれます（ワークスペースのメンバーと同じです）。

available -- 参加可能な共有を一覧表示します（参加済みおよび所有している共有が対象で、保留中の招待は除外されます）。各共有には web_url が含まれます。

check-name -- 共有のカスタム名（URL 名）が利用可能か確認します。

quickshare-create -- ワークスペース内のファイルへの一時的な QuickShare リンクを作成します。expires（秒数、デフォルトは 10,800、最大 604,800 = 7 日）または expires_at（ISO 8601 日時）を指定できます。

enable-workflow -- 共有のワークフロー機能（タスク、作業ログ、承認、ToDo）を有効にします。共有でワークフローツールを使用する前に呼び出す必要があります。

disable-workflow -- 共有のワークフロー機能を無効にします。ワークフローのデータはすべて保持され、再度有効にするまでアクセスできなくなります。

instructions-get -- 共有の AI 指示を読み取ります。scope: "profile"（デフォルト）では、/share/{share_id}/instructions/ の共有全体のスロットを読み取ります。scope: "me" では、/share/{share_id}/instructions/me/ のユーザーごとのスロットを読み取ります。未書き込みのスロットを初めて読み取ると、タイムスタンプが null の content: "" が返されます（404 にはなりません）。

instructions-set -- 共有の AI 指示を置き換えます（全体置換、UTF-8 で最大 65536 バイト）。scope: "profile"（デフォルト）では、オーナーまたは管理者である必要があります（管理者以外にはコード 166463 の 403）。scope: "me" では、ユーザーごとのスロットに書き込みます（登録済みメンバーのみ。匿名ゲストまたはリンク経由のゲストにはコード 185733 の 403）。2 つのスコープは独立しており、サーバー側では結合されません。統合した表示が必要な場合は、クライアント側で連結してください。

instructions-clear -- 共有の AI 指示をソフトクリアします（監査行は保持されます）。scope: "profile"（デフォルト）では、オーナーまたは管理者である必要があります。scope: "me" では、ユーザーごとのスロットをクリアします（登録済みメンバーのみ。匿名ゲストは対象外）。冪等です。

storage

すべてのストレージ操作では、profile_type パラメーター（context_type も使用可能。workspace または share）と、profile_id（context_id も使用可能。19 桁のプロフィール ID）が必要です。

list -- ページネーションを使って、ディレクトリ内のファイルとフォルダーを一覧表示します。各項目には web_url が含まれます（workspace のみ）。profile_type、profile_id、node_id が必要です（ルートフォルダーには root を指定します）。

recent -- すべてのディレクトリにわたって、最近更新されたファイルとフォルダーを更新日時の降順で一覧表示します。単一のフォルダーを対象とする list とは異なり、ストレージツリー全体のノードを返します。省略可能な type フィルター（file、folder、link、note）、page_size（100、250、500）、ページネーション用の cursor をサポートしています。workspace のフォルダー共有では、結果は共有のサブツリーに自動的に絞り込まれます。

details -- 1 つ以上のノードの詳細情報を取得します。node_id を使った単一検索では、web_url（Web UI でファイルのプレビューまたはフォルダーを表示する、人が読みやすいリンク。workspace のみ）を含む従来の単一形式を返します。node_ids（1～25 個の ID。同じ workspace/share 内のもの）を使った一括検索では、{format: "multi", nodes, errors, node_count, error_count, requested_count} を返します。部分的な結果は通常どおりです（errors が空でない 200 は失敗ではありません。取得できたノードを表示し、入力 ID の横に ID ごとのエラーを示してください）。結果は node.id（大文字と小文字を区別しない）で照合します。順序は保持されません。発生する可能性がある ID ごとのエラーコード：133123（見つからない／workspace が異なる）、191878（無効な OpaqueId）、146950（物理コンテンツが消失。重複排除後のキャッシュの古さが原因で、再試行不可）、146256（一時的な取得エラー。安全に再試行可能）、179961（フォーマットエラー。まれ）。25 個を超える ID はクライアント側で拒否されるため、分割してください。一括エンドポイントでは、あらゆる種類のノード（ファイル、フォルダー、ノート、リンク）を受け付けます。

search -- 統合検索：キーワード検索に加え、workspace のインテリジェンスが有効な場合は自動的にセマンティックマッチングを行います。英語の語形変化処理が組み込まれているため（「cats」で「cat」が、「running」で「run」が見つかります）、単語の変化形も検索できます。パラメーター：query（必須）、省略可能な files_scope（nodeId:versionId のペアをカンマ区切りで指定。セマンティック検索の対象を特定のファイルに限定します。インテリジェンスが必要で、無効な場合は無視されます。最大 100 個）、folders_scope（nodeId:depth のペアをカンマ区切りで指定。depth は 1～10。BFS を使ってフォルダーツリーを対象にします。インテリジェンスが必要で、無効な場合は無視されます。最大 100 個）、details（各結果に完全なノード詳細（プレビュー、AI の状態、メタデータ、バージョン）を返すには "true" を指定します。デフォルトの上限は 10 に減少します）、limit（1～500。デフォルトは 100。details=true の場合は 10）、offset。常に含まれる項目： name、parent_id（string|null）、type（file、folder、note）。インテリジェンスが有効な場合に追加される項目： relevance_score（0.0～1.0。キーワード：0.0～0.5、セマンティック：0.5～1.0）、content_snippet（一致したテキストチャンク。キーワードのみの場合は null）、match_source（"keyword"、"semantic"、"both" のいずれか）、media_segment（音声／動画のディープリンク用の {start_seconds, end_seconds}。メディア以外では null）、page（ドキュメントのページ単位のマッチング用の {start_page, end_page}。ドキュメント以外では null）、mimetype（セマンティックマッチの場合のファイル MIME タイプ）。details=true の場合に追加される項目： node（完全なノードリソース。プレビュー、AI の状態、バージョン、メタデータを含みます。ノードを読み込めない場合は null）。トップレベルの search_metadata（インテリジェンスが有効な場合のみ）：intelligence_enabled（bool）、semantic_available（bool。gRPC が失敗した場合は false となり、グレースフルデグラデーションが適用されます）、scoped（bool。files_scope または folders_scope が使用された場合は true）。インテリジェンスが無効な場合： レスポンスに含まれるのは name、parent_id、type のみです（キーワードのみの動作）。各結果には web_url が含まれます（workspace のみ）。

trash-list -- 現在ゴミ箱にある項目を一覧表示します。各項目には web_url が含まれます（workspace のみ）。

create-folder -- 新しいフォルダーを作成します。web_url を返します（workspace のみ）。

copy -- ファイル／フォルダーをコピーします。node_id を使った単一コピー（workspace または share）。node_ids 配列を使った一括コピー（workspace のみ）。新しいコピーの web_url を返します（workspace のみ）。 move — ファイル／フォルダーを移動します。単一の移動にはnode_idを使用します（ワークスペースまたは共有領域）。一括移動にはnode_ids配列を使用します（ワークスペースのみ）。web_urlを返します（ワークスペースのみ）。

delete — ファイル／フォルダーをゴミ箱に移動して削除します。単一の削除にはnode_idを使用します（ワークスペースまたは共有領域）。一括削除にはnode_ids配列を使用します（ワークスペースのみ）。

rename — ファイルまたはフォルダーの名前を変更します。web_urlを返します（ワークスペースのみ）。

purge — ゴミ箱にあるノードを完全に削除します（取り消せません）。メンバー権限が必要です。

restore — ゴミ箱からファイル／フォルダーを復元します。単一の復元にはnode_idを使用します（ワークスペースまたは共有領域）。一括復元にはnode_ids配列を使用します（ワークスペースのみ）。復元されたノードのweb_urlを返します（ワークスペースのみ）。

add-file — アップロード済みのファイルをストレージの場所にリンクします。web_urlを返します（ワークスペースのみ）。

add-link — ストレージに共有参照リンクノードを追加します。

transfer — ノードを別のワークスペースまたは共有ストレージインスタンスにコピーまたは移動します。デフォルトのモードは'copy'（ソースを保持）です。transfer_mode='move'を使用すると、コピー後にソースをゴミ箱に移動します（ルートは移動できません）。モードがmoveの場合、ソースが正常にゴミ箱に移動されたかどうかを示すsource_trashed（ブール値）がレスポンスに含まれます。

version-list — ファイルのバージョン履歴を一覧表示します。ファイルのweb_urlを返します（ワークスペースのみ）。

version-restore — ファイルを以前のバージョンに復元します。ファイルのweb_urlを返します（ワークスペースのみ）。

lock-acquire — ファイルを排他的にロックし、同時編集を防ぎます。

lock-status — ファイルのロック状態を確認します。

lock-release — ファイルの排他的ロックを解除します。

preview-url — ファイルのプレビュー用認証済み URL を取得します（サムネイル、PDF、画像、動画、音声、スプレッドシート）。preview_typeパラメーターが必要です。preview_url（すぐに使用できる URL）とweb_url（Web UI でファイルを開く、人が読みやすいリンク。ワークスペースのみ）を返します。

preview-transform — ファイルの変換（画像のサイズ変更、トリミング、形式変換）をリクエストし、変換結果のダウンロード URL を取得します。transform_nameパラメーターが必要です。transform_url（すぐに使用できる URL）とweb_url（Web UI でファイルを開く、人が読みやすいリンク。ワークスペースのみ）を返します。

upload

create-session — ファイルの分割アップロードセッションを作成します。任意のtarget_node_idを指定すると、特定の既存ノードを確実に上書きできます（action=update + file_id=<target_node_id>）。これを設定すると、parent_node_idは無視され、filenameは任意になります（新しい名前を指定しない限り既存の名前を維持し、置換時の名前変更が可能です）。filenameを省略すると、ツールは現在の名前を取得するためにstorageのdetailsを追加で1回呼び出します（API では更新モードでもnameが必要です）。これを省略するにはfilenameを指定してください。node_idは維持され、新しいバージョンはstorageアクションのversion-listで確認できます。ファイルの内容を更新する必要がある場合は、削除して再アップロードする代わりにこれを使用してください。target_node_idを指定しない場合も、同じ名前かつ同じ親を指定したアップロードはインプレースで上書きされます（標準の REPLACE 動作）。上書き後も、以前の内容はstorageアクションのversion-list／version-restoreで復元できます。

stream-upload — ストリームセッションを作成し、ファイル本文をアップロードして、1 回の呼び出しで自動的に確定します。サイズが事前にわからず、呼び出し間でセッション ID を必要としない、生成コンテンツやパイプ経由のコンテンツに使用します。profile_type、profile_id、parent_node_id、filenameと、content（テキスト） | content_base64（小さなバイナリ。サーバー側でデコード） | blob_id（POST /blob）のいずれか1つが必要です。任意のパラメーター：max_size（上記のガイダンスを参照。省略するとプランのファイルサイズ上限が使用されます）、target_node_id（特定のノードを上書きします。設定するとparent_node_idは無視され、filenameは任意になります。filenameを省略すると、create-sessionの説明にあるstorageのdetails参照が追加で行われます）、hash、hash_algo。セッションの作成後にストリームの POST が失敗した場合、未完了のセッションは自動的にキャンセルされます。 batch -- 最大200個の小さなファイル（各≤4 MB、合計≤100 MB）を、1回のマルチパート往復で1つの対象フォルダーにアップロードします。profile_type、profile_id、files[] が必要です（各エントリーには、filename と blob_id | content（テキスト） | content_base64（小さなバイナリ。サーバー側でデコード）のいずれか1つが必要です。relative_path、hash、hash_algo は省略可能です）。folder_id（バッチ全体の対象。デフォルトはインスタンスのルート）、creator（応答に含めて返すタグ）、include_hash（デフォルトは true。ハッシュのないエントリーに対してクライアント側で SHA-256 を計算）は省略可能です。status、upload_id、node_id を含むエントリーごとの results[] と、事前にフィルタリングされた errors[] が返されます。成功時でも node_id は null になる場合があります — 非同期ストレージを使用するワークスペースでは、ノード ID は後から割り当てられます。null をエラーとして扱わないでください。部分的な成功は通常の動作です — HTTP 200 で count_errored > 0 となるのは想定内です。エラーになったエントリーのみを再試行してください。すべてのエントリーがエラーになった場合、応答には all_failed: true が含まれます。ファイル単位のアップロードとは独立したレート制限バケットを使用します。429 の場合、ツールは x-ve-limit-expires の UTC 日時を提示します。認証が必要です（匿名の呼び出し元には HTTP 401、コード 10011 が返されます。その場合はシングルファイルの create-session フローを使用してください）。

chunk -- 単一のチャンクをアップロードします。テキスト／文字列には content、小さなバイナリ（サーバー側でデコード）には content_base64、POST /blob でステージングしたバイナリには blob_id を使用します。いずれか1つだけを指定してください。注意：content は UTF-8 としてそのまま保存されます。ここに base64 を渡さないでください。

stream -- 既存のストリームセッション（stream=true を指定した create-session で作成したもの）にファイル全体の本文をアップロードします。自動的にファイナライズされます。呼び出し間で upload_id が必要な場合を除き、stream-upload を優先してください。upload_id と、content（テキスト） | content_base64（小さなバイナリ。サーバー側でデコード） | blob_id のいずれか1つが必要です。hash、hash_algo は省略可能です。

finalize -- アップロードセッションをファイナライズし、ファイルの組み立てを開始して、保存完了または失敗までポーリングします。最終的なセッション状態を返します。

status -- アップロードセッションの現在の状態を取得します。省略可能な wait パラメーター（ミリ秒、0 = 即時）を指定すると、サーバー側のロングポーリングに対応します。

cancel -- アクティブなアップロードセッションをキャンセルして削除します。

list-sessions -- 現在のユーザーのアクティブなアップロードセッションをすべて一覧表示します。

cancel-all -- アクティブなアップロードセッションをすべて一度にキャンセルして削除します。

chunk-status -- アップロードセッションのチャンク情報を取得します。

chunk-delete -- アップロードセッション内のチャンクを削除／リセットします。

web-import -- 外部 URL からワークスペースまたは共有先にファイルをインポートします。

web-list -- 省略可能なフィルタリング条件を指定して、ユーザーの Web アップロードジョブを一覧表示します。

web-cancel -- アクティブな Web アップロードジョブをキャンセルします。

web-status -- 指定した Web アップロードジョブの詳細な状態を取得します。

limits -- ユーザーのプランにおけるアップロードサイズとチャンクの上限を取得します。chunk_size（最大チャンクサイズ。全プランで100 MB）、size（最大ファイルサイズ：free/agent は1 GB、pro は25 GB、business は50 GB）、chunks（セッションあたりの最大数：free/agent は35、pro/business は550）、sessions、sessions_size_max を返します。注意： 最小チャンクサイズ（最終チャンクを除き1 MB）は固定のシステム定数で、このエンドポイントからは返されません。action_context、instance_id、file_id、org は省略可能なパラメーターです。

extensions -- アップロードで制限されているファイル拡張子と許可されているファイル拡張子を取得します。特定のプランの制限を確認するには、plan パラメーターを省略可能な値として指定します。restricted_extensions、archive_extensions、enforcement_enabled、plan、cache_ttl を返します。

blob-info -- POST /blob サイドカーエンドポイントの URL、MCP セッション ID、必要なヘッダー、シェルからのファイルアップロードにすぐ使える curl コマンドを取得します。パラメーターは不要です。blob サイドカー経由でファイルをアップロードする前に使用してください。curl を使って MCP トランスポートの制限を回避するために必要な情報がすべて得られます。

ダウンロード

file-url -- ファイルのダウンロードトークンとURLを取得します。任意でバージョンを指定できます。profile_type、profile_id、node_id が必要です。

zip-url -- フォルダーまたはワークスペース／共有全体のZIPダウンロードURLを取得します。認証方法の説明とともにURLを返します。profile_type、profile_id、node_id が必要です（ストレージツリー全体の場合は root を使用します）。

quickshare-details -- quickshareリンクのメタデータとダウンロード情報を取得します。認証は不要です。

AI

すべてのAIアクションには、profile_type パラメーター（context_type も使用可能。workspace または share）と、profile_id（context_id も使用可能。19桁のプロフィールID）が必要です。

chat-create -- 初回の質問を添えて、新しいAIチャットを作成します。デフォルトの範囲はワークスペース全体（インデックス済みのすべてのドキュメント）です。検索範囲を絞る必要がない場合は、files_scope と folders_scope を省略してください。範囲や添付ファイルを指定する場合は、nodeId:versionId のペアを指定します。versionIdを空欄にすると、現在のバージョンが自動的に解決されます（明示的な versionId は、ストレージの一覧／詳細の version フィールドから取得してください）。files_attach を使用する場合は、各ファイルの ai.attach が true であることを事前に確認してください（ストレージの詳細から確認できます）。ファイル関連のパラメーターがある場合、タイプは chat から chat_with_files に自動的に昇格します。チャットIDと初回メッセージIDを返します。AIの応答を取得するには、message-readを使用してください。

chat-list -- AIチャットの一覧を取得します。

chat-details -- メッセージ履歴全体を含むAIチャットの詳細を取得します。

chat-update -- AIチャットの名前を更新します。

chat-delete -- AIチャットを削除します。

chat-publish -- 非公開のAIチャットを公開し、すべてのメンバーが閲覧できるようにします。

message-send -- 既存のAIチャットにフォローアップメッセージを送信します。メッセージIDを返します。AIの応答を取得するには、message-readを使用してください。

message-list -- AIチャット内のすべてのメッセージを一覧表示します。

message-details -- 応答テキストや引用を含む、AIチャット内の特定のメッセージの詳細を取得します。

message-read -- AIメッセージの応答を読み取ります。AIの応答が完了するまでメッセージ詳細エンドポイントをポーリングし、その後、全文を返します。

share-generate -- 外部のAIチャットボットに貼り付けられる、一時的なダウンロードURL付きのAI Share Markdownを生成します。

transactions -- 請求状況を追跡するため、AIトークン使用量の取引一覧を取得します。

autotitle -- 内容に基づいて、AIでタイトルと説明を生成します（shareコンテキストのみ）。

comment

すべてのコメントエンドポイントでは、entity_type が workspace または share、parent_id が19桁のプロフィール ID、node_id がファイルの不透明な ID の場合に、/comments/{entity_type}/{parent_id}/ または /comments/{entity_type}/{parent_id}/{node_id}/ というパスパターンを使用します。

list -- 特定のファイル（ノード）のコメントを一覧表示します。パラメーター：sort（created／-created）、limit（2～200）、offset、include_deleted、reference_type フィルター、include_total。

list-all -- ワークスペースまたは共有内のすべてのコメントを一覧表示します（特定のノードに限定されません）。list と同じ一覧表示パラメーターを使用します。

add -- 特定のファイルにコメントを追加します。本文：text（合計最大8,192文字。@[...] のメンションタグを除いた表示テキストは最大500文字）。次のメンションタグに対応しています：@[profile:id]、@[user:opaqueId:Name]、@[file:fileId:name.ext]。任意の parent_comment_id（1階層のスレッド形式。返信への返信は自動的にフラット化されます）、任意の reference（コンテンツのアンカー指定には type、timestamp、page、region、text_snippet、Markdown／ノート上のテキストのアンカー指定には exact、prefix、suffix、start_offset、end_offset を使用します。type には "document" または "text" を指定します）、および作成時にコメントをワークフローエンティティに関連付ける任意の linked_entity_type（task または approval）と linked_entity_id に対応しています。JSON 本文を使用します。

delete -- コメントを削除します。再帰的に削除されるため、親コメントを削除すると返信もすべて削除されます。

bulk-delete -- 複数のコメントを一括で論理削除します（最大100件）。再帰的な削除ではありません。削除されたコメントへの返信は保持されます。

details -- ID を指定して、単一コメントの詳細を取得します。レスポンスには linked_entity_type と linked_entity_id が含まれます（リンクされていない場合は null）。

reaction-add -- 絵文字リアクションを追加または変更します。ユーザーはコメントごとに1つのリアクションを付けられます。新しいリアクションを追加すると、以前のリアクションは置き換えられます。

reaction-remove -- コメントから自分の絵文字リアクションを削除します。

link -- 既存のコメントをワークフローエンティティにリンクします。パラメーター：comment_id、linked_entity_type（task または approval）、linked_entity_id。コメントごとにリンクは1つです。リンクすると、既存のリンクは置き換えられます。リンクフィールドが設定された更新後のコメントを返します。

unlink -- コメントからワークフローのリンクを削除します。パラメーター：comment_id。リンクフィールドが null に設定された更新後のコメントを返します。

linked -- 逆引き検索：指定したワークフローエンティティにリンクされているすべてのコメントを検索します。パラメーター：linked_entity_type（task または approval）、linked_entity_id。指定したエンティティにリンクされているコメントの一覧を返します。

event

search -- プロフィール、イベントタイプ、カテゴリ、サブカテゴリ、イベント名、期間で絞り込み、監査／イベントログを検索します。カテゴリ、サブカテゴリ、イベント名の分類一覧については、セクション7のイベント絞り込みリファレンスを参照してください。

summarize -- イベントを検索し、アクティビティの AI による自然言語の要約を返します。search と同じカテゴリ／サブカテゴリ／イベントの絞り込みに対応しています。

details -- ID を指定して、単一イベントの詳細を取得します。

activity-list -- ワークスペースまたは共有の最近のアクティビティイベントをポーリングします。

activity-poll -- ワークスペースまたは共有のアクティビティの変化をロングポーリングします。サーバーは、変化が発生するか待機時間が経過するまで接続を維持します。変更された内容を示すアクティビティキーと、次回のポーリングに使用する lastactivity タイムスタンプを返します。

member

すべてのメンバー操作では、entity_type（workspace または share）と entity_id（19 桁のプロフィール ID）パラメーターが必要です。

メンバーオブジェクトには、status（active または pending）と invite（アクティブなメンバーの場合は null、保留中の場合は {id, created, expires}。expires は YYYY-MM-DD HH:MM:SS UTC 形式で、有効期限がない場合は null）が含まれます。保留中のメンバーは、まだサインアップしていない招待ユーザーです。メンバーリストにすぐに表示され、タスク、承認、ToDo を割り当てることができます。保留中のメンバーがサインアップすると、ステータスが active になり、割り当てはすべて維持されます。招待を取り消す（invitation アクション delete で invite.id を指定する）と、保留中のメンバーが削除され、そのワークフロー項目の割り当ても解除されます。

add -- ユーザー ID を指定して既存ユーザーを追加するか、メールアドレスで招待します。メールアドレスまたはユーザー ID を email_or_user_id として渡します。メールアドレスで招待したユーザーがアカウントを持っていない場合、保留中のメンバーとして追加されます。ワークスペースでは、permissions（admin/member/guest）でアクセスレベルを設定します。共有では role（admin/member/guest/view）を使用します。

remove -- メンバーを削除します（オーナーは削除できません）。

details -- 特定のメンバーの詳細なメンバーシップ情報を取得します。ワークスペースでは member_id、共有では user_id を渡します。

update -- メンバーのロール、通知、または有効期限を更新します。

transfer-ownership -- 別のメンバーにオーナー権限を移譲します（現在のオーナーは管理者に降格されます）。

leave -- 退出します（自分を削除します）。オーナーは先にオーナー権限を移譲する必要があります。

join -- 組織のメンバーシップに基づいて自分で参加します。

join-invitation -- 招待キーを使用して招待を承諾または辞退します。

invitation

すべての招待操作では、entity_type（workspace または share）と entity_id（19 桁のプロフィール ID）パラメーターが必要です。

list -- 保留中の招待をすべて一覧表示します。

list-by-state -- 状態で絞り込んだ招待を一覧表示します。

update -- 招待を再送信または更新します（ID または招待先のメールアドレスで指定）。

delete -- 保留中の招待を取り消して削除します。これにより、メンバーリストから該当する保留中のメンバーも削除され、そのメンバーに割り当てられたワークフロー項目（タスク、承認、ToDo）の割り当ても解除されます。invitation_id には、メンバーオブジェクトの invite.id を使用します。

asset

すべてのアセット操作では、entity_type（org、workspace、share、または user）と entity_id（org/workspace/share の場合は19 桁のプロフィール ID）パラメーターが必要です。

upload -- アセット（ロゴ、バナー、プロフィール写真など）をアップロードします。プレーンテキストの内容または Base64 エンコードされたデータのいずれかを指定します（両方は指定できません）。

delete -- アセットを削除します。

types -- エンティティで利用可能なアセットの種類を一覧表示します。

list -- エンティティのすべてのアセットを一覧表示します。

read -- アセットを読み取る、またはダウンロードします。

タスク

ワークスペースや共有のタスクリストとタスクを管理します。すべてのタスク操作を行うには、対象のエンティティでワークフローが有効になっている必要があります（workspace の操作 enable-workflow または share の操作 enable-workflow）。

list-lists -- ワークスペースまたは共有のすべてのタスクリストを一覧表示します。profile_type と profile_id が必要です。sort_by（created、updated、name）、sort_dir、limit（1-200）、offset、format（Markdown の場合は "md"）に対応しています。

create-list -- 新しいタスクリストを作成します。profile_type、profile_id、name（1-255 文字）が必要です。description（最大 2000 文字）は任意です。

list-details -- 特定のタスクリストの詳細を取得します。list_id が必要です。format に対応しています。

update-list -- タスクリストの名前または説明を更新します。list_id が必要です。name、description は任意です。

delete-list -- タスクリストと、そのすべてのタスクを論理削除します。list_id が必要です。破壊的な操作です。

list-tasks -- タスクリスト内のタスクを一覧表示します。list_id が必要です。status フィルター、assignee フィルター、sort_by（created、updated、name、priority、status）、sort_dir、limit（1-200）、offset、format に対応しています。

create-task -- リストに新しいタスクを作成します。list_id と title（1-500 文字）が必要です。description（最大 5000 文字）、status（pending、in_progress、complete、blocked）、priority（0=なし、1=低、2=中、3=高、4=緊急）、assignee_id（プロファイル ID — 保留中のメンバーも指定できます）、dependencies（タスク ID の配列）、node_id（ファイル／フォルダー／ノートへのリンク）は任意です。

task-details -- 特定のタスクの全詳細を取得します。list_id と task_id が必要です。format に対応しています。

update-task -- タスクのタイトル、説明、ステータス、優先度、担当者（保留中のメンバーを含む）、依存関係、またはノードリンクを更新します。list_id と task_id が必要です。

delete-task -- タスクを論理削除します。list_id と task_id が必要です。破壊的な操作です。

change-status -- タスクのステータスを変更します。list_id、task_id、status が必要です。

assign-task -- タスクの割り当て、または割り当て解除を行います。list_id と task_id が必要です。割り当てるには assignee_id（保留中のメンバーを含むプロファイル ID）を渡します。割り当てを解除するには null を渡すか、省略します。

bulk-status -- 複数のタスクのステータスを一度に変更します。list_id、task_ids（タスク ID の配列、最大 100 件）、status が必要です。

move-task -- 同じプロファイル内の別のリストにタスクを移動します。list_id（移動元のリスト）、task_id、target_task_list_id（移動先のリスト）が必要です。sort_order（移動先リスト内の位置、デフォルトは 0）は任意です。移動元と移動先のリストは、同じプロファイルに属している必要があります。old_task_list_id と new_task_list_id を含む、更新後のタスクを返します。

reorder-tasks -- リスト内のタスクを並べ替えます。list_id と task_ids（表示順に並べたタスク ID の配列）が必要です。サーバーはこれを {order: [{id, sort_order}, ...]} に変換して API に渡します。

reorder-lists -- ワークスペースまたは共有内のタスクリストを並べ替えます。profile_type、profile_id、list_ids（表示順に並べたタスクリスト ID の配列）が必要です。サーバーはこれを {order: [{id, sort_order}, ...]} に変換して API に渡します。

filtered-list -- カテゴリーで絞り込んだタスクを一覧表示します。profile_type、profile_id、filter（"assigned"、"created"、"status"）が必要です。filter が "status" の場合は、status パラメーターも必要です。limit、offset、format に対応しています。

summary -- ワークスペースまたは共有のタスク数を簡潔に取得します。profile_type と profile_id が必要です。タスクの総数、ステータス別の内訳、自分に割り当てられたタスク数、自分が作成したタスク数を返します。format に対応しています。

worklog

エージェントの作業を追跡するためのアクティビティログです。アップロード、タスクの変更、共有の作成、その他の重要な操作を行った後、実行した内容とその理由を記録します。人間と AI が検索できる監査証跡を作成できます。すべての worklog アクションを実行するには、対象エンティティでワークフローが有効になっている必要があります。

append -- worklog に新しいエントリーを追加します。entity_type（"task"、"task_list"、または "profile"）、entity_id、content（1～10000 文字）が必要です。変更を行った後、実行した内容とその理由を記録するために使用します。エントリーは作成後に変更できません。

list -- worklog エントリーの一覧を取得します。entity_type（"task"、"task_list"、または "profile"）と entity_id（該当エンティティの不透明な ID、または entity_type が "profile" の場合は 19 桁の profile ID）が必要です。type フィルター（"info" または "interjection"）、sort_dir（"asc" または "desc"、デフォルトは "desc"）、limit（1～200）、offset、format（Markdown の場合は "md"）に対応しています。

interject -- 確認が必要な緊急の interjection エントリーを作成します。entity_type（"task"、"task_list"、または "profile"）、entity_id、content（1～10000 文字）が必要です。interjection は優先度の高い修正であり、常に緊急として扱われます。

details -- 特定の worklog エントリーの詳細をすべて取得します。entry_id が必要です。format に対応しています。

acknowledge -- interjection エントリーを確認済みとしてマークします。entry_id が必要です。acknowledgable: true のエントリーのみ確認できます。

unacknowledged -- 未確認の interjection（acknowledgable が true のエントリー）を一覧表示します。entity_type（"task"、"task_list"、または "profile"）と entity_id が必要です。limit、offset、format に対応しています。作業を進める前に、必ず未確認の interjection を確認してください。

profile-list -- profile レベルのすべての worklog エントリーを一覧表示します。profile_type と profile_id が必要です。limit、offset、format に対応しています。エンティティ単位の一覧を取得する list とは異なります。

filtered-list -- カテゴリーで絞り込んだ worklog を一覧表示します。profile_type、profile_id、filter（"authored" または "interjections"）が必要です。エントリーの種類によるサブフィルターとして、任意の type（"info" または "interjection"）を指定できます。limit、offset、format に対応しています。

summary -- ワークスペースまたは共有の worklog 件数の概要を取得します。profile_type と profile_id が必要です。エントリー総数、エントリーの種類別内訳、自分が作成したエントリー数、保留中の interjection 数を返します。format に対応しています。

承認

タスク、ストレージノード、作業記録エントリ、または共有に関連付けられた正式な承認リクエストです。すべての承認操作では、対象エンティティでワークフローが有効になっている必要があります。

list -- ワークスペースまたは共有の承認リクエストを一覧表示します。profile_type と profile_id が必要です。status フィルター（pending、approved、rejected）、limit（1～200、デフォルトは50）、offset、format に対応しています。

create -- 新しい承認リクエストを作成します。profile_type、profile_id、entity_type（「task」、「node」、「worklog_entry」、または「share」）、entity_id、description（1～65535文字）が必要です。approver_id（指定する承認者のプロファイル ID。保留中のメンバーも指定できます）、deadline（YYYY-MM-DD HH:MM:SS — ISO-8601 形式ではありません）、node_id（成果物の参照）は任意です。

details -- 承認者リストや決定内容を含む、承認リクエストの詳細を取得します。profile_type、profile_id、approval_id（不透明な英数字の ID）が必要です。format に対応しています。

resolve -- 承認リクエストに決定を下します。profile_type、profile_id、approval_id、resolve_action（「approve」または「reject」）が必要です。comment（最大5000文字）は任意です。指定された承認者のみが決定できます。

bulk-create -- 共有内のすべてのファイルとノートについて、ノードの承認リクエストを一括作成します（最大50ノード）。profile_id と description（1～65535文字）が必要です。approver_id（保留中のメンバーも指定できます）と deadline（YYYY-MM-DD HH:MM:SS — ISO-8601 形式ではありません）は任意です。共有のみで利用でき、メンバーと管理者のみが実行できます。

bulk-approve -- 共有内の保留中の承認リクエストをすべて一括承認します。profile_id が必要です。comment（最大5000文字）は任意です。古くなった承認リクエスト（version_match=false）はスキップされます。ゲストは割り当てられた承認リクエストを承認できます。

bulk-reject -- 共有内の保留中の承認リクエストをすべて一括却下します。profile_id が必要です。comment（最大5000文字）は任意です。古くなった承認リクエスト（version_match=false）はスキップされます。ゲストは割り当てられた承認リクエストを却下できます。

filtered-list -- カテゴリで絞り込んだ承認リクエストを一覧表示します。filter（「pending」、「created」、「assigned」、または「resolved」）が必要です。ワークスペースまたは共有の範囲を指定する場合は profile_type と profile_id を指定します。どちらも省略すると、プロファイルをまたいだユーザーレベルの表示になります（/user/approvals/list/{filter}）。注：assigned フィルターは profile_type と profile_id を指定した場合にのみ利用でき、プロファイルをまたいだユーザーレベルのクエリには対応していません。status サブフィルター、limit、offset、format に対応しています。

summary -- ワークスペースまたは共有の承認件数を簡潔に表示します。profile_type と profile_id が必要です。自分が作成したものと自分に割り当てられたものについて、保留中、承認済み、却下済みの件数を返します。format に対応しています。

update -- 保留中の承認リクエストを更新します。profile_type、profile_id、approval_id が必要です。description（1～65535文字）、approver_id（保留中のメンバーも指定できます）、deadline（YYYY-MM-DD HH:MM:SS — ISO-8601 形式ではありません）、node_id、properties（JSON オブジェクト）のうち、少なくとも1つを指定する必要があります。保留中の承認リクエストのみ更新できます。status、entity_type、entity_id、profile_id は変更できません。

delete -- 承認リクエストを完全に削除します（ステータスは問いません）。profile_type、profile_id、approval_id が必要です。取り消しできません。メンバーと管理者のみ実行でき、ゲストは実行できません。

bulk-delete -- 共有内のすべての承認リクエストを完全に削除します（最大500件）。profile_id が必要です。保留中と解決済みの両方を削除します。メンバーと管理者のみ実行でき、ゲストは実行できません。

todo

ワークスペースおよび共有に紐づく、シンプルなフラット形式のチェックリストです。ネストには対応していません。すべての todo アクションでは、対象エンティティでワークフローが有効になっている必要があります。

list -- ワークスペースまたは共有の todo を一覧表示します。profile_type と profile_id が必要です。filter_done（ブール値）、sort_by（created、updated、title）、sort_dir、limit（1～200、デフォルトは100）、offset、format に対応しています。

create -- 新しい todo 項目を作成します。profile_type、profile_id、title（1～500文字）が必要です。assignee_id は任意です（参加待ちのメンバーを指定できます）。

details -- todo の詳細情報を取得します。todo_id（英数字の不透明なID）が必要です。format に対応しています。

update -- todo を更新します。todo_id が必要です。title、assignee_id（参加待ちのメンバーを指定できます）、done に対応しています。

delete -- todo を論理削除します。todo_id が必要です。破壊的な操作です。

toggle -- todo の完了状態を切り替えます。todo_id が必要です。完了と未完了が切り替わります。

bulk-toggle -- 複数の todo の完了状態を一括設定します。profile_type、profile_id、todo_ids（todo ID の配列、最大100件）、done（ブール値：完了にする場合は true、未完了にする場合は false）が必要です。

filtered-list -- カテゴリで絞り込んだ todo を一覧表示します。profile_type、profile_id、filter（「assigned」、「created」、「done」、「pending」のいずれか）が必要です。limit、offset、format に対応しています。

summary -- ワークスペースまたは共有の todo 件数を簡潔に取得します。profile_type と profile_id が必要です。合計、完了、未完了、自分に割り当てられた項目、自分が作成した項目の件数を返します。format に対応しています。

apps

インタラクティブな MCP App ウィジェットの検出と起動を行います。ウィジェットは、エージェントとの会話内に表示されるインタラクティブな HTML5 UI です。

list -- 利用可能なすべての MCP App ウィジェットと、そのメタデータ（タイトル、説明、対応ツール、対応アクション、リソース URI）を一覧表示します。

details -- 特定のウィジェットのメタデータをすべて取得します。app_id（ウィジェット名。例：「file-picker」）が必要です。

launch -- ワークスペースまたは共有のコンテキストでウィジェットを起動します。app_id、profile_type（「workspace」または「share」）（context_type も指定可能）、profile_id（19桁のプロファイル ID）（context_id も指定可能）が必要です。描画可能なウィジェットの HTML コンテンツを返します。

get-tool-apps -- 特定のツールドメインに関連付けられたウィジェットを検索します。tool_name（例：「storage」、「ai」、「comment」）が必要です。そのツールの操作用 UI を提供するウィジェットを返します。

---

10. Code Mode（ヘッドレスエージェント）

ヘッドレスエージェント（Claude Code、Cursor、Continue など）から接続すると、サーバーは Code Mode を自動的に有効にします。これは、19個すべてのツールを提供するモードに代わる軽量なモードです。Code Mode が公開するツールは全部で4つです。

ツール	用途
auth	認証（サインイン、サインアップ、API キー、PKCE、2FA）
upload	ファイルのアップロード（チャンク分割、テキスト、Web インポート）
search	コンテンツ（ファイル、ノート、フォルダー）の検索、または API エンドポイントの検出
execute	認証済みの API 呼び出しを Fast.io に実行

MCP Apps に対応したクライアント（Claude Desktop、Cline）には引き続き、19個すべてのツールに加え、6個の app-* ウィジェットツール（レジストリ内の各ウィジェットにつき1つ）が提供されます。不明なクライアントには、デフォルトで全ツールが提供されます。

コンテンツを検索する（最初にこちらを使用）

ユーザーが Fast.io のデータについて「X を探して」「Y はどこにある」「Z を持っていますか」と尋ねた場合は、target を設定せずに search を呼び出してください（デフォルトは content です）。execute を使って /storage/search/ の呼び出しを手動で組み立てないでください。search ツールは適切なエンドポイントを呼び出し、ワークスペースを横断して検索し、結果を正規化します。

search query="tax return 2023"                               (fan out across ALL workspaces)
search query="Q3 budget" workspace_id="1234567890123456789"  (scoped to one workspace)
search query="invoice" share_id="9876543210987654321"        (scoped to one share)
search query="meeting notes from last quarter" details=true  (semantic, with full node details)

結果の形式：

{
  "results": [
    { "id": "<30-char node id>", "type": "file", "name": "tax-return-2023.pdf",
      "parent_id": "<folder id>", "workspace_id": "1234…",
      "score": 0.87, "snippet": "…2023 tax return for…" }
  ],
  "total": 1,
  "scope": { "type": "workspace", "workspace_ids": ["1234…"] },
  "next_offset": 50
}

キーワード検索とセマンティック検索： ワークスペースのインテリジェンスがオフ（デフォルト）の場合、検索対象はファイル名とフォルダー名のみです。高速で無料です。インテリジェンスがオンの場合、同じエンドポイントでインデックス済みのドキュメントコンテンツに対するセマンティック（RAG）検索も実行され、score フィールドと snippet フィールドが返されます。インテリジェンスを有効にするには、execute POST /workspace/{id}/update/ intelligence=true を実行します。インデックス作成のコストはドキュメントのページあたり約 10 クレジットです。クエリ自体は無料です。

セマンティック検索の絞り込み： folders_scope（nodeId:depth のペア。深度は 1～10）を渡すと、結果をサブツリーに限定できます。または、files_scope（nodeId:versionId のペア）を渡すと、特定のファイルバージョンに限定できます。インテリジェンスがオフの場合、どちらも無視されます。

スコープ：

• workspace_id が指定されている場合 → 単一ワークスペースを検索し、limit／offset によるページネーションを使用します。
• share_id が指定されている場合 → 単一の共有を検索します。
• どちらも指定されていない場合 → アクセス可能な上位 10 件のワークスペースを並列に検索します（同時実行数 4）。横断検索ではページネーションを利用できません。より深くページネーションするには、明示的に workspace_id を渡してください。

search ツール（API エンドポイントの検索）

コードモードツール（auth、upload、コンテンツモードの search）でラップされていない REST エンドポイントを呼び出す必要がある場合は、target を "api" に切り替えて API 仕様を検索します。メソッド、パス、パラメーター、説明を含む一致したエンドポイントが返されます。選んだパスを execute に渡してください。

search target="api" query="list files in workspace" tag="storage"
search target="api" query="create share" tag="share"
search target="api" query="authentication"
search target="api" query="pagination" include_concepts=true

パラメーター（すべてのモード）：

• query（string、必須）-- キーワード、エンドポイントパス、または概念（api モード）、もしくは検索したいもの（content モード）
• target（enum、任意）-- "content"（デフォルト）または "api"

パラメーター（content モードのみ）：

• workspace_id（string、任意）-- 検索対象を 1 つのワークスペースに限定する 19 桁のワークスペース ID
• share_id（string、任意）-- 検索対象を 1 つの共有に限定する 19 桁の共有 ID
• limit（number、任意）-- 結果の最大件数。1～200（デフォルトは単一スコープで 50、横断検索ではワークスペースごとに 25）
• offset（number、任意）-- 単一スコープ検索のページネーションオフセット
• details（boolean、任意）-- ノードの詳細情報（プレビュー、AI の状態、メタデータ）を含めます。デフォルトは false
• folders_scope（string、任意）-- セマンティック検索をフォルダーのサブツリーに限定します（インテリジェンスが必要）
• files_scope（string、任意）-- セマンティック検索を特定のファイルバージョンに限定します（インテリジェンスが必要）

パラメーター（api モードのみ）：

• tag（string、任意）-- ドメインで絞り込みます：auth、workspace、storage、ai、share、upload、org、user、member、comment、event、metadata など
• include_concepts（boolean、任意）-- 概念に関するドキュメント（ページネーション、ID、エラー）を含めます。デフォルトは true

execute ツール

認証済みの API 呼び出しを Fast.io REST API に対して実行します。エンドポイントを見つけるには、まず search を使用してください。

メソッド：

• get -- オプションのクエリパラメーターを指定した GET リクエスト
• post -- フォームエンコードされた本文を使用する POST（デフォルトの API 形式）
• postJson -- JSON 本文を使用する POST
• delete -- DELETE リクエスト
• put -- フォームエンコードされた本文を使用する PUT

認証トークンは自動的に挿入されます。パスパラメーターは呼び出し側で設定する必要があります（{workspace_id} を実際の ID に置き換えてください）。複数のステップからなる操作では、execute を複数回、順番に呼び出してください。

execute method="get" path="/org/1234567890123456789/list/workspaces/"

execute method="post" path="/workspace/1234567890123456789/storage/root/createfolder/" body={"name": "reports"}

execute method="postJson" path="/workspace/1234567890123456789/storage/root/createnote/" body={"name": "summary.md", "content": "# Summary"}

パラメーター：

• method（enum、必須）-- HTTP メソッド："get"、"post"、"postJson"、"delete"、"put"
• path（string、必須）-- API エンドポイントのパス（例：'/orgs/list/'、'/workspace/{workspace_id}'）
• body（object、任意）-- リクエスト本文（post／put ではフォームエンコード、postJson では JSON）
• params（object、任意）-- URL に追加するクエリパラメーター
• timeout_ms（number、任意）-- タイムアウト（ミリ秒。デフォルトは 30000、最大は 60000）

レスポンスの処理

execute ツールは、次の3種類のレスポンスを自動的に処理します。

• JSON（ほとんどのエンドポイント） -- 標準的な Fast.io API エンベロープとして解析されます
• テキスト（Markdown、プレーンテキストなど） -- { content, content_type, http_status } として返されます
• バイナリ（画像、PDF など） -- download:// MCP リソースを使用するための案内とメタデータを返します

コードモードでのノートの読み取り

/read/（生のバイナリを返します）の代わりに、/readnote/（JSON を返します）を使用します。

execute method="get" path="/workspace/{workspace_id}/storage/{node_id}/readnote/"

ノート以外のアップロードファイルを読み取る場合は、download:// MCP リソースを使用します。

resources/read uri="download://workspace/{workspace_id}/{node_id}"