---
title: "Update an agent"
method: PATCH
path: "/api/me/agents/{url}"
tags: ["Member Agents"]
---

# Update an agent

`PATCH /api/me/agents/{url}`

Update one registered agent identified by its `url`. The `url` field itself cannot be changed via PATCH — supplying a `url` in the body that differs from the path returns `400 url_immutable`; re-register at the new URL and DELETE the old entry to migrate. All other fields accept partial updates.

## 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. 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`.

## Request body

- MemberAgentPatch — 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` 'private' | 'members_only' | 'public' — 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).
  - `type` 'brand' | 'rights' | 'measurement' | 'governance' | 'creative' | 'sales' | 'buying' | 'signals' — 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.
  - `health_check_url` string, uri

## Response `200`

Agent updated.

- MemberAgentResponse
  - `agent` MemberAgent, 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.
    - `url` string, uri, required
    - `visibility` 'private' | 'members_only' | 'public', required — 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).
    - `type` 'brand' | 'rights' | 'measurement' | 'governance' | 'creative' | 'sales' | 'buying' | 'signals' | 'unknown', required — Agent type as stored on the registry. Server-side smuggle protection compares the caller's declaration against the capability snapshot (when one exists) and may stamp `unknown` if the snapshot contradicts the declaration without classifying it. `unknown` is reserved for that server-side outcome; clients cannot submit it.
    - `name` string
    - `health_check_url` string, uri — Optional fallback liveness URL used by the health probe when the protocol handshake fails.
  - `warnings` MemberAgentVisibilityWarning[]
    - `code` 'visibility_downgraded', required
    - `agent_url` string, required
    - `requested` 'public', required
    - `applied` 'members_only', required
    - `reason` 'tier_required', required
    - `message` string, required
  - `org_auto_created` boolean — 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.
  - `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.

## Other responses

- `400` — No organization associated with this account, or `body.url` differs from the path (`url_immutable`).
- `401` — Authentication required
- `403` — `?org=` was supplied but the caller is not a member of that organization.
- `404` — No member profile, or no agent registered at the given `url`.

---

[API](https://skmtc.net/adcontextprotocol/apis/agenticadvertising-org-registry-api.md) · [All operations](https://skmtc.net/adcontextprotocol/apis/agenticadvertising-org-registry-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/adcontextprotocol/agenticadvertising-org-registry-api/revisions/9ea7fedf54c0/schema)