API接続リファレンス

CIや別のアプリケーションをaachatへ接続するとき、またはCLIとWebUIがサーバーへ接続する仕組みを調べるときに使うページです。外部からの入口は用途で分かれます。ClaudeやChatGPTなど認証済みの外部AIからは Connected apps（リモートMCP）、CIや別システムのイベントからは Webhook Trigger、人間・Agentの通常の操作は aachat / chat CLIを使い、CLIリファレンスから始めてください。sourceにrouteが存在することや、/v1というprefixは、安定した第三者向けAPI、互換性の維持期間、バージョン移行方針を保証しません。

用途と認証主体から入口を選ぶ

目的	推奨する入口	主体と権限
ClaudeやChatGPTなどの外部AIから、ProjectとSessionを読み、追加指示・Lead Agentへの新規Session起動を行う	Connected apps（リモートMCP `https://api.aachat.io/mcp`）	OAuthで接続した本人のidentityで、接続時に許可したTeamと本人の現在の閲覧・実行権限に限られます。提供される操作は`list_projects`、`read_project`、`list_sessions`、`read_session`、`send_followup`、`start_session`の6つです。新規Sessionの起動には、ProjectのLeadが本人のactiveなAgentで、その実行環境が準備済みであることが必要です。外部AIは会話での本人の明示指示に基づいて書き込み、接続の同意は書込の指示を兼ねません。
CIやwebhookアダプターからSessionまたは公開済みWorkflowを開始する	Webhook Triggerと設定ガイド	Trigger専用のBearer secretで、設定されたSessionまたはWorkflowを起動します。人間のログインtokenとは別です。
Team、Project、メンバー、Agentを管理し、メッセージ、文書、Media、HTML、Project Database、Team Wikiを使う	人間用の`aachat` CLIとWebUI。repository開発では既存shared Client	ログインした人間のidentityに対して、Team/Projectのroleと操作ごとの権限を確認します。認証だけでは書込・管理権限を得られません。
実行中Sessionからメッセージ、Ask、文書、Workflow/Trigger、delivery receiptなどを扱う	Sessionに提供される`chat` CLIと投影された契約	SessionのAgent identity、Project coverage、現行membership、lifecycleを確認します。Session tokenは汎用サービスcredentialではありません。
対話的なSession、Workflow、Triggerを開始・継続・確認する	CLI/WebUIの操作と既存Client method	routeに応じた人間またはSessionのidentity。起動、所有、Project scopeを別途確認します。Webhook secretでこれらのAPIを操作することはできません。
DiscoverのAgent、Skill、Templateや、意図して共有された内容を読む	公開WebUIと発行されたshare URL	一部の読取は匿名で可能です。インストール、公開、投票、共有管理には別途認証と所有確認があります。share tokenの権限は対象の内容scopeに限られます。
WebUI、runtime、aachatの基盤を実装する	既存WebUI API層、shared Client、syncとrealtimeの実装	内部client/runtime protocol、使い切りrealtime ticket、または専用server/worker権限を使います。control/admin routeやprovider webhookは汎用の接続入口ではありません。

Webhook Triggerは新しい仕事を開始します。Projectデータの自由な閲覧、任意Sessionの継続、permissionの承認、Agentの管理に使う汎用API keyではありません。第三者のwebhookから仕事を開始したい場合は、自分のアダプターでproviderのイベントを受信・検証してからWebhook Triggerを呼びます。aachatのprovider専用webhookへ任意のイベントを送らないでください。

Webhook Triggerで外部から起動する

Projectの Triggers でWebhookを作成し、Sessionまたは公開済みWorkflowを選び、Trigger詳細の Connect a sender に従ってsecretを設定します。送信元設定・JSON入力・{{ webhook.metadata }}・制限・状態取得・secret交換はWebhookガイドを参照してください。

表示された /v1/triggers/{id}/webhook へ Authorization: Bearer <secret> と Content-Type: application/json 付きでJSONをPOSTします。本文の例です。

json

{"idempotency_key":"issue-123-opened","metadata":{"issue":123}}

secretをコマンド引数や共有されるlogへ展開しないでください。

どちらの起動先も任意のmetadataを受け取り、Session Triggerはさらに任意のtext、Workflow Triggerは任意のinputを受け取ります。イベントごとに安定した idempotency_key を使います。新規受付は202、同じ要求の再送は200で元のtargetを返し、同じkeyで内容が違えば409です。返された status_url は現在の同じsecretで読み取ります。受付はRuntime起動や仕事の成功を保証しません。429ではRetry-Afterを待って同じkeyで再送します。prompt・metadata・logにsecretを含めないでください。

失敗時の本文は{"error":{"code":"...","message":"..."}}の形です。code（例: 検証エラーのinvalid_input）と HTTP status で分岐し、messageの文言には依存しないでください。

以前あったProjectごとのrun keyで外部からSessionを起動するAPIは削除されました。CIや別システムからの起動にはWebhook Triggerを使います。外部AIの会話から仕事を始める場合はConnected appsを使います。

HTTP相関IDとredirectの境界

対応serverのX-Aachat-Request-Id応答headerは、HTTP試行を照合するための情報です。curlでは--dump-header <保存先>で応答headerを別に保存できます。既知のoccurrenceをGETする場合など、権限のある読取で取得し、ID取得のためにPOSTを重ねないでください。header保存先は実際のlocal fileに置き換え、共有前に秘密情報がないか確認します。

requestに有効な単一UUIDの同名headerがあればserverは採用し、欠落・不正・重複なら新しいUUIDを応答します。必須の認証headerではなく、権限や重複実行防止を付与しません。再送は上のidempotency_keyとoccurrence照合の手順を使います。headerや診断fieldが取得できない場合はserver相関未確認として扱います（診断の読み方）。

aachat組込Rust API clientは別originへのredirectを追わず、同originは従来の上限付き追従を保ちます。Webのaachat API fetchは同originを含む全redirectを拒否します。この制約は通常のpage navigation、外部storage grantの取得、利用者自身のcurl一般に適用する説明ではありません。API接続先やproxyがredirectを返す場合は、管理者/supportと最終的な正規API接続先と応答を確認します。header保護を外す回避や、結果不明の書込の無条件再送は行いません。

既存の実装を読む

以下のsourceリンクは、repositoryへのアクセス権を持つ開発者向けの任意の参照です。kensaku63/aachatは非公開repositoryのため、閲覧にはアクセス権のあるGitHubアカウントでのログインが必要です。匿名で開いたリンクが404でも、それだけでsourceの削除やAPI障害を意味するわけではありません。

外部接続にsourceの閲覧は必要ありません。sourceを読めない場合も、接続設定はWebhook Trigger、通常の操作はCLIリファレンス、問題の切り分けはトラブルシューティングへ進めます。

repository開発では、既存client methodからmountされたroute、request/response型、認可、永続化へ操作を辿ります。調べるserver/clientに対応するsource revisionを使ってください。以下はrepositoryのmain branchへの読取入口であり、別にversion管理されたSDK仕様ではありません。

調べたいこと	sourceの入口
HTTPの機能群がどこへmountされ、どう保護されるか	Server root、route構成、認証
既存Rust callerがrequestを組み立て、errorを読む方法	Shared Clientと操作別module
受け付けるJSON fieldとenumの値	API型のregistry、Sessionの型、共通error型
保存されるデータの制約と変更	DB migration。最初のtable定義だけでなく、後続のmigrationも読みます。

Team/Project/membership、messages/search/timeline、共有文書と成果物、Team Wiki、Session/permission/wait、Workflow/Trigger、Discover/publicationには対応するrouteと型のmoduleがあります。無関係なHTTP literalをコピーせず、自分の用途の機能群を辿ってください。WebUI専用の読取とruntimeの書込は、serverが同じでも置き換えられません。

control/admin endpoint、開発用login、sync/runtime delivery、worker/gateway認可、provider webhook payload、realtime protocolは、第三者が呼び出す例としては掲載していません。これらのcomponentへ貢献するときは、それぞれの実装と配備契約を使ってください。このreferenceによって別のSDK、OpenAPI generator、安定性保証が加わることはありません。