🎉 AdCP 3.0 is now GA — see what's new
Documentation
- Introduction
- Quickstart
- FAQ
- AI Disclosure
- Trust & Security
curl --request POST \
--url https://agenticadvertising.org/api/me/agents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://agent.example.com/mcp",
"name": "<string>",
"visibility": "private",
"type": "brand",
"health_check_url": "<string>"
}
'{
"agent": {
"url": "https://agent.example.com/mcp",
"visibility": "private",
"name": "<string>",
"type": "brand",
"health_check_url": "<string>"
},
"warnings": [
{
"code": "visibility_downgraded",
"agent_url": "<string>",
"requested": "public",
"applied": "members_only",
"reason": "tier_required",
"message": "<string>"
}
],
"org_auto_created": true,
"profile_auto_created": true
}Register an agent
Register an agent on the caller’s organization member profile.
Idempotent on url: re-posting the same url updates the entry in place rather than creating a duplicate. New entries return 201; updates return 200.
True one-call storefront experience. A third-party app holding only a user’s OAuth token can POST /api/me/agents once and have the entire bootstrap chain materialize:
-
If the caller has zero org memberships, the server auto-creates an organization (corporate or personal workspace based on the user’s email domain) and the response includes
org_auto_created: true. -
If the caller’s org has no member profile, the server auto-creates a private profile (display name = organization name,
is_public: false) and the response includesprofile_auto_created: true.
Both auto-bootstraps are best-effort fallbacks. To customize org name / company_type / revenue_tier, or to control profile slug / brand identity / tagline, call POST /api/organizations and POST /api/me/member-profile explicitly before registering the agent. Tier transitions never happen via this path — go through the billing flow.
The type field is resolved server-side from the agent’s capability snapshot — a client cannot pin a misclassification (e.g. registering a sales agent as buying).
visibility: "public" requires Professional tier or higher and a primary_brand_domain set on the profile. Non-API-tier callers who request public will have the entry stored as members_only instead, and the response will include a visibility_downgraded warning describing the coercion.
curl --request POST \
--url https://agenticadvertising.org/api/me/agents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://agent.example.com/mcp",
"name": "<string>",
"visibility": "private",
"type": "brand",
"health_check_url": "<string>"
}
'{
"agent": {
"url": "https://agent.example.com/mcp",
"visibility": "private",
"name": "<string>",
"type": "brand",
"health_check_url": "<string>"
},
"warnings": [
{
"code": "visibility_downgraded",
"agent_url": "<string>",
"requested": "public",
"applied": "members_only",
"reason": "tier_required",
"message": "<string>"
}
],
"org_auto_created": true,
"profile_auto_created": true
}Documentation Index
Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt
Use this file to discover all available pages before exploring further.
Authorizations
Bearer token in the Authorization header. Two token types are accepted:
- Organization API key (
sk_...) issued via the dashboard. Org-scoped, long-lived, for server-to-server use. - User JWT obtained via the OAuth 2.1 authorization code flow with PKCE. User-scoped, short-lived. Discover the authorization server at
/.well-known/oauth-authorization-serverand the protected-resource metadata at/.well-known/oauth-protected-resource/api.
Query Parameters
WorkOS organization id to act on. Defaults to the caller's primary organization. Use this from a multi-org session (or when shelling with a user JWT) to target a non-primary org. Verification goes through WorkOS membership lookup; non-members get 403.
"org_01HXZAB123"
Body
Request body for POST /api/me/agents.
"https://agent.example.com/mcp"
Visibility tier on the registry catalog. private = profile owner only; members_only = AAO API-tier members on operator lookup; public = listed in the public catalog and reflected in the org's brand.json (requires Professional tier or higher).
private, members_only, public Agent type. Resolved server-side from the agent's capability snapshot when one exists; the value submitted by the client is used only as a fallback when no snapshot is available, and is never trusted to override an inferred classification.
brand, rights, measurement, governance, creative, sales, buying, signals, unknown Response
Agent already registered at this url; entry updated in place.
Agent entry stored on a member profile.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Set to true when this POST was the caller's first interaction with the registry and the server auto-created the organization (display name derived from the user's email domain for corporate emails, or <First Last>'s Workspace for free-email providers). Combined with profile_auto_created, this is the one-call storefront experience: a third-party app holding only an OAuth token gets the org, profile, and registered agent in a single request.
Set to true when this POST was the first agent registration on the caller's organization and the server auto-created a private member profile (display name = organization name, is_public: false). Absent on subsequent calls and on update-in-place. Surfaced so storefront-style integrations can show a "we set up your profile" hint without needing to detect the prior 404 → bootstrap → retry shape.
Was this page helpful?