Skip to main content
PATCH
/
api
/
v1
/
agents
/
{agentId}
Update mutable agent fields (visibility / mcp_enabled).
curl --request PATCH \
  --url https://openapi.beeos.ai/api/v1/agents/{agentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mcp_enabled": true
}
'
{
  "success": true,
  "data": {
    "id": "<string>",
    "instanceId": "<string>",
    "name": "<string>",
    "status": "<string>",
    "mcpEnabled": true,
    "description": "<string>",
    "displayName": "<string>",
    "slug": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

Authorizations

​
Authorization
string
header
required

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 the 403 insufficient_scope error. Existing oag_ keys automatically gain full owner-level access and do not need to be re-issued. SDK calls that previously passed scopes to createAPIKey should drop the argument. See the changelog at the bottom of this spec for the full migration note.

Path Parameters

​
agentId
string
required
Maximum string length: 128

Body

application/json

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 is rejected with invalid_param.

​
visibility
enum<string>

Agent ACL bucket. private is owner-only; public lets any authenticated caller invoke; unlisted is invokable but absent from public listings. The org bucket is reserved for P1-C when the org-scope ACL lands.

Available options:
private,
unlisted,
public
​
mcp_enabled
boolean

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.

Response

Updated agent details.

​
success
boolean
required
​
data
object
required