API接続リファレンス

CIや別のアプリケーションをaachatへ接続するとき、またはCLIとWebUIがサーバーへ接続する仕組みを調べるときに使うページです。外部システムから新しい仕事を開始する場合は External Session Run を使います。通常の人間・Agentの操作はCLIリファレンスから始めてください。sourceにrouteが存在することや、/v1というprefixは、安定した第三者向けAPI、互換性の維持期間、バージョン移行方針を保証しません。

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

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

外部credentialを準備する

External Session Runに従い、ProjectのWebUIで Start from external app を開きます。管理できるのはAgentの現在の人間ownerであり、その人間がProjectのactiveなAdminまたはCollaboratorである必要があります。AgentもProjectのactiveなAdminまたはCollaboratorでなければなりません。Projectはactiveで、ownerのruntimeが固定された起動設定とworkspace repositoryで対象Agentを開始できることが前提です。

作成responseにはkey、token、run_urlが含まれます。画面では後ろの2つをAACHAT_API_KEYとAACHAT_API_URLとして表示します。ここでのAACHAT_API_URLはserver originだけではなく、/v1/external/session-runsで終わる完全なPOST URLです。配備先のhostnameを推測せず、返されたURLを使ってください。生のkeyは作成・rotation時に一度表示され、credential一覧からは取得できません。呼出し元のsecret storeに保存します。人間のログインtoken、Session token、GitHub token、内部worker secretをこの欄へ転用しないでください。

run endpoint自身がAuthorization: Bearer <key>を読み、このリクエストを人間のJWTとして認証することはありません。serverは外部keyのhashを保存します。promptとmetadataはinvocationのデータになるため、いずれにも秘密情報を含めず、ログにも残さないでください。保存と実行の境界はTrust Boundaryを参照してください。

完全なリクエストを送る

次のshell例には--fail-with-body対応のcurl、信頼できるcredential URL、環境変数へ読み込んだkeyが必要です。送信すると、そのcredentialのProjectで実際の仕事が始まります。ファイルはCIイベントの例であり、live tokenは含みません。仕事の内容とイベント識別子を自分のものに置き換え、再送用に同じrequestを保持してください。

# AACHAT_API_URL and AACHAT_API_KEY come from the credential creation screen.
# AACHAT_API_URL is the complete run_url, without a query string.
: "${AACHAT_API_URL:?Set the credential run_url}"
: "${AACHAT_API_KEY:?Load the key from your secret store}"

cat > external-run.json <<'JSON'
{
  "text": "Inspect the CI failure for commit abc123 and report findings in the project.",
  "idempotency_key": "ci:example/repo:12345:attempt-1",
  "metadata": {
    "source": "ci",
    "repository": "example/repo",
    "run_id": "12345"
  }
}
JSON

curl --silent --show-error --fail-with-body \
  --request POST "${AACHAT_API_URL}?wait=started" \
  --header "Authorization: Bearer ${AACHAT_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data-binary @external-run.json

JSON bodyで受け付けるのはtext、idempotency_key、任意のmetadataだけです。未知のfieldは拒否されます。credentialを上書きするためにagent_id、project、mode、launch、workspace_repoを追加しないでください。

新しいinvocationはcredentialごとに60秒間で30件、pending（accepted）は5件までです。これは実装上の上限であり、処理能力の保証ではありません。同一requestの再送は、新規invocation向けのこれらの確認より前に既存invocationを返します。

responseを読み、同じ呼出しを再確認する

成功したPOSTとGETはHTTP 200 とinvocation bodyを返します。以下は省略記号のないresponse形状の例で、ID、時刻、app hostnameは例示です。値のない任意fieldは省略され、必ずnullとして出るわけではありません。

受付状態は次のようになります。wait=startedの待機がtimeoutした場合にも、この状態で返ることがあります。

{
  "invocation_id": "11111111-1111-4111-8111-111111111111",
  "project": { "team": "example", "name": "ci-checks" },
  "agent_id": "22222222-2222-4222-8222-222222222222",
  "accepted_at": "2026-09-06T09:00:00Z",
  "status": "accepted"
}

runtimeが開始をackすると、次のようになります。

{
  "invocation_id": "11111111-1111-4111-8111-111111111111",
  "project": { "team": "example", "name": "ci-checks" },
  "agent_id": "22222222-2222-4222-8222-222222222222",
  "session_id": "33333333-3333-4333-8333-333333333333",
  "accepted_at": "2026-09-06T09:00:00Z",
  "status": "started",
  "web_url": "https://app.example.test/t/example/projects/ci-checks?session=33333333-3333-4333-8333-333333333333"
}

startedが示すのはSessionの起動です。仕事の完了、CI成功、code delivery、mergeの成功ではありません。返されたweb_urlを開いて仕事を追います。acceptedでもSessionが既に紐づいている場合があるため、startedより前にsession_idとweb_urlが含まれることもあります。

invocation_idを保存し、新しいSessionを開始せずに同じinvocationを読みます。

INVOCATION_ID='11111111-1111-4111-8111-111111111111' # Replace with the returned ID.
curl --silent --show-error --fail-with-body \
  --header "Authorization: Bearer ${AACHAT_API_KEY}" \
  "${AACHAT_API_URL}/${INVOCATION_ID}"

GETは同じresponse型を返します。読取scopeはcredentialの現在のtokenではなく、そのinvocationを受け付けたときのtokenです。invocationが存在しない場合や、tokenが受付時のものと一致しない場合は404になります。bearer tokenの欠落・形式不正は401です。

再送、rotation、revokeを使い分ける

POSTのresponseを失ったら、同じcredentialとidempotency_keyで元のrequestを再送します。invocation_idを既に持っている場合は、先にGETしてください。network timeoutやacceptedだけを理由に新しいイベントkeyを生成すると、別の仕事が作られる可能性があります。

requestの比較には、正規化されたtext、metadata、固定された起動設定とworkspace contextが含まれます。同じkeyを異なる入力で再利用すると409になります。JSON objectのkey順は正規化されますが、値の変更は異なる入力です。終端のfailedも同一requestの再送でそのまま返り、再送によって再起動することはありません。failureと紐づくSessionを調べ、原因を直してから、意図して新しく試行する場合だけ新しいidempotency keyを使ってください。

• Revoke・期限切れ: 新規invocationを止めます。受付済みinvocationは受付時のtokenで引き続き読めます。そのtokenがcredentialを識別できる間は、同一POST再送でも既存結果を取得できます。revokeは受付済みの仕事の取消でも、その読取権限の消去でもありません。
• Rotate: activeなcredentialのtokenを変更します。revoke済み・期限切れのcredentialはrotateできないため、新しく作成します。旧tokenは再送を含むPOSTでcredentialを識別できなくなります。旧tokenで受け付けたinvocationは、引き続きその旧tokenでGETできます。新tokenではそれらをGETできません。同じcredential IDに対して、新tokenと同じidempotency keyで同じ入力をPOSTすると、既存invocationが返る場合があります。
• 再発行: 別のcredential identityを作ります。idempotencyはcredentialをまたいで重複を排除しません。置き換えたcredentialで送り直す前に、残っている仕事を照合してください。

新しい仕事では、Projectがactiveか、作成者が現在もAgentを所有しProjectのメンバーか、AgentがProjectのactiveなメンバーかも再確認します。keyでこれらの関係変更を迂回することはできません。合わなくなった場合は権限を持つ人間ownerから設定し直してください。復旧に必要な間は受付時のtokenも秘密として保護し、診断の証拠として公開しないでください。

エラーと復旧

HTTP requestの拒否はerror envelopeで返り、invocationのfailureとは別です。例えばrequestのmetadataを[]にすると、HTTP 400で次を返します。

{
  "error": {
    "code": "validation_error",
    "message": "metadata must be an object when provided."
  }
}

受付後に起動に失敗したinvocationは、HTTP 200のまま返ることがあります。例えば、開始前に対象Projectがactiveでなくなった場合です。

{
  "invocation_id": "11111111-1111-4111-8111-111111111111",
  "project": { "team": "example", "name": "ci-checks" },
  "agent_id": "22222222-2222-4222-8222-222222222222",
  "accepted_at": "2026-09-06T09:00:00Z",
  "status": "failed",
  "failure": {
    "code": "conflict",
    "message": "Target project is no longer active. Reissue the external session run key for an active project."
  }
}

失敗responseにも、紐づいたsession_idとweb_urlが含まれる場合があります。再起動を決める前に確認してください。failure codeとmessageは実際の起動失敗によって変わるため、この例が唯一の失敗形態ではありません。

HTTP相関IDとredirectの境界

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

requestに有効な単一UUIDの同名headerがあればserverは採用し、欠落・不正・重複なら新しいUUIDを応答します。必須の認証headerではなく、権限や重複実行防止を付与しません。再送は上のidempotency_keyとinvocation照合の手順を使います。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保護を外す回避や、結果不明の書込の無条件再送は行いません。

既存の実装を読む

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

Team/Project/membership、messages/search/timeline、共有文書と成果物、Company/registry/meetings、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、安定性保証が加わることはありません。