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>",
"health_check_url": "<string>"
}
'import requests
url = "https://agenticadvertising.org/api/me/agents"
payload = {
"url": "https://agent.example.com/mcp",
"name": "<string>",
"health_check_url": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://agent.example.com/mcp',
name: '<string>',
health_check_url: '<string>'
})
};
fetch('https://agenticadvertising.org/api/me/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agenticadvertising.org/api/me/agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://agent.example.com/mcp',
'name' => '<string>',
'health_check_url' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agenticadvertising.org/api/me/agents"
payload := strings.NewReader("{\n \"url\": \"https://agent.example.com/mcp\",\n \"name\": \"<string>\",\n \"health_check_url\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agenticadvertising.org/api/me/agents")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://agent.example.com/mcp\",\n \"name\": \"<string>\",\n \"health_check_url\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agenticadvertising.org/api/me/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"https://agent.example.com/mcp\",\n \"name\": \"<string>\",\n \"health_check_url\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"agent": {
"url": "https://agent.example.com/mcp",
"visibility": "private",
"type": "brand",
"name": "<string>",
"health_check_url": "<string>"
},
"warnings": [
{
"code": "visibility_downgraded",
"agent_url": "<string>",
"requested": "public",
"applied": "members_only",
"reason": "tier_required",
"message": "<string>"
}
],
"profile_auto_created": true
}{
"agent": {
"url": "https://agent.example.com/mcp",
"visibility": "private",
"type": "brand",
"name": "<string>",
"health_check_url": "<string>"
},
"warnings": [
{
"code": "visibility_downgraded",
"agent_url": "<string>",
"requested": "public",
"applied": "members_only",
"reason": "tier_required",
"message": "<string>"
}
],
"profile_auto_created": true
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}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.
The organization must already exist. Human credentials select it explicitly with ?org=; an API key uses the exact organization scope returned by WorkOS. The endpoint never creates an organization. If the existing organization has no member profile, the server creates a private profile and includes profile_auto_created: true.
type is required and declared by the caller — the server does not infer it. Server-side smuggle protection still cross-checks the declared type against the agent’s capability snapshot when one exists; if the snapshot contradicts the declaration without classifying it, the stored value is unknown and the dashboard surfaces the conflict for the owner to resolve.
visibility: "public" requires a paid AAO tier (Professional, Builder, Member, or Leader) and a verified primary domain on the organization (set via the Linked Domains UI). Non-API-tier callers (Explorer or no tier) 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>",
"health_check_url": "<string>"
}
'import requests
url = "https://agenticadvertising.org/api/me/agents"
payload = {
"url": "https://agent.example.com/mcp",
"name": "<string>",
"health_check_url": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://agent.example.com/mcp',
name: '<string>',
health_check_url: '<string>'
})
};
fetch('https://agenticadvertising.org/api/me/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agenticadvertising.org/api/me/agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://agent.example.com/mcp',
'name' => '<string>',
'health_check_url' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agenticadvertising.org/api/me/agents"
payload := strings.NewReader("{\n \"url\": \"https://agent.example.com/mcp\",\n \"name\": \"<string>\",\n \"health_check_url\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agenticadvertising.org/api/me/agents")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://agent.example.com/mcp\",\n \"name\": \"<string>\",\n \"health_check_url\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agenticadvertising.org/api/me/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"https://agent.example.com/mcp\",\n \"name\": \"<string>\",\n \"health_check_url\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"agent": {
"url": "https://agent.example.com/mcp",
"visibility": "private",
"type": "brand",
"name": "<string>",
"health_check_url": "<string>"
},
"warnings": [
{
"code": "visibility_downgraded",
"agent_url": "<string>",
"requested": "public",
"applied": "members_only",
"reason": "tier_required",
"message": "<string>"
}
],
"profile_auto_created": true
}{
"agent": {
"url": "https://agent.example.com/mcp",
"visibility": "private",
"type": "brand",
"name": "<string>",
"health_check_url": "<string>"
},
"warnings": [
{
"code": "visibility_downgraded",
"agent_url": "<string>",
"requested": "public",
"applied": "members_only",
"reason": "tier_required",
"message": "<string>"
}
],
"profile_auto_created": true
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}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. Human sessions and user JWTs must select it explicitly. WorkOS API keys may omit it because their validated credential already carries an exact organization scope; when supplied with an API key it must match that scope.
"org_01HXZAB123"
Body
Request body for POST /api/me/agents. type is required — the owner declares it; the server never infers.
"https://agent.example.com/mcp"
Agent type the caller declares. Required on register; smuggle-protection still cross-checks against the capability snapshot when one exists. The server never infers type — the owner declares what kind of agent this is.
brand, rights, measurement, governance, creative, sales, buying, signals 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 a paid AAO tier — Professional, Builder, Member, or Leader).
private, members_only, public Response
Agent already registered at this url; entry updated in place.
Agent entry stored on a member profile. type is required on read because every write surface declares it and the operator endpoint always emits it; a stored value of unknown is the smuggle-protection outcome (snapshot contradicted the declaration without classifying it) and is the only path that surfaces an agent without a real type.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
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?