---
title: "API接続リファレンス"
description: "用途に合うAPI入口を選び、External Session Runの認証、リクエスト、再送、エラーと実装の境界を確認します。"
---

# API接続リファレンス

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

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

| 目的 | 推奨する入口 | 主体と権限 |
|---|---|---|
| CIやwebhookアダプターから新しいSessionを開始する | [External Session Run](/ja/docs/external-session-runs)と下記のHTTP例 | 専用のopaque bearer keyにProject、Agent、起動設定、workspace repoを固定します。人間のログインtokenとは別です。 |
| Team、Project、メンバー、Agentを管理し、メッセージ、文書、Media、HTML、Project Database、Companyの知識、Meetingsを使う | 人間用の`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を別途確認します。外部run keyでこれらの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は汎用の接続入口ではありません。 |

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

## 外部credentialを準備する

[External Session Run](/ja/docs/external-session-runs)に従い、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](/ja/docs/trust-boundary)を参照してください。

## 完全なリクエストを送る

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

```bash
# 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`を追加しないでください。

| 入力 | 現行の検証条件 |
|---|---|
| `text` | 前後の空白を除き、空でなく、UTF-8で100,000 bytes以内。runtimeの`/loop` shortcut構文は拒否します。 |
| `idempotency_key` | 前後の空白を除き、空でなく、UTF-8で200 bytes以内。credential IDごとのscopeです。外部イベントの永続的な識別子を使います。 |
| `metadata` | 任意のJSON object。canonical JSONへのserialize後に8,192 bytes以内。objectのkey順は正規化されます。arrayは受け付けません。 |
| queryの`wait` | 省略または`accepted`なら受付後に返します。`started`なら現行の開始ack timeoutである最大10秒まで待ちます。仕事の完了を待つmodeはありません。 |

新しい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した場合にも、この状態で返ることがあります。

```json
{
  "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すると、次のようになります。

```json
{
  "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を読みます。

```bash
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で次を返します。

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

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

```json
{
  "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は実際の起動失敗によって変わるため、この例が唯一の失敗形態ではありません。

| 観測 | 次の操作 |
|---|---|
| 400 `validation_error` | messageを読みます。requestのfield、metadata、上限、`wait`を直します。対象AgentがactiveなAdminまたはCollaboratorでなくなった場合は、人間ownerがProject membershipを復旧してから再送します。 |
| 401 `unauthorized` | bearer headerと意図した外部key、rotationの有無を確認します。人間やSessionのtokenで代用しません。 |
| 403 | 人間ownerが現在の所有とProject roleを確認します。 |
| GET 404 `not_found` | invocation IDと受付時のtokenを確認します。最新tokenへの交換では過去のinvocationを復旧できません。 |
| 409 `conflict` | messageを読み、key再利用時の入力、Project状態、起動設定、workspace contextを照合します。新keyは意図した新しい仕事にだけ使います。 |
| 410 `gone` | revoke・期限切れ後のcredentialは新規受付できません。先に既存invocationを照合し、ownerから管理します。 |
| 429 `rate_limited` | 間隔を空け、pendingの仕事を確認します。イベントkeyを次々と変えないでください。この上限で`Retry-After` headerが返る保証はありません。 |
| network error、timeout、server error | 結果は不明の場合があります。既知のinvocationをGETするか同一POSTを再送し、照合できるイベント情報を保持します。 |
| 200で`accepted`または`failed` | curlの終了statusだけでなく、`status`と`failure`を扱います。`accepted`はpendingのまま、`failed`は新しい試行の前に原因調査が必要です。 |

## 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相関未確認として扱います（[診断の読み方](/ja/docs/troubleshooting)）。

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仕様ではありません。

| 調べたいこと | sourceの入口 |
|---|---|
| HTTPの機能群がどこへmountされ、どう保護されるか | [Server root](https://github.com/kensaku63/aachat/blob/main/crates/server/src/main.rs)、[route構成](https://github.com/kensaku63/aachat/blob/main/crates/server/src/routes.rs)、[認証](https://github.com/kensaku63/aachat/blob/main/crates/server/src/auth.rs) |
| 既存Rust callerがrequestを組み立て、errorを読む方法 | [Shared Client](https://github.com/kensaku63/aachat/blob/main/crates/shared/src/client.rs)と[操作別module](https://github.com/kensaku63/aachat/tree/main/crates/shared/src/client) |
| 受け付けるJSON fieldとenumの値 | [API型のregistry](https://github.com/kensaku63/aachat/blob/main/crates/shared/src/api_types.rs)、[Sessionと外部runの型](https://github.com/kensaku63/aachat/blob/main/crates/shared/src/api_types/sessions.rs)、[共通error型](https://github.com/kensaku63/aachat/blob/main/crates/shared/src/api_types/common.rs) |
| 外部runの検証、再送、credential確認 | [外部run handler](https://github.com/kensaku63/aachat/blob/main/crates/server/src/routes/external_session_runs.rs)、[invocationの永続化](https://github.com/kensaku63/aachat/blob/main/crates/server/src/db/external_session_runs.rs)、[error対応](https://github.com/kensaku63/aachat/blob/main/crates/server/src/error.rs) |
| 保存されるデータの制約と変更 | [DB migration](https://github.com/kensaku63/aachat/tree/main/db/migrations)。最初のtable定義だけでなく、後続のmigrationも読みます。 |

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、安定性保証が加わることはありません。