Skip to main content
POST
Register an agent

Authorizations

Authorization
string
header
required

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-server and the protected-resource metadata at /.well-known/oauth-protected-resource/api.

Query Parameters

org
string

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.

Example:

"org_01HXZAB123"

Body

application/json

Request body for POST /api/me/agents. type is required — the owner declares it; the server never infers.

url
string<uri>
required
Example:

"https://agent.example.com/mcp"

type
enum<string>
required

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.

Available options:
brand,
rights,
measurement,
governance,
creative,
sales,
buying,
signals
name
string
visibility
enum<string>

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).

Available options:
private,
members_only,
public
health_check_url
string<uri>

Response

Agent already registered at this url; entry updated in place.

agent
object
required

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.

warnings
object[]
profile_auto_created
boolean

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.