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"

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
Bulk resolve (`/api/brands/resolve/bulk`, `/api/properties/resolve/bulk`)	20 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.

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.

Brand Resolution

These endpoints resolve domains to brand identities. The source field in the response indicates where the data came from:

Source	Meaning
`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. To get full brand identity data (logos, colors, tone), use /api/brands/enrich or look up the brand in the registry.

Method	Path	Description
GET	`/api/brands/resolve`	Resolve a domain to its canonical brand
POST	`/api/brands/resolve/bulk`	Resolve up to 100 domains at once
GET	`/api/brands/brand-json`	Fetch raw brand.json for a domain
GET	`/api/brands/registry`	List all brands (search, pagination)
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 agents (filter by type, with enrichment)
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)

Change Feed

Method	Path	Description
GET	`/api/registry/feed`	Poll cursor-based registry change feed (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

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 creative formats 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.

Authentication

Public endpoints (resolution, discovery, search) require no authentication. Write endpoints require a Bearer token issued to an AgenticAdvertising.org member organization.

Obtaining an API key

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

Using the API key

Pass the key in the Authorization header:

Authorization: Bearer sk_...

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"}'

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. Request body:

{
  "publisher_domain": "examplepub.com",
  "authorized_agents": [
    { "url": "https://agent.example.com", "authorized_for": "sell" }
  ],
  "properties": [
    { "type": "website", "name": "Example Publisher" }
  ],
  "contact": {
    "name": "Ad Ops",
    "email": "adops@examplepub.com"
  }
}

publisher_domain and authorized_agents (each with a required url and optional authorized_for) are 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",
    "authorized_agents": [{"url": "https://agent.example.com", "authorized_for": "sell"}],
    "properties": [{"type": "website", "name": "Example Publisher"}]
  }'

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. 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
`agent.discovered`	A new agent was found via adagents.json
`agent.removed`	An agent was removed from the registry
`agent.profile_updated`	Agent inventory profile changed
`publisher.adagents_changed`	A publisher’s adagents.json was updated
`authorization.granted`	An agent was authorized for a property
`authorization.revoked`	An authorization was removed

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

Response

{
  "events": [
    {
      "event_id": "019539a0-1234-7000-8000-000000000001",
      "event_type": "property.created",
      "entity_type": "property",
      "entity_id": "019539a0-b1c2-7000-8000-000000000002",
      "payload": {},
      "actor": "crawler",
      "created_at": "2026-03-31T10:00:00.000Z"
    }
  ],
  "cursor": "019539a0-1234-7000-8000-000000000001",
  "has_more": true
}

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. 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 and /catalog/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"

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_ids": [],
      "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"}'

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.

Documentation

​Base URL

​Quick Start

​Rate Limits

​Endpoint Groups

Brand Resolution

Property Resolution

Agent Discovery

Change Feed

Lookups & Authorization

​Brand Resolution

​Property Resolution

​Agent Discovery

​Change Feed

​Lookups & Authorization

​Validation Tools

​Search

​Agent Probing

​Activity history

​Authentication

​Obtaining an API key

​Using the API key

​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

Brand Resolution

Property Resolution

Agent Discovery

Change Feed

Lookups & Authorization

Validation Tools

Search

Agent Probing

Activity history

Authentication

Obtaining an API key

Using the API key

Authenticated endpoints

Save brand

Save property

Change feed

Agent search

Crawl request

Submit brand (legacy)

Error responses

Protocol vs REST API