エージェント

エージェント（agent） は登録された AI コーディングエージェントで、独立した主体ではなく、あるユーザーの委任された identity です。キャプチャされたセッションは所有者に帰属し、所有者のワークスペース可視性を継承します。エージェントを登録すると、その単一の Agent Access Token（AAT） も発行されます。これは、エージェントが活動を取り込む際に使う書き込み専用の資格情報です。そのトークンを消費するエンドポイントは Agent ingest を参照してください。

エージェントの管理は対話的なサーフェスです。以下の変更系エンドポイントはログイン済みの session を必要とし、呼び出し元自身のエージェントにのみ作用します。平文のトークンシークレット（spantail_aat_…）は作成時とローテーション時に 一度だけ 返され、その後は取得できません。

エージェントオブジェクト

フィールド	型	説明
`id`	string	一意の識別子。
`type`	string	エージェントの種別: `claude_code`、`codex`、`cursor`、`other`。
`name`	string	表示名（1〜100 文字）。
`createdAt`	string	ISO 8601 の作成時刻。
`disabledAt`	string \| null	設定されている間、エージェントは一時停止され、トークンは ingest で拒否されます。
`archivedAt`	string \| null	設定されているとアーカイブ済み（取り消し不可）。
`token`	object \| null	アクセストークンの概要（下記）。

トークン概要はシークレットやそのハッシュを一切公開しません。

フィールド	型	説明
`lastUsedAt`	string \| null	トークンが最後に ingest に使われた ISO 8601 時刻。
`expiresAt`	string \| null	ISO 8601 の有効期限。期限なしの場合は `null`。

エージェントの一覧

GET /api/v1/agents

必要な認証はクエリによって異なります。

クエリなし session only — 呼び出し元自身のエージェントを新しい順で返します。対話的なセッションが必要です。
?ownerUserId=<id> scope: admin — インスタンス管理者 が他ユーザーのエージェントを読み取ります。

所有者の userId とトークンハッシュは決して返されません。

クエリパラメータ

名前	型	必須	説明
`ownerUserId`	string	いいえ	インスタンス管理者のみ: 特定ユーザーのエージェントを一覧。

curl
Response

curl "https://<your-instance>/api/v1/agents" \
  -H "Cookie: <your session cookie>"

[
  {
    "id": "agt_bot",
    "type": "claude_code",
    "name": "Build bot",
    "createdAt": "2026-06-28T09:30:00.000Z",
    "disabledAt": null,
    "archivedAt": null,
    "token": {
      "lastUsedAt": "2026-06-28T10:15:00.000Z",
      "expiresAt": null
    }
  }
]

エージェントの登録

POST /api/v1/agents session only

呼び出し元が所有するエージェントを登録し、その単一のアクセストークンを発行します（エージェントとトークンは 1:1）。ワークスペースは関与しません: セッションがどこに記録されるかは、各 ingest ペイロードが指定します（エージェント ingest を参照）。平文の secret はこのレスポンスで 一度だけ 返されます。

リクエストボディ

フィールド	型	必須	説明
`type`	string	はい	エージェントの種別: `claude_code`、`codex`、`cursor`、`other`。
`name`	string	はい	表示名（1〜100 文字）。
`expiresInDays`	integer	いいえ	トークンの有効日数（1〜3650）。省略すると期限なし。

curl
Response

curl -X POST "https://<your-instance>/api/v1/agents" \
  -H "Cookie: <your session cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "claude_code",
    "name": "Build bot"
  }'

{
  "id": "agt_bot",
  "type": "claude_code",
  "name": "Build bot",
  "createdAt": "2026-06-28T09:30:00.000Z",
  "disabledAt": null,
  "archivedAt": null,
  "token": {
    "lastUsedAt": null,
    "expiresAt": null
  },
  "secret": "spantail_aat_9f8c2b1a4d6e0f3c5a7b9d1e2f4a6c8e"
}

201 Created を返します。

エージェントの無効化・有効化

PATCH /api/v1/agents/:id session only

disabled を切り替えてエージェントを一時停止・再開します。無効の間、エージェントのトークンは ingest で拒否され、再有効化すると元に戻ります。これは（アーカイブと違い）取り消し可能です。エージェントオブジェクトを返します。

リクエストボディ

フィールド	型	必須	説明
`disabled`	boolean	はい	`true` で一時停止、`false` で再開。

curl -X PATCH "https://<your-instance>/api/v1/agents/agt_bot" \
  -H "Cookie: <your session cookie>" \
  -H "Content-Type: application/json" \
  -d '{ "disabled": true }'

エージェントのアーカイブ

DELETE /api/v1/agents/:id session only

エージェントをアーカイブし、そのトークンを直ちに無効化します。204 No Content を返します。

アクセストークンのローテーション

POST /api/v1/agents/:id/token/rotate session only

有効期限を保ったまま、エージェントのトークンシークレットをその場で再生成します。古いシークレットは直ちに使えなくなります。新しい平文の secret は一度だけ返されます。

curl
Response

curl -X POST "https://<your-instance>/api/v1/agents/agt_bot/token/rotate" \
  -H "Cookie: <your session cookie>"

{
  "secret": "spantail_aat_1d3f5a7c9e0b2d4f6a8c0e2b4d6f8a0c"
}