---
title: "Create or replace a platform agent (super_admin; two-step; stale version answers 409)"
method: PUT
path: "/api/admin/agents/{agentId}"
tags: ["agents"]
---

# Create or replace a platform agent (super_admin; two-step; stale version answers 409)

`PUT /api/admin/agents/{agentId}`

## Request

- Base URL: `https://api.wizbi.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.wizbi.ai/api/admin/agents/{agentId}`
- Auth: none declared

## Path parameters

- `agentId` string, required

## Request body

- object
  - `agent` object, required
    - `id` string, required
    - `name` string, required
    - `description` string
    - `persona` string
    - `layers` object[]
      - `id` string, required: Stable id, e.g. "group", "dm", "guest", "shared_room".
      - `text` string, required
      - `when` object
        - `modes` string[]
        - `chatTypes` string[]
        - `channels` string[]
        - `roles` string[]
        - `flag` string
    - `tools` object
      - `allow` string[]
      - `deny` string[]
      - `connectors` string[]
    - `modes` object
      - `lean` object
        - `role` 'fast' | 'deep'
        - `maxRounds` integer
        - `thinkingBudget` integer
        - `toolCap` integer
        - `includeOrgSkill` boolean
      - `full` object
        - `role` 'fast' | 'deep'
        - `maxRounds` integer
        - `thinkingBudget` integer
        - `toolCap` integer
        - `includeOrgSkill` boolean
    - `defaultMode` 'lean' | 'full'
    - `escalation` boolean
    - `channels` string[]
    - `audience` 'everyone' | 'org_admins'
    - `chatTypes` string[]
    - `limits` object
      - `turnsPerDay` integer
      - `maxMessageChars` integer
    - `status` 'active' | 'disabled'
    - `version` integer
    - `updatedAt` string, date-time
    - `updatedBy` string
  - `expectedVersion` integer
  - `note` string
  - `confirm` boolean

## Response `200`

Preview or the saved agent.

- union
  - object
    - `preview` object, required
  - object
    - `id` string, required
    - `name` string, required
    - `description` string
    - `persona` string
    - `layers` object[]
      - `id` string, required: Stable id, e.g. "group", "dm", "guest", "shared_room".
      - `text` string, required
      - `when` object
        - `modes` string[]
        - `chatTypes` string[]
        - `channels` string[]
        - `roles` string[]
        - `flag` string
    - `tools` object
      - `allow` string[]
      - `deny` string[]
      - `connectors` string[]
    - `modes` object
      - `lean` object
        - `role` 'fast' | 'deep'
        - `maxRounds` integer
        - `thinkingBudget` integer
        - `toolCap` integer
        - `includeOrgSkill` boolean
      - `full` object
        - `role` 'fast' | 'deep'
        - `maxRounds` integer
        - `thinkingBudget` integer
        - `toolCap` integer
        - `includeOrgSkill` boolean
    - `defaultMode` 'lean' | 'full'
    - `escalation` boolean
    - `channels` string[]
    - `audience` 'everyone' | 'org_admins'
    - `chatTypes` string[]
    - `limits` object
      - `turnsPerDay` integer
      - `maxMessageChars` integer
    - `status` 'active' | 'disabled'
    - `version` integer
    - `updatedAt` string, date-time
    - `updatedBy` string

## Other responses

- `400`: Invalid request.
- `403`: Not allowed, or the feature is off for the organization.
- `404`: Unknown agent or version.
- `409`: Stale version.

---

[API](https://skmtc.dev/wizbi/apis/wizbi-core-api.md) · [All operations](https://skmtc.dev/wizbi/apis/wizbi-core-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wizbi/apis/wizbi-core-api/revisions/5a47416c82ec?raw)