Update mutable agent fields (visibility / mcpEnabled).
Patch a narrow set of caller-managed agent properties. The
whitelist is intentionally minimal — description, name,
version, avatar_url, capabilities, and skills are
reconciled from the pod-side POST /api/v1/agents/sync and
would silently revert on the next sync if patched here.
Authorisation: caller MUST own the agent. Public discovery uses the
agent-card endpoints; this management resource never bypasses owner
scope. Patches with no recognised fields fail with
invalid_param.
Authorizations
Pass a user JWT or a oag_ User API Key on the
Authorization: Bearer <token> header. Both are validated by
openapi-gateway against the Auth service.
Both credential types are user-scoped: every key (and every JWT) is bound to exactly one owner, and every route grants the caller full access to that owner's own resources. Cross-tenant access is denied by owner-ACL inside the handlers — there is no per-route scope vocabulary on this API.
Removed in v1.1.0: the legacy
agents:*/tasks:*/files:*/instances:*scope set has been dropped together with the403 insufficient_scopeerror. Existingoag_keys automatically gain full owner-level access and do not need to be re-issued. SDK calls that previously passedscopestocreateAPIKeyshould drop the argument. See the changelog at the bottom of this spec for the full migration note.
Path Parameters
128Body
Body for PATCH /api/v1/agents/{agentId} (P1-B). Whitelist
intentionally narrow — description / name / version /
avatar_url / capabilities / skills are owned by the pod-side
POST /api/v1/agents/sync and would silently revert if patched
here. The empty object and unknown properties are rejected. If both
MCP key spellings are supplied, their boolean values must agree.
Agent ACL bucket. private is owner-only; public lets any
authenticated caller invoke; unlisted is invokable but
absent from public listings; marketplace is catalog-visible.
private, unlisted, public, marketplace Whether the agent shows up under MCP Gateway's tools/list.
Independent of visibility — an unlisted agent can still
be MCP-exposed; a public agent without MCP is invoke-only.
Deprecated snake_case alias for mcpEnabled.