AgenTrux API Reference

A2A (Agent-to-Agent) プロトコルで公開しているエンドポイントのリファレンスです。

Base URL: https://api.agentrux.com

目次

1. 認証フロー概要
2. クレデンシャル一覧
3. Discovery — /.well-known + /a2a
4. Auth — /auth
5. Data Plane — /topics
6. Console — /console
7. エラーレスポンス
8. Webhook 通知

認証フロー概要

1. Activation Code を redeem（1 度だけ）
   POST /auth/redeem-activation-code  { "code": "act_..." }
        → { client_id: "crd_...", client_secret: "aks_...", script_id, issued_at }

2. アクセストークン取得（script 実行ごと）
   POST /oauth/token  (form: grant_type=client_credentials&client_id=crd_...&client_secret=aks_...)
        → { access_token: "aat_..." (JWT), expires_in: 600, ... }

3. Pub/Sub操作
   POST /topics/{id}/events   (publish — Authorization: Bearer aat_...)
   GET  /topics/{id}/events   (read/poll)
   GET  /topics/{id}/events/stream  (SSE)

4. リフレッシュ（authorization_code / device_code grant のみ）
   POST /oauth/token  (form: grant_type=refresh_token&refresh_token=art_...)
   （client_credentials は refresh token を発行しない — 再度 /oauth/token を呼ぶ）

5. クロスアカウント共有（Console 操作のみ、 Phase Z 2026-05-22）
   Topic owner: POST /console/aliases/{ali_id}/share-trust  {grantee_email}
   Grantee:    POST /console/grants  {topic_id, script_id, action}
   （旧 invite_code anonymous トークンは廃止、 受領 user は事前登録必須）

クレデンシャル一覧

Discovery

GET /a2a

ヘルスチェック。認証不要。

Response 200

{
  "status": "ok",
  "version": "0.1.0",
  "timestamp": "2026-03-11T12:00:00+00:00"
}

GET /.well-known/agent-card.json

A2A Agent Card（JSON）。認証不要。エージェントがこのカードを読むだけで AgenTrux を自律的に利用できる。

Auth

認証・トークン発行エンドポイント。いずれも JWT 不要（ボディにクレデンシャルを含む）。

POST /auth/redeem-activation-code

ワンタイムの Activation Code（act_）を redeem し、永続的な Script credential を取得する。

Request

{
  "code": "act_Abc123..."
}

Response 200

{
  "client_id": "crd_550e8400-e29b-41d4-a716-446655440000",
  "client_secret": "aks_xxxxxxxx",
  "script_id": "scr_...",
  "issued_at": "2026-03-11T12:00:00+00:00"
}

client_secret（aks_）は 1 度だけ返却されます。

重要: client_id（crd_）と client_secret（aks_）は永続的に保存してください。redeem は 1 回限り。紛失時は Console で新しい act_ を発行。

POST /oauth/token

Bearer アクセストークンを取得する。form-encoded（application/x-www-form-urlencoded）、OAuth 2.1。

Request（grant_type=client_credentials）

grant_type=client_credentials&client_id=crd_...&client_secret=aks_...

Response 200

{
  "access_token": "aat_eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "topic:top_<uuid>:read topic:top_<uuid>:write"
}

grant_type=client_credentials は refresh_token を返しません。aat_ 失効時（約10分）は再度 /oauth/token を呼びます。

JWT クレーム

発行される JWT には以下のクレームが含まれます:

POST /oauth/token（grant_type=refresh_token）

refresh token をローテーションして新しいアクセストークンを取得する。refresh token は authorization_code / device_code grant のみが発行（client_credentials には refresh leg なし — 再度 /oauth/token を呼ぶ）。旧 refresh token は即時無効化される。

Request（form-encoded）

grant_type=refresh_token&refresh_token=art_xxxxxxxx&client_id=...

Response 200

{
  "access_token": "aat_eyJhbGciOi...",
  "refresh_token": "art_yyyyyyyy",
  "token_type": "Bearer",
  "expires_in": 600
}

重要: リフレッシュ後は必ず新しい refresh_token を保存してください。旧トークンは即時無効化されます。

クロスアカウント共有（Console 操作のみ、 Phase Z 2026-05-22）

旧 inv_ anonymous トークンは廃止されました。 登録済 user をグループに招待する場合は POST /console/group-invites/redeem を使います（招待された user が自身の Console session で redeem します）。 クロスアカウントのトピック / スクリプトアクセスは Console の 2 段操作で確立します（受領者は AgenTrux に登録済の user である必要があります）。

1. Topic オーナー: POST /console/aliases/{ali_id}/share-trust body { "grantee_email": "..." } で AliasTrust を確立。
2. 受領者: 自身の Console session で POST /console/grants { topic_id, script_id, action } を呼んで Grant を作成。

Script の貸与（delegated execution）には POST /console/scripts/{scr_id}/share { grantee_email } を使うと、サーバが script_delegations 行を直接作成します。

Data Plane

トピックへのイベント Publish / Subscribe。全エンドポイントで JWT 認証が必要です。

Authorization: Bearer <access_token>

JWT のスコープ: topic:{topic_id}:read または topic:{topic_id}:write

GET /topics

このスクリプトがアクセスできるトピック一覧を、人間可読な名前付きで返します。 ワークフロープラグイン(MCP, Agent SDK 等)が Console (Kratos) API を経由せずにトピックセレクタを表示するために使います。

Auth: 有効なスクリプト JWT。レスポンスは JWT の scope クレームから生成 され、DB 側の追加認可は行いません。

Request

GET /topics
Authorization: Bearer <access_token>

Response 200

{
  "items": [
    {
      "topic_id": "top_019d5ec8-dc41-7723-9761-6a40eacc858a",
      "name": "oc-command",
      "display_name": "OpenClaw Command",
      "retention_seconds": 86400,
      "actions": ["read", "write"]
    }
  ]
}

結果は (name, topic_id) でソートされ、ワークフロー側で位置を保存しても 安定します。同一トピックに read と write の両方を持つ場合は 1 エントリに まとめられ、actions: ["read", "write"] となります。ソフト削除済みの トピックは静かに除外されるため、古い grant がドロップダウンを壊すことは ありません。

GET /console/grants

現在の Console セッションで参照できる grant を、トピックメタデータと結合 して返します。管理画面や診断 UI 向け、つまり「自分はどの権限を持ち、誰が 発行し、どんな上限があるか」を表示するためのエンドポイントです。ワークフロー プラグイン側のドロップダウンには GET /topics を優先してください。

Auth: Console セッション（Kratos）。これはスクリプト JWT の data-plane ではなく Console プレーンのエンドポイントです。

Request

GET /console/grants
Cookie: <console session>

Response 200

{
  "items": [
    {
      "grant_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "topic_id": "top_019d5ec8-dc41-7723-9761-6a40eacc858a",
      "topic_name": "oc-command",
      "topic_display_name": "OpenClaw Command",
      "action": "read",
      "grantor_alias_id": "...",
      "description": "OpenClaw command bus",
      "rate_limit_per_min": 60,
      "daily_limit": 10000,
      "created_at": "2026-04-08T17:52:48+00:00"
    }
  ]
}

アクティブな (topic, action) ごとに 1 エントリ返されます。ワイルドカード (topic_id = "*")の grant 行は返りません — build_scope_with_grants が JWT 発行時にトピック毎へ展開済みで、ワイルドカード行そのものは直接呼び 出せないためです。ソフト削除された grant / トピック、および JWT scope の 範囲外の grant は除外されます。ソート順は (topic_name, action, grant_id)。

POST /topics/{topic_id}/events

トピックにイベントを Publish する。

Auth: topic:{topic_id}:write

Request

{
  "event_type": "sensor.reading",
  "payload": {"temperature": 23.5, "unit": "celsius"},
  "metadata": {"source": "edge-01"}
}

payload（インラインパス）または payload_object_id（オブジェクト参照パス）のいずれか一方を指定します（両方は不可）。

Response 200

{
  "event_id": "evt_...",
  "topic_id": "top_...",
  "stored_at": "2026-03-11T12:00:00+00:00",
  "ttl_expires_at": "2026-03-12T12:00:00+00:00",
  "payload_kind": "inline",
  "inline_size_bytes": 48,
  "next_read_cursor": "..."
}

オブジェクト参照パスでは payload_kind が "object_ref" となり、レスポンスには inline_size_bytes の代わりに payload_object_id（pob_...）と size_bytes が含まれます。

GET /topics/{topic_id}/events

カーソルベースのページネーションでイベントを取得する。

Auth: topic:{topic_id}:read

Query Parameters

Response 200

{
  "events": [
    {
      "event_id": "evt_...",
      "event_type": "sensor.reading",
      "stored_at": "2026-03-11T12:00:00+00:00",
      "ttl_expires_at": "2026-03-12T12:00:00+00:00",
      "payload_kind": "inline",
      "payload": {"temperature": 23.5},
      "producer_script_id": "scr_...",
      "cursor": "..."
    }
  ],
  "next": {
    "after": "<opaque-cursor>",
    "before": null,
    "has_more": true,
    "url": "/topics/top_.../events?after=...&limit=100",
    "frontier": "<opaque-cursor>"
  },
  "topic": {
    "topic_id": "top_...",
    "oldest_available_evt_id": "evt_..."
  }
}

イベントはトップレベルの events 配列で返されます。ページングには next.after の opaque cursor トークンを使います（evt_id 文字列ではありません）。 これを after クエリパラメータに渡すか、next.url をそのまま辿ることで次ページを 取得します。next オブジェクトはさらに before（逆方向の opaque cursor、なければ null）、has_more（真偽値）、frontier（現在の watermark cursor、新着イベントの ポーリング用）を持ちます。topic オブジェクトは topic_id と oldest_available_evt_id（トピックが空の場合は null）を返します。各イベントも自身の cursor を持ちます。

読み取り系（本エンドポイント、GET /events/{event_id}、 GET /payloads/{object_id}）は、月次 egress クォータを使い切ると details.metric = "egress_bytes" を伴う 402 PAYMENT_REQUIRED を返します。

GET /topics/{topic_id}/events/stream

SSE (Server-Sent Events) で新しいイベントの hint 通知を受け取る。

Auth: topic:{topic_id}:read

Query Parameters / Headers

Response 200 text/event-stream

event: hint
id: <opaque-cursor>
data: {"topic_id":"top_...","event_id":"evt_...","ts":"2026-01-01T00:00:00Z","producer_script_id":"scr_..."}

: keepalive

• Hint のみ: SSE はイベントの存在を通知するだけで、ペイロードは含みません。実際のイベント取得には GET /topics/{topic_id}/events を使ってください。
• Keepalive: 30 秒ごとにコメント行 (: keepalive) が送信されます。
• 再接続: 最後に受信した id: の値（opaque cursor）を Last-Event-ID ヘッダに設定して再接続してください。サーバが decode して再開します。順序は保証されないため event_id で重複排除してください。

GET /topics/{topic_id}/events/{event_id}

単一のイベントを ID で取得する。

Auth: topic:{topic_id}:read

Response 200

{
  "event_id": "evt_...",
  "event_type": "sensor.reading",
  "stored_at": "2026-03-11T12:00:00+00:00",
  "ttl_expires_at": "2026-03-12T12:00:00+00:00",
  "payload_kind": "inline",
  "payload": {"temperature": 23.5},
  "producer_script_id": "scr_...",
  "cursor": "..."
}

履歴イベントのバックフィル

by-sequence 専用エンドポイントはありません。ネットワーク断後に欠損した イベントを補填するには、カーソルベースの read GET /topics/{topic_id}/events?after=<cursor> をページングで使い、 最後に正常処理したカーソルから再開してください。

POST /topics/{topic_id}/payloads

外部ペイロードのメタデータを作成し、署名付きアップロード URL を取得する。

Auth: topic:{topic_id}:write

Request

{
  "content_type": "application/octet-stream",
  "size_bytes": 1048576,
  "checksum_sha256": "abc123..."
}

Response 201

{
  "object_id": "...",
  "upload_url": "https://...",
  "expiration": "2026-03-12T12:00:00+00:00"
}

upload_url に対して PUT リクエストでファイルをアップロードしてください。

GET /topics/{topic_id}/payloads/{object_id}

ペイロードのメタデータと署名付きダウンロード URL を取得する。

Auth: topic:{topic_id}:read

Response 200

{
  "object_id": "...",
  "content_type": "application/octet-stream",
  "size": 1048576,
  "hash": "sha256:abc123...",
  "download_url": "https://...",
  "expiration": "2026-03-12T12:00:00+00:00"
}

Console

コンソール（Web UI）用のエンドポイントです。Kratos によるセッション認証が必要です。

GET /console/connections/sse

Composer 用の SSE エンドポイント。現在のユーザーの Alias が所有またはアクセス権を持つトピックのイベント通知をリアルタイムでストリーミングします。コンソールの Composer でライブ更新に使用されます。実際のイベント取得には GET /console/topics/{topic_id}/events を使ってください。

Auth: セッション Cookie（Kratos）— ユーザーがアクティブな Alias を通じてトピックの read アクセス権を持っている必要があります。

Query Parameters / Headers

Response 200 text/event-stream

event: hint
id: <opaque-cursor>
data: {"topic_id":"top_...","event_id":"evt_...","ts":"2026-01-01T00:00:00Z","producer_script_id":"scr_..."}

: keepalive

• GET /topics/{topic_id}/events/stream と同じ SSE 形式ですが、JWT の代わりにセッション認証を使用します。
• Last-Event-ID: 再接続時、ブラウザが自動的に最後に受信した id: の値を Last-Event-ID ヘッダに設定して送信するため、シームレスに再開できます。
• Keepalive: 30 秒ごとにコメント行 (: keepalive) が送信され、接続を維持します。

AccountResponse

アカウント関連のコンソールエンドポイントが返す AccountResponse スキーマには以下のフィールドが含まれます:

これらのプロフィール項目は PATCH /console/me/profile に変更したいプロフィール項目を含む JSON ボディを送ることで更新できます。

エラーレスポンス

全エンドポイント共通のエラーフォーマットです。

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid credentials"
  }
}

Webhook 通知

トピックにイベントが publish されると、登録済みの Webhook URL に通知が送信されます（管理コンソールで設定）。

Payload

{
  "topic_id": "top_...",
  "event_id": "evt_...",
  "timestamp": 1710151200,
  "delivery": "webhook"
}

署名検証

X-AgenTrux-Signature ヘッダに timestamp と HMAC-SHA256 署名が含まれます（Stripe 互換形式）。

X-AgenTrux-Signature: t={timestamp},v1={hex_digest}

検証方法:

1. ヘッダから t（unix timestamp）と v1（hex 署名）をパース
2. サブスクリプションの Webhook シークレットをキーに HMAC-SHA256(secret, "{t}." + リクエストボディ) を計算
3. v1 と定数時間比較で照合