> ## Documentation Index
> Fetch the complete documentation index at: https://darwin.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update agent

> Update selected fields of an owned agent.

Read [Get agent](/docs/reference/studio-get-agent), then send its `revision` as `expectedRevision`, the fields to change, and an `Idempotency-Key`. Omitted fields stay unchanged. Use `avatarUrl: null` to clear an image. A stale revision or handle conflict returns `409`; reread and review the change before retrying with a new key.


## OpenAPI

````yaml openapi-publish.json PATCH /v3/publish/agent/{agentId}
openapi: 3.1.0
info:
  title: Publish
  version: 3.0.0
  description: >-
    Owner-authorized agent and operation publishing, operating decisions and
    analytics, and durable campaign management. Publishing records does not
    bypass independent execution verification. Campaign submission requests
    review; it does not activate delivery or authorize spending.
servers:
  - url: https://api.darwin.so/api
security: []
paths:
  /v3/publish/agent/{agentId}:
    patch:
      tags:
        - Publish
      summary: Update agent
      description: >-
        Update selected profile fields with expectedRevision. Omitted fields are
        unchanged. A stale revision or duplicate handle returns 409.
      operationId: update_published_agent
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            Stable key for this exact mutation. Reusing it with different input
            returns 409.
          schema:
            type: string
            minLength: 1
            maxLength: 200
        - name: agentId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                handle:
                  type: string
                  pattern: ^[a-z0-9](?:[a-z0-9-]{0,39}[a-z0-9])?$
                name:
                  type: string
                  minLength: 1
                  maxLength: 160
                description:
                  type: string
                  maxLength: 5000
                avatarUrl:
                  anyOf:
                    - type: string
                      maxLength: 2000
                      format: uri
                    - type: 'null'
                visibility:
                  type: string
                  enum:
                    - PRIVATE
                    - RESTRICTED
                    - PUBLIC
                expectedRevision:
                  type: integer
                  minimum: 1
                  maximum: 2147483647
              required:
                - expectedRevision
              additionalProperties: false
            example:
              expectedRevision: 1
              name: Acme Weather Worldwide
      responses:
        '200':
          description: >-
            Current owner-scoped result. A mutation retry returns its saved
            response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    type: object
                    properties:
                      agentId:
                        type: string
                      handle:
                        anyOf:
                          - type: string
                          - type: 'null'
                      name:
                        type: string
                      description:
                        anyOf:
                          - type: string
                          - type: 'null'
                      avatarUrl:
                        anyOf:
                          - type: string
                          - type: 'null'
                      visibility:
                        type: string
                      revision:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      createdAt:
                        type: string
                        format: date-time
                        pattern: >-
                          ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                      updatedAt:
                        type: string
                        format: date-time
                        pattern: >-
                          ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    required:
                      - agentId
                      - handle
                      - name
                      - description
                      - avatarUrl
                      - visibility
                      - revision
                      - createdAt
                      - updatedAt
                    additionalProperties: false
                required:
                  - agent
                additionalProperties: false
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type:
                      - string
                      - array
                  code:
                    type: string
        '401':
          description: Missing or invalid credentials.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type:
                      - string
                      - array
                  code:
                    type: string
        '403':
          description: Insufficient scope or user authority.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type:
                      - string
                      - array
                  code:
                    type: string
        '404':
          description: Resource is absent or not owned by this caller.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type:
                      - string
                      - array
                  code:
                    type: string
        '409':
          description: Revision, handle, idempotency, or decision conflict.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type:
                      - string
                      - array
                  code:
                    type: string
        '503':
          description: Canonical product storage or migration is unavailable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type:
                      - string
                      - array
                  code:
                    type: string
      security:
        - apiKey: []
        - apiKeyBearer: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
    apiKeyBearer:
      type: http
      scheme: bearer
      description: A Darwin API key supplied as an Authorization Bearer token.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.