---
updatedAt: 2026-07-31T12:37:05.000Z
---

# Replace an Agent

Fully replaces an agent (SCIM 2.0 PUT). Immutable fields (`id`, `meta`) are ignored.

**Entitlements:**
- `tenantAdmin` — full access (all operations)
- `agentOwner` — full create, read, update, and delete access, and status changes
- `writeAgents` — update metadata only; cannot change status
- `manageAgentStatus` — update status only; all other fields must match existing values

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "version": "1.0.0",
    "description": "AI Agents",
    "title": "AI Agents"
  },
  "servers": [
    {
      "url": "https://{tenanturl}",
      "variables": {
        "tenanturl": {
          "default": "{tenant_url}",
          "description": "URL of your IBM Security Verify tenant"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Agent management",
      "description": "SCIM 2.0 compliant agent operations"
    }
  ],
  "paths": {
    "/v1.0/Agents/{id}": {
      "put": {
        "tags": [
          "Agent management"
        ],
        "summary": "Replace an Agent",
        "description": "Fully replaces an agent (SCIM 2.0 PUT). Immutable fields (`id`, `meta`) are ignored.\n\n**Entitlements:**\n- `tenantAdmin` — full access (all operations)\n- `agentOwner` — full create, read, update, and delete access, and status changes\n- `writeAgents` — update metadata only; cannot change status\n- `manageAgentStatus` — update status only; all other fields must match existing values",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Unique identifier of the agent (UUID)",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Complete agent data for replacement",
          "content": {
            "*/*": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAgentRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Agent replaced successfully",
            "content": {}
          },
          "400": {
            "description": "Bad Request - Invalid request payload (CSINH1002E), validation errors (CSINH2100E-CSINH2112E), or immutable field modification (CSINH2111E)",
            "content": {}
          },
          "401": {
            "description": "Unauthorized - Authentication required",
            "content": {}
          },
          "403": {
            "description": "Forbidden - Insufficient permissions (CSINH2501E), unauthorized status change (CSINH2506E), or unauthorized field change (CSINH2507E)",
            "content": {}
          },
          "404": {
            "description": "Not Found - Agent not found (CSINH2001E)",
            "content": {}
          },
          "409": {
            "description": "Conflict - Agent with same displayName or externalId already exists (CSINH2002E)",
            "content": {}
          },
          "500": {
            "description": "Internal Server Error (CSINH1000E)",
            "content": {}
          }
        },
        "x-category": "AI Agents",
        "x-publicAPI": "true",
        "x-codegen-request-body-name": "payload"
      }
    }
  },
  "components": {
    "schemas": {
      "UpdateAgentRequest": {
        "required": [
          "displayName",
          "schemas"
        ],
        "type": "object",
        "properties": {
          "schemas": {
            "type": "array",
            "description": "**REQUIRED** - SCIM schema URIs",
            "example": [
              "urn:ietf:params:scim:schemas:core:ibm:2.0:Agent"
            ],
            "items": {
              "type": "string"
            }
          },
          "displayName": {
            "maxLength": 256,
            "type": "string",
            "description": "**REQUIRED** - Human-readable name for the agent. Must be unique within tenant. Max 256 characters.",
            "example": "Production API Service"
          },
          "status": {
            "type": "string",
            "description": "Agent status. Optional in PUT — if not provided, defaults to `UNDER_REVIEW`.",
            "example": "ACTIVE",
            "enum": [
              "DEFAULT",
              "ACTIVE",
              "SUSPENDED",
              "UNDER_REVIEW"
            ]
          },
          "description": {
            "maxLength": 1024,
            "type": "string",
            "description": "Detailed description of the agent's purpose (optional). Max 1024 characters.",
            "example": "API service for production workloads"
          },
          "externalIds": {
            "maxItems": 1000,
            "type": "array",
            "description": "External identifiers from source systems (optional). Each externalId must be unique within the tenant. Max 1000 items, each max 128 chars.",
            "example": [
              "ext-agent-123",
              "legacy-id-456"
            ],
            "items": {
              "maxLength": 128,
              "type": "string"
            }
          },
          "owners": {
            "type": "array",
            "description": "Owner user IDs (optional).",
            "items": {
              "$ref": "#/components/schemas/Owner"
            }
          },
          "tags": {
            "type": "array",
            "description": "Custom tags for categorization (optional).",
            "example": [
              "production",
              "api-service"
            ],
            "items": {
              "type": "string"
            }
          },
          "authMethods": {
            "type": "array",
            "description": "Authentication methods (optional). Each requires 'name' (unique within agent, max 128 chars) and 'type'.",
            "items": {
              "$ref": "#/components/schemas/AuthMethod"
            }
          }
        },
        "description": "Agent update request schema for PUT operations. Both 'schemas' and 'displayName' are required."
      },
      "AuthMethod": {
        "required": [
          "name",
          "type"
        ],
        "type": "object",
        "properties": {
          "name": {
            "maxLength": 128,
            "type": "string",
            "description": "Unique identifier for this authentication method within the agent (max 128 chars)",
            "example": "primary-jwt-auth"
          },
          "type": {
            "type": "string",
            "description": "Type of authentication method",
            "example": "jwt",
            "enum": [
              "jwt",
              "certificate",
              "oidc",
              "oauth",
              "apikey",
              "mtls",
              "svid-jwt",
              "svid-x509"
            ]
          },
          "display": {
            "type": "string",
            "description": "Human-readable name",
            "example": "JWT Authentication"
          },
          "attributes": {
            "type": "array",
            "description": "Additional attributes for the authentication method",
            "example": [
              "iss=https://issuer.example.com",
              "sub=service-account"
            ],
            "items": {
              "type": "string"
            }
          }
        },
        "description": "Authentication method configuration"
      },
      "Owner": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "description": "Unique identifier of the owner",
            "example": "user-123"
          },
          "type": {
            "type": "string",
            "description": "Type of owner",
            "example": "User",
            "enum": [
              "User",
              "Group",
              "Role",
              "Agent"
            ]
          },
          "$ref": {
            "type": "string",
            "description": "URI reference to the owner resource",
            "example": "/cdprofilemgmt/v2.0/Users/user-123"
          },
          "display": {
            "type": "string",
            "description": "Display name of the owner (auto-populated from Cloud Directory)",
            "example": "John Doe"
          }
        },
        "description": "Owner reference (User, Group, Role, or Agent)"
      }
    }
  },
  "x-original-swagger-version": "2.0",
  "x-explorer-enabled": false
}
```