Skip to main content
PATCH
Update 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.

Path Parameters

url
string
required

The agent's url, URL-encoded (e.g. https%3A%2F%2Fagent.example.com%2Fmcp).

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 PATCH /api/me/agents/{url}. The url field cannot be changed via PATCH; re-register at the new URL and DELETE the old entry instead. If type is omitted, the existing value is preserved.

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
type
enum<string>

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
health_check_url
string<uri>

Response

Agent updated.

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.