AdCP — Registry API

The AgenticAdvertising.org registry provides a public REST API for resolving brands and properties, discovering agents, and validating authorization in the AdCP ecosystem.

Base URL

https://agenticadvertising.org

Most endpoints are public and require no authentication. Authenticated endpoints require a Bearer token. The full OpenAPI 3.1 specification is available for code generation and tooling. It is also discoverable at /.well-known/openapi.yaml.

Quick Start

Resolve a brand domain to its canonical identity:

curl "https://agenticadvertising.org/api/brands/resolve?domain=acmecorp.com"

const res = await fetch(
  "https://agenticadvertising.org/api/brands/resolve?domain=acmecorp.com"
);
const brand = await res.json();
console.log(brand.brand_name, brand.canonical_domain);

import requests

brand = requests.get(
    "https://agenticadvertising.org/api/brands/resolve",
    params={"domain": "acmecorp.com"}
).json()
print(brand["brand_name"], brand["canonical_domain"])

Response

{
  "canonical_id": "acmecorp.com",
  "canonical_domain": "acmecorp.com",
  "brand_name": "Acme Corp",
  "keller_type": "master",
  "house_domain": "acmecorp.com",
  "source": "brand_json"
}

Rate Limits

Endpoint	Limit
Brand bulk resolve (`/api/brands/resolve/bulk`)	20 requests and 100 unique domain resolutions/minute per IP; 25 domains and 16 KB per request
Property bulk resolve (`/api/properties/resolve/bulk`)	20 requests/minute per IP
Brand reads (`/api/brands/resolve`, `/api/brands/brand-json`)	60 requests/minute per IP
Save endpoints (`/api/brands/save`, `/api/properties/save`)	60 requests/hour per user
Crawl request (`/api/registry/crawl-request`)	5 minutes per domain, 30 requests/hour per user
All other endpoints	No limit

Rate-limited endpoints return 429 Too Many Requests when the limit is exceeded. Brand bulk resolve returns 503 with a Retry-After header when too much resolution work is already queued.

Endpoint Groups

Brand Resolution

Resolve domains to canonical brand identities, fetch brand.json files, and browse the brand registry.

Property Resolution

Resolve publisher domains to property information, validate adagents.json, and browse properties.

Agent Discovery

List, search, and filter agents by inventory profile. Browse publishers and view registry statistics.

Change Feed

Poll a cursor-based feed of registry changes for local sync.

Lookups & Authorization

Look up agents by domain, validate product authorization, and check property authorization in real time.

Lookups by entity

Three endpoints answer different questions about who is in the registry. They span two tag groups in the API reference, so use this table to pick the right lookup surface before diving into endpoint-specific parameters.

Endpoint	Auth surface	What it returns
`GET /api/registry/agents`	Public catalog; authenticated AgenticAdvertising.org API-tier members also see `members_only` agents.	The AgenticAdvertising.org-attested member-enrolled agent catalog, with optional filters and enrichment for health, capabilities, properties, compliance, measurement metrics, and verification state.
`GET /api/registry/operator?domain=X`	Auth-aware: anonymous callers see `public`; AgenticAdvertising.org API-tier members also see `members_only`; profile owners can also see `private`.	The agents operated by the queried entity plus the publishers that trust those agents.
`GET /api/registry/publisher?domain=X`	Public and unauthenticated; AgenticAdvertising.org membership does not change the response shape.	The inventory the queried entity publishes (`properties[]`) and the agents it authorizes (`authorized_agents[]` from `adagents.json`).

GET /api/registry/agents — use this when you want to browse or filter the public agent population. See Registering an agent for how agents end up in this catalog. Reference: List agents endpoint under Agent Discovery. GET /api/registry/operator?domain=X — use this when you have one entity in hand and want its agent footprint. GET /api/registry/publisher?domain=X — use this when you have one publisher in hand and want its inventory and delegations. The response’s formats[] is a lossy display projection, not the complete publisher contract. It omits custom-format schema pointers, channel applicability, and legacy projection metadata. Pass include=placements to receive provenance-labeled placement summaries with resolved canonical format options for placement eligibility. Consumers doing creative validation or needing omitted declaration fields must fetch the resolved raw catalog using the returned community registry_url or publisher hosting.resolved_url / hosting.expected_url. The registry lookup chooses the publisher-origin/community rung and reports provenance; the raw document supplies the complete declarations.

Brand Resolution

These endpoints resolve domains to brand identities. The source field identifies the provenance of the selected registry record. When more than one candidate fact exists for a domain, selection is deterministic: hosted wins over brand_json, then community, then enriched. Ties among stored rows use the most recently validated record and a stable ID tie-breaker. A normal read prefers that durable stored winner on a source tie; fresh=true lets a successful live origin read win a tie, but never override a higher-provenance stored record. Identical normal requests therefore do not randomly change records or labels.

Source	Meaning
`hosted`	Registered by a domain owner whose control of the domain has been verified
`brand_json`	Resolved from the domain’s `/.well-known/brand.json` file
`enriched`	Enriched via Brandfetch API
`community`	Submitted by a community member

All sources produce the same resolution response structure, but they are not equivalent evidence. hosted and brand_json are backed by domain control; community and enriched describe what the registry has learned without proving that the domain operator asserted it. source is identity provenance, not proof of a house relationship—use relationship_trust for that. To get full brand identity data (logos, colors, tone), use /api/brands/enrich or look up the brand in the registry.

Reading trust

A domain is authoritative for its own identity — TLS proves the document came from that domain and nothing more. Relationships between a brand and a house need both sides to publish them, so resolution reports how each relationship was established rather than flattening it into a single answer. For third-party verification, call GET /api/brands/resolve?domain=<leaf-domain> and inspect relationship_trust. Only mutual and inline are reciprocated relationships suitable for extending trust to house_domain:

mutual means the leaf publishes house_domain and the house names the leaf in brand_refs[]; relationship_verified_at reports when the resolver last observed both sides agreeing.
inline means the house’s own canonical document defines the leaf, so the ownership statement and identity come from the house authority itself.

Every other value is non-reciprocated. In particular, claimed_house_domain with leaf_only is one side’s self-assertion and must not authorize the leaf as part of that house. There is no separate ordered-chain endpoint in v3: the hierarchy is one level deep, and the reciprocated house_domain edge in this response is the supported ownership-verification result. An absent relationship_trust is not the same as standalone: it means the selected record carries no relationship verdict. Consumers must treat missing evidence as unknown, not as evidence that no relationship exists.

`relationship_trust`	Meaning
`inline`	The house’s own document defines the brand.
`mutual`	Both sides publish the relationship. The trust-extending edge.
`leaf_only`	The brand claims a house whose reciprocal declaration is missing, not yet active, or older than the resolver’s trust ceiling. See `claimed_house_domain`.
`house_only`	A house claims the brand, which has not claimed the house.
`standalone`	The brand claims no house.
`unverifiable`	A claimed house exists but could not be checked.

house_domain is only set on a trust-extending relationship; a one-sided claim appears as claimed_house_domain. For mutual, relationship_verified_at records when both sides were last seen agreeing — it does not advance while the house side is unreachable. relationship_declared_at records the house’s brand_refs[].effective_at, falling back to the resolver’s durable first observation when the publisher omits it. AgenticAdvertising.org’s reference resolver requires both clocks to remain live: confirmation may be retained for at most 24 hours while the house is unreachable, and declarations age out after 180 days even when re-confirmation keeps succeeding. Future declarations remain leaf_only until their effective time. Callers can apply stricter policies to either timestamp. Following a redirect never lets a domain adopt a house’s identity. When a domain’s brand.json points at a house that does not name the domain back — in properties[] as relationship: "owned", or in brand_refs[] — the response carries the claim (claimed_house_domain with relationship_trust: leaf_only) and no brand identity. A house that lists a domain with direct, delegated, or ad_network is declaring a monetization path, not ownership, so it does not resolve that domain’s identity either. If you expected an identity here, the house is missing its half of the relationship. fresh=true bypasses the resolution cache and refetches from the origin. When that fetch fails and a stored record is returned instead, live_brand_json carries that request’s failed-fetch diagnostics so you can distinguish “stored evidence returned” from “origin checked successfully.” Apply your own freshness policy to that fallback rather than silently treating it as live. Pre-v3 documents are promoted to canonical v3 identity for the response, flagged with promoted_from_schema and migration_warnings. Promotion covers identity only; legacy relationship data is preserved opaquely and never becomes a trust claim. In particular, a warning with field: "house" means the legacy house object was moved to legacy_metadata.legacy_house and did not establish house_domain. The publisher must add house_domain to the leaf document and a reciprocal brand_refs[] entry to the house document.

Trust fields in brand lists

/api/brands/registry and /api/brands/find include relationship_trust, relationship_verified_at, and claimed_house_domain on each result row. These are cached from the last crawler resolution cycle and use the same semantics as the relationship_trust field on /api/brands/resolve responses. The cache staleness is bounded by the crawl interval. An absent relationship_trust in a list result means trust has not yet been computed for that brand — it MUST NOT be interpreted as standalone. For an authoritative, real-time verdict use /api/brands/resolve.

Method	Path	Description
GET	`/api/brands/resolve`	Resolve a domain to its canonical brand
POST	`/api/brands/resolve/bulk`	Resolve up to 25 domains at once
GET	`/api/brands/brand-json`	Fetch raw brand.json for a domain
GET	`/api/brands/registry`	List all brands (search, pagination) with cached trust state
GET	`/api/brands/enrich`	Enrich brand data via Brandfetch
GET	`/api/brands/history`	Edit history for a brand
POST	`/api/brands/save`	Save or update a community brand (auth required)

Property Resolution

Method	Path	Description
GET	`/api/properties/resolve`	Resolve a domain to its property info
POST	`/api/properties/resolve/bulk`	Resolve up to 100 domains at once
GET	`/api/properties/registry`	List all properties (search, pagination)
GET	`/api/properties/validate`	Validate a domain’s adagents.json
GET	`/api/properties/history`	Edit history for a property
POST	`/api/properties/save`	Save or update a hosted property (auth required)

Agent Discovery

Method	Path	Description
GET	`/api/registry/agents`	List all member-enrolled agents — filter by type (`?type=brand	rights	measurement	governance	creative	sales	buying	signals`)
GET	`/api/registry/agents/search`	Search agents by inventory profile (auth required)
GET	`/api/registry/publishers`	List all publishers
GET	`/api/registry/stats`	Registry statistics
POST	`/api/registry/crawl-request`	Request re-crawl of a publisher domain (auth required)

Measurement-vendor discovery

To discover measurement vendors specifically (Adelaide-style attention, Scope3-style emissions, Nielsen DAR, IAS/DV custom quality, etc.), filter the agent list by type=measurement:

curl "https://agenticadvertising.org/api/registry/agents?type=measurement"

This returns every measurement agent enrolled in the registry by an AgenticAdvertising.org member organization. Per-metric catalog discovery. Each measurement agent publishes its full per-metric catalog at get_adcp_capabilities.measurement.metrics[] — the canonical, vendor-controlled source of truth. AgenticAdvertising.org crawls each measurement agent’s get_adcp_capabilities on a TTL and stores the result; passing ?capabilities=true folds the catalog into the response next to creative_capabilities and signals_capabilities.

Trust and external links

The registry caches measurement catalogs; it does not endorse or independently review their links or claims. Read each URL according to its field-level purpose:

Field	Meaning	What it does not prove
`methodology_url`	Vendor-published methodology documentation for the metric.	That AgenticAdvertising.org, an accreditor, or another independent party reviewed the methodology.
`standard_reference`	The industry-standard document the vendor says the metric implements.	That the implementation conforms to the standard or holds accreditation.
`accreditations[].evidence_url`	The vendor-supplied pointer intended to lead to the accreditor’s public listing or other public evidence for the named accreditation.	That the accreditation is valid, current, or independently verified by the registry.

An accreditation entry is a vendor assertion while verified_by_aao is false. Treat it as independently verified only when a separate, explicit attestation or verification state establishes who verified the claim, what was verified, and when. Enrollment, catalog caching, a plausible accreditor name, and an evidence_url alone do not establish that state. Clients must treat all three fields as untrusted external-link input. Parse the value as a URL, offer clickable links only for HTTPS destinations, show the destination hostname, and use an external-site confirmation when the destination is not already trusted by the user. A new-tab link should set target="_blank" with rel="noopener noreferrer"; render escaped text and attributes rather than interpolating catalog values through innerHTML. Fetching a link is a separate security decision from rendering it. Browser and server clients should not fetch these URLs merely to display a catalog. A service that deliberately retrieves methodology or evidence content must apply its normal SSRF and privacy controls, including blocking private, loopback, link-local, and metadata-service destinations and revalidating every redirect. These semantics are stable properties of the named fields, so the response does not repeat them in a top-level _meta path list or per-value provenance flag. Such metadata would duplicate the schema contract without turning a vendor-supplied link into verified evidence. Filter parameters (all imply type=measurement when present; an explicit non-measurement type returns 400):

Param	Match	Notes
`metric_id=attention_units`	Exact match on `metrics[].metric_id`	Repeatable; multiple values are AND’d (vendor must carry all named metrics).
`accreditation=MRC`	Exact match on `metrics[].accreditations[].accrediting_body`	Repeatable; multiple values are AND’d (vendor must carry all named accreditations). When combined with `metric_id`, a cross-product AND applies — see combined filter semantics below. Vendor-asserted — `verified_by_aao` is always `false` in the response; renderers should mark these as vendor claims, not AgenticAdvertising.org endorsements.
`q=attention`	Case-insensitive substring on `metric_id`	v1 scope: metric_id only. Max 64 chars; SQL wildcards (`%`, `_`) rejected. Description/standard fuzzy search is a follow-up.

Combined filter semantics. When both metric_id and accreditation are present, per-metric semantics apply: the same metrics[] element must satisfy both constraints simultaneously. A vendor with an attention_units metric and a separately MRC-accredited viewability metric does not match — only a vendor whose attention_units metric itself carries MRC accreditation does. With multiple values, every (metric_id, accreditation) pair must be satisfied by at least one metrics element. This is a cross-product AND, not an OR within accreditation:

# Vendor must have MRC-accredited attention_units AND MRC-accredited emissions
curl "https://agenticadvertising.org/api/registry/agents?metric_id=attention_units&metric_id=emissions&accreditation=MRC"

Using multiple accreditation values alongside multiple metric_id values produces an all-pairs AND (M × N constraints) and typically returns few or no results. Prefer single accreditation with multiple metric_id values for discovery.

# All vendors offering attention measurement
curl "https://agenticadvertising.org/api/registry/agents?metric_id=attention_units&capabilities=true"

# MRC-accredited viewability vendors
curl "https://agenticadvertising.org/api/registry/agents?type=measurement&accreditation=MRC&q=viewab&capabilities=true"

Direct call vs. index — when to use which. Buyers have two paths to a vendor’s metric catalog:

Use case	Path	Why
Discovery / planning (“which vendors offer attention?”)	Registry index (`?metric_id=...`)	Pre-aggregated, cached, fast. Cross-vendor in one call. Stale up to the registry TTL window (typically 24h).
Settlement / audit (“does Adelaide currently support metric X?”)	Direct call to `get_adcp_capabilities`	Live, canonical, no staleness. The buyer is already calling the measurement agent at delivery / reconciliation time; one extra call is cheap and removes index staleness from the audit trail.
Filtering at `get_products` time	Registry index	Buyer is in a fast-path query and the seller’s product catalog already needs to know which vendors are valid.

Creative-agent discovery

Endpoints publish their canonical build, validation, and preview surface in get_adcp_capabilities.creative.supported_formats[]. The registry snapshots those self-declarations and supports reverse lookup without calling every candidate. Results can include standalone creative agents and mixed sales/creative agents; registry type is the endpoint’s primary role, not an exclusion of its other capability blocks. Creative filters do not force a primary type, because mixed sales/creative endpoints are valid renderer candidates. Multiple format_kind or creative_operation values are OR’d within that parameter; different parameters must match the same supported_formats[] entry.

Param	Match
`format_kind`	Exact canonical `format.format_kind`
`publisher_domain`	Exact publisher namespace on `format`
`format_option_id`	Exact publisher format option on `format`
`capability_id`	Exact agent-local capability identifier
`creative_operation`	`build`, `validate`, or `preview`

# Agents claiming they can build a fictional publisher's exact vertical-video contract
curl "https://agenticadvertising.org/api/registry/agents?publisher_domain=shorts.streamhaus.example&format_option_id=vertical_video&creative_operation=build&capabilities=true"

# Generic hosted-video builders
curl "https://agenticadvertising.org/api/registry/agents?format_kind=video_hosted&creative_operation=build"

These are endpoint self-claims, not publisher endorsements. Before production use, call the selected endpoint’s get_adcp_capabilities directly to refresh the declaration and then route build_creative with that entry’s capability_id when operations includes build.

Change Feed

Method	Path	Description
GET	`/api/registry/feed`	Poll cursor-based registry change feed (auth required)
GET	`/api/registry/feed/stream`	Stream cursor-based registry feed pages over Server-Sent Events (auth required)

Lookups & Authorization

Method	Path	Description
GET	`/api/registry/lookup/domain/{domain}`	Find agents authorized for a domain
GET	`/api/registry/lookup/property`	Find agents by property identifier
GET	`/api/registry/lookup/agent/{agentUrl}/domains`	Get all domains for an agent
POST	`/api/registry/validate/product-authorization`	Validate agent product authorization
POST	`/api/registry/expand/product-identifiers`	Expand property selectors to identifiers
GET	`/api/registry/validate/property-authorization`	Real-time authorization check

Authorization validation checks both sides: the publisher’s adagents.json (does it authorize this agent with the claimed delegation_type?) and the operator’s brand.json (does it declare this property with a matching relationship?).

Validation Tools

Method	Path	Description
POST	`/api/adagents/validate`	Validate adagents.json for a domain
POST	`/api/adagents/create`	Generate adagents.json content

Search

Method	Path	Description
GET	`/api/search`	Search across brands, publishers, and properties
GET	`/api/manifest-refs/lookup`	Find manifest references for a domain

Agent Probing

Method	Path	Description
GET	`/api/public/discover-agent`	Probe an agent URL for capabilities
GET	`/api/public/agent-formats`	Get canonical `creative.supported_formats[]` capabilities from an agent
GET	`/api/public/agent-products`	Get products from a sales agent
GET	`/api/public/validate-publisher`	Validate a publisher domain

Activity history

GET /api/brands/history?domain={domain} and GET /api/properties/history?domain={domain} return the edit history for a registry entry, newest first. These are public endpoints — no authentication required.

Response

{
  "domain": "acmecorp.com",
  "total": 3,
  "revisions": [
    {
      "revision_number": 3,
      "editor_name": "Pinnacle Media",
      "edit_summary": "Updated logo URL",
      "source": "community",
      "is_rollback": false,
      "created_at": "2026-03-01T12:34:56Z"
    },
    {
      "revision_number": 2,
      "editor_name": "system",
      "edit_summary": "API: enriched via Brandfetch",
      "source": "enriched",
      "is_rollback": false,
      "created_at": "2026-02-15T08:00:00Z"
    }
  ]
}

Entries with editor_name: "system" were written by automated enrichment. When is_rollback is true, rolled_back_to contains the revision number that was restored. Pagination uses limit (max 100) and offset query parameters.

Anti-abuse and anti-homograph controls

Because /api/brands/save, /api/properties/save, and the adagents validation endpoints accept domain strings from authenticated member organizations, the hosted registry applies a layered floor of anti-abuse controls at save time. These are operational behaviors of the AgenticAdvertising.org registry in the 3.x era — not a new wire surface — and exist so that typosquats, confusable lookalikes, and drive-by brand hijacks cannot get written into the index by a single authenticated caller.

Domain normalization (IDNA 2008 + confusable detection). Save endpoints SHOULD apply IDNA 2008 to normalize internationalized domain names to ASCII before persistence, and SHOULD then run Unicode confusable-detection (for example, ICU uspoof or equivalent) against two corpora: (1) already-registered entries in the index, and (2) a curated high-value-brand deny list maintained by the registry operator. The deny list catches typosquats of well-known brands before those brands themselves are registered (e.g., a g00gle.com submission collides with the deny-list entry even if Google has not yet claimed an index row). Ambiguous submissions — mixed-script labels, homograph collisions, disallowed Unicode classes — SHOULD be rejected or flagged for human review rather than silently committed.
Ownership proof before commit. Save endpoints MUST require evidence of domain control before a new brand or property entry is committed to the index — this is the threat that motivates the control, since an attacker with a compromised member API key would otherwise be free to bulk-register fresh confusable variants that have no prior entry to conflict with. For revisions to an existing community-source entry by the same authenticated organization, re-proof SHOULD be required on a rolling basis (for example, once the prior proof is older than 90 days) but MAY be skipped within that window. Accepted proofs are either a DNS TXT record at _adcp-owner.{domain} matching a server-issued nonce, or an HTTP challenge hosted at /.well-known/adcp-ownership.txt on the domain. Nonces MUST be single-use, scoped to the (organization, domain) pair, and MUST expire within 15 minutes of issuance; verification MUST consume the nonce on success and invalidate it on failure. A leaked or unused nonce after expiry is dead. Revisions to an existing authoritative entry (i.e., one backed by brand.json / adagents.json) continue to follow the 409 Conflict semantics in Save brand and Save property; ownership proof covers the community-source save path.
Per-organization rate limits on saves. In addition to the per-IP rate limits documented in Rate Limits, save endpoints SHOULD apply per-organization limits so that a single compromised API key cannot bulk-register confusable variants. The hosted implementation uses a burst-tolerant cap (indicative: tens of saves per hour per org, low-hundreds per day per org); callers exceeding the per-org bucket receive 429 Too Many Requests.

These controls are enforced by the hosted AgenticAdvertising.org registry. Self-hosted mirrors consuming the Change Feed rely on the hosted registry’s save-time checks and do not re-run them — which is consistent with the feed’s advisory-identity posture (see specs/registry-change-feed.md §Advisory identity material): the feed is change-detection, not a trust anchor, and the publisher’s own adagents.json pin remains the authoritative identity source (see adagents.json §signing_keys). Operators running an alternative registry implementation SHOULD apply equivalent save-time controls before accepting community-source writes.

Authentication

Public endpoints (resolution, discovery, search) require no authentication. Write endpoints accept either an organization API key (server-to-server) or a user JWT obtained via OAuth 2.1 (interactive / agent clients). Both are sent in the Authorization: Bearer ... header.

Option A: Organization API key

Long-lived, org-scoped. Best for server-to-server integrations where no user is present.

Sign in at agenticadvertising.org/dashboard/api-keys
Click Create key and copy the generated key

Pass the key in the Authorization header:

Authorization: Bearer sk_...

Option B: User SSO via OAuth 2.1

Short-lived, user-scoped. Best for agent clients (MCP, AI assistants, custom apps) where a human is signing in to AAO. A single token works against both /mcp and the REST API. Discovery follows RFC 8414 and RFC 9728:

Authorization server metadata: GET /.well-known/oauth-authorization-server
Protected-resource metadata (REST API): GET /.well-known/oauth-protected-resource/api
Protected-resource metadata (MCP): GET /.well-known/oauth-protected-resource/mcp

The flow is authorization code with PKCE. Dynamic client registration (RFC 7591) is available at /register. Users authenticate via AuthKit; the token is a WorkOS-signed JWT.

Authorization: Bearer <jwt>

A valid user JWT proves identity, not entitlement. Endpoints gated on organization membership or admin role (most write endpoints) still return 403 if the authenticated user lacks the required standing. Community-mirror submissions are the exception to direct role rejection: PUT /api/registry/mirrors/{platform} accepts any authenticated organization. A registry moderator or AgenticAdvertising.org administrator publishes immediately; other callers create a pending proposal and receive 202 Accepted plus Location, status_url, and proposal_digest. Review decisions must echo that digest, and approval fails if the public mirror changed since submission. Contributor proposals are limited to 1 MiB and 2,000 catalog items. This keeps community contribution open without allowing an organization credential to publish a global fallback catalog on another platform’s behalf without bounded, revision-safe review.

Authenticated endpoints

These endpoints require a valid API key.

Save brand

POST /api/brands/save Save or update a community brand in the registry. For existing brands, creates a revision-tracked edit. Cannot edit authoritative brands managed via brand.json — those return 409 Conflict. Request body:

{
  "domain": "acmecorp.com",
  "brand_name": "Acme Corp",
  "brand_manifest": {
    "name": "Acme Corp",
    "description": "A fictional company",
    "logos": [{ "url": "https://acmecorp.com/logo.svg", "tags": ["icon"] }],
    "colors": [{ "hex": "#FF5733", "type": "accent" }]
  }
}

domain and brand_name are required. brand_manifest (brand identity data) is optional. The brand’s source is set to "community" by the server. Domains are normalized (protocol stripped, lowercased).

curl -X POST "https://agenticadvertising.org/api/brands/save" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"acmecorp.com","brand_name":"Acme Corp"}'

const res = await fetch(
  "https://agenticadvertising.org/api/brands/save",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      domain: "acmecorp.com",
      brand_name: "Acme Corp",
    }),
  }
);
const result = await res.json();

import requests

result = requests.post(
    "https://agenticadvertising.org/api/brands/save",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"domain": "acmecorp.com", "brand_name": "Acme Corp"},
).json()

Response (create)

{
  "success": true,
  "message": "Brand \"Acme Corp\" saved to registry",
  "domain": "acmecorp.com",
  "id": "br_abc123"
}

Response (update)

{
  "success": true,
  "message": "Brand \"Acme Corp\" updated in registry (revision 2)",
  "domain": "acmecorp.com",
  "id": "br_abc123",
  "revision_number": 2
}

Save property

POST /api/properties/save Save or update a hosted property in the registry. For existing properties, creates a revision-tracked edit. Cannot edit authoritative properties managed via adagents.json — those return 409 Conflict. This is an identity-only write surface: the stored document always carries authorized_agents: []. Sales authorization lives solely in the publisher’s own origin adagents.json — the community registry cannot mint or carry it — so any authorized_agents sent in the request body is ignored. Request body:

{
  "publisher_domain": "examplepub.com",
  "properties": [
    { "type": "website", "name": "Example Publisher" }
  ],
  "contact": {
    "name": "Ad Ops",
    "email": "adops@examplepub.com"
  }
}

publisher_domain is required. properties (each requiring type and name) and contact are optional. Domains are normalized (protocol stripped, lowercased).

curl -X POST "https://agenticadvertising.org/api/properties/save" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publisher_domain": "examplepub.com",
    "properties": [{"type": "website", "name": "Example Publisher"}]
  }'

const res = await fetch(
  "https://agenticadvertising.org/api/properties/save",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      publisher_domain: "examplepub.com",
      properties: [{ type: "website", name: "Example Publisher" }],
    }),
  }
);
const result = await res.json();

import requests

result = requests.post(
    "https://agenticadvertising.org/api/properties/save",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "publisher_domain": "examplepub.com",
        "properties": [{"type": "website", "name": "Example Publisher"}],
    },
).json()

Response (create)

{
  "success": true,
  "message": "Hosted property created for examplepub.com",
  "id": "prop_xyz789"
}

Response (update)

{
  "success": true,
  "message": "Property 'examplepub.com' updated (revision 2)",
  "id": "prop_xyz789",
  "revision_number": 2
}

Change feed

GET /api/registry/feed Poll a cursor-based feed of registry changes. Use this to keep a local copy of the registry in sync without re-fetching the full dataset. Events are ordered by UUID v7 event_id, providing monotonic cursor progression. The feed retains events for 90 days — expired cursors return 410 Gone. Each response includes freshness metadata so consumers can measure feed lag for the requested type filter. Schema: core/registry-feed-response.json wraps core/registry-event.json items. Query parameters:

Parameter	Type	Default	Description
`cursor`	UUID	—	Resume after this event ID. Omit for the earliest available events.
`types`	string	—	Comma-separated event type filters. Supports glob patterns (e.g. `property.*`).
`limit`	number	100	Max events per page (1–10,000).

Event types:

Type	Description
`property.created`	A new property was added to the registry
`property.updated`	Property metadata changed
`property.merged`	Two property records were merged
`property.stale`	Property failed re-crawl validation
`property.reactivated`	A stale property passed re-crawl
`collection.created`	A new publisher collection was added to the registry
`collection.updated`	Collection metadata or distribution identifiers changed
`collection.merged`	Two collection records were merged
`collection.removed`	A collection is no longer visible in the publisher’s authoritative catalog
`agent.discovered`	A new `agent_url` appeared in a publisher’s `adagents.json` (authorization graph; does not imply the agent is in `/api/registry/agents`)
`agent.removed`	An agent was removed from the registry
`agent.profile_updated`	Agent inventory profile changed
`agent.compliance_changed`	Agent compliance or verification status changed
`agent.verification_earned`	Agent earned an AAO Verified badge
`agent.verification_lost`	Agent lost an AAO Verified badge
`publisher.adagents_discovered`	A publisher’s adagents.json was discovered and projected into the registry
`publisher.adagents_changed`	A semantic field of a publisher’s adagents.json changed, including a formats-only or placements-only revision. The payload includes `changed_fields`, `format_count`, and `placement_count` on newly emitted 3.2 events.
`authorization.granted`	An agent was authorized for a property
`authorization.revoked`	An authorization was removed
`authorization.modified`	An authorization stayed visible, but externally visible metadata changed (including rotation of `signing_keys`)

authorization.* payloads carry signing_keys — the publisher-pinned JWK set from authorized_agents[*].signing_keys in adagents.json. Consumers verifying inbound TMP signatures key on kid → JWK; null when the publisher declared no keys, in which case consumers fall back to the agent-hosted JWKS per spec R-2. Note that per specs/registry-change-feed.md §Advisory identity material the feed is change-detection, not a trust anchor: consumers MUST re-verify against the publisher’s own adagents.json before acting on identity changes.

curl "https://agenticadvertising.org/api/registry/feed?types=property.*&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(
  "https://agenticadvertising.org/api/registry/feed?types=property.*&limit=50",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const feed = await res.json();
// Store feed.cursor for next poll

import requests

feed = requests.get(
    "https://agenticadvertising.org/api/registry/feed",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"types": "property.*", "limit": 50},
).json()
# Store feed["cursor"] for next poll

The crawler compares every semantic top-level field of the normalized document. Changes confined to formats[] or placements[] therefore emit publisher.adagents_changed; changes only to transport/version metadata ($schema or last_updated) do not. Consumers may use changed_fields to target their refresh, but should re-resolve every field they depend on when reading an older retained event that lacks this field. 3.2 migration note: handlers that previously reacted only to agents_added, agents_removed, properties_added, or properties_removed should also inspect changed_fields — a formats-only or placements-only revision emits this event with those count fields unchanged and changed_fields set to ["formats"] or ["placements"].

Response

{
  "events": [
    {
      "event_id": "019539a0-1234-7000-8000-000000000001",
      "event_type": "property.created",
      "entity_type": "property",
      "entity_id": "019539a0-b1c2-7000-8000-000000000002",
      "payload": {
        "property_rid": "019539a0-b1c2-7000-8000-000000000002",
        "classification": "property",
        "source": "contributed",
        "identifiers": [
          { "type": "domain", "value": "streamer.example.com" }
        ]
      },
      "actor": "crawler",
      "created_at": "2026-03-31T10:00:00.000Z"
    }
  ],
  "cursor": "019539a0-1234-7000-8000-000000000001",
  "has_more": true,
  "freshness": {
    "generated_at": "2026-03-31T10:00:15.000Z",
    "latest_event_created_at": "2026-03-31T10:00:00.000Z",
    "lag_seconds": 15,
    "retention_days": 90
  }
}

When has_more is true, pass the returned cursor value in the next request to continue polling. When false, you’ve reached the end of the current feed — poll again later with the same cursor to pick up new events. latest_event_created_at is the newest matching event currently visible to the feed. lag_seconds is computed against generated_at; alert on it according to your own mirror freshness target. GET /api/registry/feed/stream provides the same feed pages over Server-Sent Events. Reconnect with your last persisted cursor after disconnects. The stream emits event: feed with the same JSON shape shown above and event: heartbeat while caught up. Cursors are tied to the same logical types subscription; changing filters while reusing a cursor can skip events that were filtered out previously. The stream carries the resume cursor in JSON data.cursor, not SSE id, so browser EventSource clients must reconnect with ?cursor=.... If the cursor has expired (older than 90 days or not found), the response is 410 Gone:

410 Gone

{
  "error": "cursor_expired",
  "message": "Cursor is older than 90-day retention window. Re-bootstrap from /registry/agents/search, /catalog, and /catalog/collections/sync."
}

Agent search

GET /api/registry/agents/search Search agents by inventory profile — channels, markets, content categories, property types, and more. Filters use AND across dimensions and OR within a dimension. Results are ranked by a relevance score based on filter match breadth, inventory depth, and TMP support. Query parameters:

Parameter	Type	Default	Description
`channels`	CSV	—	Filter by channel (e.g. `ctv,olv,display`)
`property_types`	CSV	—	Filter by property type (e.g. `ctv_app,website`)
`markets`	CSV	—	Filter by market/country code (e.g. `US,GB`)
`categories`	CSV	—	Filter by IAB content category (e.g. `IAB-7,IAB-7-1`)
`tags`	CSV	—	Filter by tag (e.g. `premium,brand_safe`)
`delivery_types`	CSV	—	Filter by delivery type (e.g. `guaranteed,programmatic`)
`has_tmp`	boolean	—	Require TMP support (`true` or `false`)
`min_properties`	number	—	Minimum number of properties in inventory
`cursor`	string	—	Pagination cursor from a previous response
`limit`	number	50	Max results per page (1–200)

Each CSV parameter accepts up to 100 values.

curl "https://agenticadvertising.org/api/registry/agents/search?channels=ctv,olv&markets=US&has_tmp=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(
  "https://agenticadvertising.org/api/registry/agents/search?channels=ctv,olv&markets=US&has_tmp=true",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const agents = await res.json();

import requests

agents = requests.get(
    "https://agenticadvertising.org/api/registry/agents/search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"channels": "ctv,olv", "markets": "US", "has_tmp": "true"},
).json()

Response

{
  "results": [
    {
      "agent_url": "https://ads.streamhaus.example.com",
      "channels": ["ctv", "olv"],
      "property_types": ["ctv_app", "website"],
      "markets": ["US", "GB", "CA"],
      "categories": ["IAB-7", "IAB-7-1"],
      "tags": ["premium"],
      "delivery_types": ["guaranteed"],
      "format_kinds": ["video_hosted", "video_vast"],
      "property_count": 42,
      "publisher_count": 3,
      "has_tmp": true,
      "category_taxonomy": null,
      "relevance_score": 0.92,
      "matched_filters": ["channels", "markets"],
      "updated_at": "2026-03-31T10:00:00.000Z"
    }
  ],
  "cursor": "MC45Mjpodh...",
  "has_more": false
}

The matched_filters array shows which filter dimensions matched, useful for understanding why a result was returned. The relevance_score combines filter match breadth, ln(property_count + 1) weighted at 0.1, and a 0.05 boost for TMP support.

Crawl request

POST /api/registry/crawl-request Request an immediate re-crawl of a publisher domain. Use this after updating an adagents.json file so the registry picks up changes without waiting for the next scheduled crawl. The crawl runs asynchronously — the endpoint returns 202 Accepted immediately. Rate-limited to one request per domain every 5 minutes and 30 requests per user per hour. Request body:

{
  "domain": "examplepub.com"
}

domain is required. Domains are normalized (lowercased, trimmed). The endpoint validates the domain format and performs a DNS lookup to reject private/reserved IP addresses.

curl -X POST "https://agenticadvertising.org/api/registry/crawl-request" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"examplepub.com"}'

const res = await fetch(
  "https://agenticadvertising.org/api/registry/crawl-request",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ domain: "examplepub.com" }),
  }
);
const result = await res.json(); // 202

import requests

result = requests.post(
    "https://agenticadvertising.org/api/registry/crawl-request",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"domain": "examplepub.com"},
).json()

202 Accepted

{
  "message": "Crawl request accepted",
  "domain": "examplepub.com"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded for this domain",
  "retry_after": 245
}

retry_after is the number of seconds to wait before retrying.

Submit brand (legacy)

POST /api/brands/discovered/community Submit a brand for review. This endpoint predates /api/brands/save — prefer the save endpoint for new integrations.

Error responses

Status	Description
400	Missing required fields or invalid domain
401	Missing or invalid API key
409	Cannot edit an authoritative brand/property (managed via `brand.json` or `adagents.json`)
410	Cursor expired (change feed — older than 90-day retention window)
429	Rate limit exceeded

Protocol vs REST API

The AdCP protocol defines MCP and A2A tasks for agent-to-agent communication (e.g. get_products, create_media_buy). The registry REST API is separate — it provides HTTP endpoints for looking up entities in the AgenticAdvertising.org registry. Use the REST API for discovery and authorization:

Resolve brand or property domains before making protocol calls
Discover which agents exist and what they’re authorized for
Validate authorization in real time during ad serving
Build integrations that browse or search the registry

Use MCP/A2A tasks for transactional operations:

Fetching products from a sales agent (get_products)
Creating media buys (create_media_buy)
Building creatives (build_creative)
Getting signals (get_signals)

A typical integration uses both: resolve a publisher domain via the registry API, then call the authorized agent’s MCP endpoint to transact.

​Base URL

​Quick Start

​Rate Limits

​Endpoint Groups

Brand Resolution

Property Resolution

Agent Discovery

Change Feed

Lookups & Authorization

​Lookups by entity

​Brand Resolution

​Reading trust

​Trust fields in brand lists

​Property Resolution

​Agent Discovery

​Measurement-vendor discovery

Trust and external links

​Creative-agent discovery

​Change Feed

​Lookups & Authorization

​Validation Tools

​Search

​Agent Probing

​Activity history

​Anti-abuse and anti-homograph controls

​Authentication

​Option A: Organization API key

​Option B: User SSO via OAuth 2.1

​Authenticated endpoints

​Save brand

​Save property

​Change feed

​Agent search

​Crawl request

​Submit brand (legacy)

​Error responses

​Protocol vs REST API

Base URL

Quick Start

Rate Limits

Endpoint Groups

Lookups by entity

Brand Resolution

Reading trust

Trust fields in brand lists

Property Resolution

Agent Discovery

Measurement-vendor discovery

Creative-agent discovery

Change Feed

Lookups & Authorization

Validation Tools

Search

Agent Probing

Activity history

Anti-abuse and anti-homograph controls

Authentication

Option A: Organization API key

Option B: User SSO via OAuth 2.1

Authenticated endpoints

Save brand

Save property

Change feed

Agent search

Crawl request

Submit brand (legacy)

Error responses

Protocol vs REST API