🎉 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/organizations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"organization_name": "Acme Media",
"is_personal": false,
"company_type": "adtech",
"revenue_tier": "under_1m",
"marketing_opt_in": false
}
'{
"success": true,
"organization": {
"id": "org_01HXZAB123",
"name": "Acme Media"
},
"id": "<string>",
"name": "<string>",
"adopted": true
}Create or adopt my organization
Bootstrap the caller’s organization explicitly. Use this when the caller wants to control the organization name, company_type, revenue_tier, or is_personal flag before any agents are registered.
Most storefront-style integrations don’t need this call — POST /api/me/agents will auto-create an org for a fresh OAuth user (corporate or personal workspace based on the email domain) and surface org_auto_created: true in the response. Reach for POST /api/organizations only when the auto-derived defaults aren’t acceptable.
Three outcomes depending on the caller’s state:
-
Fresh create (most common): a new WorkOS organization is created, the caller is added as
owner, the corporate domain is recorded as email-verified, and ToS / privacy-policy acceptance is logged from the request context. Returns{ success: true, organization: { id, name } }. -
Prospect adoption: an organization with the caller’s email domain already exists as a
prospect(the registry pre-recorded it from a brand crawl but no human had claimed it yet). The caller is promoted toownerof the existing record instead of forking a duplicate. Returns{ id, name, adopted: true }. -
Already-active conflict: the org exists and is already claimed by another paying member or a previously joined user. Returns
409with the existing org id so the caller can switch to a join-request flow (POST /api/organizations/:orgId/join-requests) instead of trying to register a duplicate.
Tier transitions happen via the billing flow only — there is no membership_tier field on this endpoint. After org creation, send the user to POST /api/checkout-session (or the dashboard /membership page) to start a subscription; the Stripe webhook is the sole writer of organizations.membership_tier.
Rate-limited per user: 15 failed attempts per hour; successful calls do not count against the limit so a legitimate registration is never penalized by earlier validation errors.
curl --request POST \
--url https://agenticadvertising.org/api/organizations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"organization_name": "Acme Media",
"is_personal": false,
"company_type": "adtech",
"revenue_tier": "under_1m",
"marketing_opt_in": false
}
'{
"success": true,
"organization": {
"id": "org_01HXZAB123",
"name": "Acme Media"
},
"id": "<string>",
"name": "<string>",
"adopted": 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.
Body
Request body for POST /api/organizations.
Bootstraps a WorkOS organization, mirrors the caller as owner, records the caller's ToS / privacy-policy acceptance, and (for non-personal orgs) inserts an email-verified record into organization_domains so subsequent registry calls can skip explicit domain-verification.
Membership tier and corporate domain are not caller-supplied: the tier is set by the Stripe webhook on subscription events, and the corporate domain is derived from the authenticated user's email.
Display name for the organization. Used both as the org row name and (when auto-bootstrapping a member profile via the first agent registration) as the profile's display_name.
1 - 200"Acme Media"
Set to true to create a personal workspace instead of a corporate organization. Personal workspaces skip corporate-domain verification, are limited to one per user, and cannot host the company_* membership tiers.
Coarse classification of the organization's role in the open ad ecosystem. Drives default verification badges and the member profile's display category.
adtech, agency, brand, publisher, data, ai, other Annual revenue band, USD. Drives membership-tier eligibility for company-tier seats.
under_1m, 1m_5m, 5m_50m, 50m_250m, 250m_1b, 1b_plus Whether the caller opted in to AAO marketing communications. Recorded once per user (not overwritten on subsequent calls). Independent of Terms-of-Service consent, which is recorded server-side from the request context.
Response
Prospect adoption — an existing prospect organization for this domain was claimed by the caller. Body is { id, name, adopted: true }.
Response from POST /api/organizations. The body shape varies by path: a fresh creation returns { success: true, organization: { id, name } }; a prospect adoption returns { id, name, adopted: true } directly. Both paths are 2xx; downstream callers should treat any 2xx as "the org now exists and you are an owner of it" and read whichever id is present.
Show child attributes
Show child attributes
Set on the prospect-adoption path: when an org with the user's email domain already exists in a prospect state (i.e. the registry pre-recorded it from a brand crawl but no human had claimed it yet), this call adopts that org for the caller instead of creating a new one.
true when the response is the prospect-adoption path. When true, no new WorkOS organization was created — the caller is now the owner of an existing prospect record.
Was this page helpful?