AAO ディレクトリ API

agenticadvertising.org の AAO ディレクトリは、オープンウェブ全体でパブリッシャー adagents.json ファイルをインデックスします。この API は、すべてのセールスエージェントオペレーターが同期時に必要とする 逆マップ を表示します:

「どのパブリッシャーが私のエージェントを認可したか?」

このエンドポイントなしでは、オペレーターはパブリッシャードメインリストを手動で保守し fetch_agent_authorizations をそれに対して呼ぶか、オープンウェブを自分でクロールしなければなりません。両方ともマネージドネットワークスケールでは実行不可能です（cafemedia だけで単一のマネージャーファイルの下に約 6,800 のパブリッシャードメインを委譲）。このエンドポイントは ディスカバリー であり、認可ではありません。パブリッシャー自身の adagents.json がトラストルートのままです。ディレクトリは、どのパブリッシャーを SDK のドメインごとプリミティブ（verify_agent_authorization、fetch_agent_authorizations）経由で直接検証すべきかを伝えます。

エンドポイント

GET https://{aao_directory}/v1/agents/{agent_url}/publishers

{agent_url} はパーセントエンコードされなければなりません（MUST）。ディレクトリは、SDK が verify_agent_authorization で適用するのと同じ規約を使って、ルックアップキーを正準化します（小文字ホスト、デフォルトポート除去、パスコンポーネントの末尾スラッシュ正規化）。

クエリパラメーター

Parameter	Type	Default	Semantics
`since`	ISO 8601	未設定	`last_verified_at` ≥ `since` のパブリッシャーのみを返す。増分同期を可能にする。
`cursor`	不透明文字列	未設定	先のレスポンスが返したページネーションカーソル。カーソルの寿命の間、ディレクトリのリフレッシュサイクル全体で安定。
`status`	string、繰り返し	`authorized`	ライフサイクルステータスでフィルター。v1: `authorized`、`revoked`。値ごとにキーを 1 回繰り返す（OpenAPI `style: form, explode: true`）。カンマ区切り単一値形式（`status=authorized,revoked`）は受け入れられない。ディレクトリは繰り返しキー形式を指す説明とともに `400` を返さなければならない（MUST）。
`limit`	int（1–1000）	200	ページあたり最大パブリッシャー数。
`include`	string、繰り返し	未設定	拡張されたロウごとフィールドにオプトイン。v1: `properties` — 各 `PublisherEntry` がそのパブリッシャーの下の正準 `property_ids[]` リストを運ぶ（消費者が数比較だけでなくフェデレーテッドフェッチに対して完全な集合差分を実行できる）。繰り返しキー形式、`status` と同じエンコードルール。未知の値は `400` を返す。

実例: 複数のステータス値でフィルター

GET /v1/agents/https%3A%2F%2Fsales-agent.example.com%2F/publishers?status=authorized&status=revoked&limit=500

TypeScript での同等物:

const url = new URL(`${directory}/v1/agents/${encodeURIComponent(agentUrl)}/publishers`);
url.searchParams.append("status", "authorized");
url.searchParams.append("status", "revoked");
url.searchParams.set("limit", "500");

Python（requests）での同等物:

requests.get(
    f"{directory}/v1/agents/{quote(agent_url, safe='')}/publishers",
    params=[("status", "authorized"), ("status", "revoked"), ("limit", "500")],
)

status パラメーターの OpenAPI フラグメント:

- in: query
  name: status
  schema:
    type: array
    items:
      type: string
      enum: [authorized, revoked]
  style: form
  explode: true
  required: false

繰り返しキーが選ばれたのは、(a) それが URLSearchParams.append() と OpenAPI のデフォルト explode: true が生成するもので、(b) カンマを含みうる将来の値ときれいに合成し、(c) ディレクトリでパーサーの曖昧性を残さないからです。

実例: 完全な集合差分のため `?include=properties` を要求

GET /v1/agents/https%3A%2F%2Fsales-agent.example.com%2F/publishers?include=properties

デフォルトレスポンスは properties_authorized を数としてのみ運びます。数の等価は集合の等価では ありません: 3 つのプロパティをローテートするパブリッシャーは数を変えないまま集合を完全に異なるものにし、数ベースの分岐検出器はそれを見られません。?include=properties は PublisherEntry ごとに property_ids: list[string] フィールドを追加します — そのパブリッシャーの下でエージェントのセレクターが解決する正準 ID — 消費者がフェデレーテッド fetch_agent_authorizations 結果に対して集合として完全な集合差分を実行し、大きさの差分だけでなくローテーションを検出できるように。フラグはデフォルトページペイロードを小さく保つためオプトインです。インライン ID はパブリッシャーごとのプロパティ数 × 約 16 バイト/ID を追加します。マネージドネットワーク親ファイル（約 6,800 パブリッシャー × 平均 1 プロパティ ≈ 追加 7 KB の ID）では、オーバーヘッドは小さいが非ゼロです。ページネーションセマンティクスは変わりません。

レスポンス

{
  "agent_url": "https://sales-agent.example.com",
  "directory_indexed_at": "2026-05-19T12:00:00Z",
  "publishers": [
    {
      "publisher_domain": "recipeswithessentialoils.com",
      "discovery_method": "ads_txt_managerdomain",
      "manager_domain": "cafemedia.com",
      "properties_authorized": 1,
      "properties_total": 1,
      "signing_keys_pinned": false,
      "status": "authorized",
      "last_verified_at": "2026-05-19T08:00:00Z"
    },
    {
      "publisher_domain": "wsj.com",
      "discovery_method": "direct",
      "manager_domain": null,
      "properties_authorized": 47,
      "properties_total": 200,
      "signing_keys_pinned": true,
      "status": "authorized",
      "last_verified_at": "2026-05-19T10:00:00Z"
    },
    {
      "publisher_domain": "former-partner.example",
      "discovery_method": "authoritative_location",
      "manager_domain": "cafemedia.com",
      "properties_authorized": 0,
      "properties_total": 0,
      "signing_keys_pinned": false,
      "status": "revoked",
      "last_verified_at": "2026-05-19T11:00:00Z"
    }
  ],
  "next_cursor": "eyJv..."
}

?include=properties では、各 PublisherEntry が追加で property_ids を運びます:

{
  "publisher_domain": "recipeswithessentialoils.com",
  "discovery_method": "ads_txt_managerdomain",
  "manager_domain": "cafemedia.com",
  "properties_authorized": 3,
  "properties_total": 3,
  "property_ids": ["p-001", "p-002", "p-003"],
  "signing_keys_pinned": false,
  "status": "authorized",
  "last_verified_at": "2026-05-19T08:00:00Z"
}

フィールドリファレンス

エンベロープ

Field	Required	Notes
`agent_url`	yes	ルックアップキーの正準化エコー。
`directory_indexed_at`	yes	結果セット内の最新のパブリッシャーごとリフレッシュ。消費者自身のキャッシュのプロベナンス。空のページでは NULL — レポートするアンカーがない。消費者は null 値からキャッシュ鮮度を進めるべきでない（SHOULD NOT）。
`publishers`	yes	配列。空配列は有効なレスポンス — ディレクトリはこのエージェントをインデックスしたが現在の認可が解決しない。
`next_cursor`	optional	不透明ページネーションカーソル。終端ページでは不在または null。

`PublisherEntry`

Field	Required	Notes
`publisher_domain`	yes	`adagents.json` がエージェントを認可するパブリッシャー。
`discovery_method`	yes	`direct`、`authoritative_location`、`adagents_authoritative`、または `ads_txt_managerdomain`。下記参照。
`manager_domain`	conditional	`discovery_method` ≠ `direct` のとき必須。それ以外は null。
`properties_authorized`	yes	エージェントのセレクターが解決するこの publisher_domain のみの下のプロパティ数。決してネットワーク全体の数ではない。
`properties_total`	yes	パブリッシャーのファイル（またはそのドメインの親ファイルのインラインサブセット）内のこの publisher_domain のみの下のプロパティ数。決してネットワーク全体の数ではない。
`property_ids`	conditional	リクエストが `?include=properties` を含んだとき、かつそのときのみ存在。エージェントのセレクターがこのパブリッシャーの下で解決する `property_id` の正準リスト — `properties_authorized` が数える同じ集団を、消費者がフェデレーテッドフェッチに対して完全な集合差分（数比較だけでなく）を実行できるよう ID として表示。パブリッシャーごとスコープ。決してネットワーク全体でない。集合として扱う。順序は未指定。
`signing_keys_pinned`	optional	パブリッシャーがこのエージェントに `signing_keys[]` をピン留めするか。`true` のとき、エージェントの署名付きレスポンスはエージェント自身の JWKS にかかわらずピン留めされた集合に対して検証されなければならない（MUST）。
`status`	yes	`authorized` または `revoked`。下記参照。
`last_verified_at`	yes	ディレクトリがこのパブリッシャーの `adagents.json` を最後にフェッチし検証したとき。

`discovery_method` 値

Value	Meaning	Trust profile
`direct`	パブリッシャー自身の `/.well-known/adagents.json` にエージェントがリストされている。	最強 — 委譲ホップなし。
`authoritative_location`	パブリッシャーの `/.well-known/adagents.json` が、エージェントをリストするマネージャーファイルを指す `authoritative_location` を宣言。	強 — パブリッシャーが積極的に委譲。
`adagents_authoritative`	マネージャーファイル自身の `properties[]` がパブリッシャーのドメインを運ぶことで発見（adcp#4825 インライン解決ルールに従い）。	中 — パブリッシャーはマネージャーファイルで名指されたが委譲を自身でホストしなかった。
`ads_txt_managerdomain`	マネージャーファイルを指すパブリッシャーの `ads.txt` `MANAGERDOMAIN=` ディレクティブ経由で発見。	最弱 — `managerdomain` フォールバック安全ルールが唯一の肯定的クロスチェック。

ディレクトリは discovery_method: ads_txt_managerdomain のロウを返す前に managerdomain 安全ルールを検証します — これがオペレーターごとの ads.txt クロールに対するディレクトリの主な付加価値です。

`status` 値

Value	Meaning
`authorized`	セレクターがこの publisher_domain の下で 1 つ以上のプロパティに解決する。通常のケース。
`revoked`	パブリッシャーが以前エージェントを認可し、今や権威ファイルの `revoked_publisher_domains[]` にこの `publisher_domain` をリストする。失効が着地した後の最初の同期でトゥームストーンとして発行され、その後ドロップ。オペレーターが各パブリッシャーのキャッシュ TTL をポーリングせずに失効を伝播できる。

unbound、pending、unreachable、no_properties は 意図的に v1 の一部でありません。ディレクトリは adagents.json が正常にフェッチされエージェントを参照するパブリッシャーのみをインデックスします。パブリッシャーが消えた場合、ディレクトリはトゥームストーンを返すのではなく結果からそれをドロップします（消費者は先のページに対する集合差分でメンバーシップを追跡）。

HTTP セマンティクス

Status	Meaning
`200 OK`	ルックアップ成功。ボディは空の `publishers[]` を持ってもよい（MAY）。
`400 Bad Request`	不正な形式の `agent_url`、無効なカーソル、未知の `status` 値、または繰り返しキーではなくカンマ区切りリストとして供給された `status`。
`404 Not Found`	ディレクトリはこの `agent_url` を参照するパブリッシャーを決してインデックスしていない。`200` + 空とは区別される（それはディレクトリがこのエージェントをインデックスしたが現在の認可が解決しないことを意味する）。
`429 Too Many Requests`	レート制限。`Retry-After` ヘッダーが設定される。バケットキー: `agent_url`（匿名）プラス IP（多層防御）。
`5xx`	ディレクトリエラー。消費者はバックオフでリトライすべき（SHOULD）。

エンドポイントは Cache-Control と ETag を設定します。条件付き GET（If-None-Match）がワイヤーレベルのキャッシュメカニズムです。ボディの directory_indexed_at が消費者ロジックの鮮度アンカーです。

認証

V1 は未認証です。パブリッシャー adagents.json ファイルは公開です。逆マップは公開です。レート制限が IP ベースからアイデンティティベースに卒業する場合、パスはエージェントの公開 JWKS をキーとする RFC 9421 リクエスト署名を重ねる別の RFC です — エージェントはリクエストに署名することで agent_url を制御することを証明します。この RFC の範囲外。

ページネーション

カーソルは不透明です。置換可能な文字列として扱い、そのまま返してください。ディレクトリは通知なしにカーソル形式を変更してもよい（MAY）。消費者はカーソル内容を解析してはなりません（MUST NOT）。カーソルは少なくとも 1 つのディレクトリリフレッシュサイクルの間有効なままです。それを過ぎると、ディレクトリは cursor_expired を伴う 400 または最初からの再走査を伴う 200 を返してもよい（MAY） — 両方とも適合。消費者は先のリクエストの実時間を記録し、24 時間より古いカーソルの使用を拒否すべきです（SHOULD）。

他のプリミティブとの関係

AAO ディレクトリは既存の SDK プリミティブを補完します:

Question	Primitive	Direction
このエージェントはこのパブリッシャーの `adagents.json` にリストされているか?	`verify_agent_authorization(adagents_data, agent_url)`	プッシュ（パブリッシャー → エージェント）
パブリッシャーのリストが与えられたとき、どれが私のエージェントを認可するか?	`fetch_agent_authorizations(agent_url, publisher_domains)`	プル、呼び出し元供給リスト
どのパブリッシャーが私のエージェントを認可するか?	`GET /v1/agents/{agent_url}/publishers`	プル、ディレクトリ供給リスト

最初の 2 つは、オペレーターが既にパブリッシャー集合を知っている質問に答えます。ディレクトリエンドポイントはオペレーターの実際の同期時の質問に答えます: 「私のパブリッシャー集合は何か?」推奨ワークフロー:

GET /v1/agents/{agent_url}/publishers を呼んでパブリッシャー集合を発見。
レスポンスの各 publisher_domain について、オペレーターはトラストルートに対して再確認するためパブリッシャー自身の adagents.json に対して verify_agent_authorization を呼んでもよい（MAY）。ディレクトリの last_verified_at はクリティカルパスでのドメインごと検証の必要性を減らすが排除しない。
レスポンスの properties_authorized / properties_total をオペレーター向けスコープサマリーに、signing_keys_pinned フラグをどのエージェントがパブリッシャーのピンに一致する JWKS を公開しなければならないかを表示するために使う。
分岐検出器（ディレクトリとパブリッシャーのライブ adagents.json が不一致のケースを捕捉）を実行するオペレーターは、?include=properties を要求し、ディレクトリの property_ids[] をフェデレーテッドフェッチに対して数ではなく集合として比較すべき（SHOULD）。N プロパティをローテートするパブリッシャーは両側で等しい数を生成する。集合比較のみがそれを捕捉する。

`publisher_properties` インライン解決との関係

マネージドネットワーク型親ファイル（adcp#4825 インライン解決ルールに従い）では、ディレクトリは publisher_domain でフィルターされた親ファイルのインライン properties[] から properties_total を計算します。このスケールでの厳格なフェデレーションは、ディレクトリリフレッシュごとパブリッシャーごとに N HTTP フェッチを要求します — オペレーターが持つのと同じスケール問題が 1 レイヤー上に移動しただけ。ディレクトリは仕様が承認するインライン解決ルールを使います。

範囲外（v1）

認証。 公開エンドポイント、匿名レート制限。アイデンティティバウンドの制限は必要なら別の RFC で到達。
クロスディレクトリフェデレーション。 単一ディレクトリ。エンドポイント形状は、複数の AAO 互換ディレクトリがそれを実装できるよう定義されている。どのディレクトリをクエリするかのディスカバリーは今日は構成。
新しい認可のプッシュ通知。 ポーリングベースの v1。
完全なプロパティオブジェクトのインライン。 ?include=properties は解決された property_ids[] のみを返す — プロパティオブジェクト自体ではない。ID を持つ消費者は既存のドメインごとプリミティブ経由で詳細をフェッチできる。

はじめに

AdCP で構築する

プロトコル

FAQ

トラストとセキュリティ

リファレンス

AAO

認定

AAO ディレクトリ API — エージェント ↔ パブリッシャー逆引き

AAO ディレクトリ API

エンドポイント

クエリパラメーター

実例: 複数のステータス値でフィルター

実例: 完全な集合差分のため `?include=properties` を要求

レスポンス

フィールドリファレンス

エンベロープ

`PublisherEntry`

`discovery_method` 値

`status` 値

HTTP セマンティクス

認証

ページネーション

他のプリミティブとの関係

`publisher_properties` インライン解決との関係

範囲外（v1）

関連項目

​AAO ディレクトリ API

​エンドポイント

​クエリパラメーター

​実例: 複数のステータス値でフィルター

​実例: 完全な集合差分のため ?include=properties を要求

​レスポンス

​フィールドリファレンス

​エンベロープ

​PublisherEntry

​discovery_method 値

​status 値

​HTTP セマンティクス

​認証

​ページネーション

​他のプリミティブとの関係

​publisher_properties インライン解決との関係

​範囲外（v1）

​関連項目

AAO ディレクトリ API

エンドポイント

クエリパラメーター

実例: 複数のステータス値でフィルター

実例: 完全な集合差分のため `?include=properties` を要求

レスポンス

フィールドリファレンス

エンベロープ

`PublisherEntry`

`discovery_method` 値

`status` 値

HTTP セマンティクス

認証

ページネーション

他のプリミティブとの関係

`publisher_properties` インライン解決との関係

範囲外（v1）

関連項目