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

# Update Agent Group

Use this API to update an agent group's `name` and/or `description`.

<Warning>
  This endpoint updates **only** `name` and `description`. It **cannot** change membership; use [Add Agents](/docs/api-reference/rest-apis/v2/agents/groups/add-agents) / [Remove Agents](/docs/api-reference/rest-apis/v2/agents/groups/remove-agents) for that. `metadata` is **immutable** after creation. Sending `metadata`, `agentIds`, or any other unknown field is rejected with a validation error (`.strict()`).
</Warning>

At least one of `name` or `description` must be provided; an empty update is rejected.

<Warning>
  System groups (`copy-qa`, `seo`, `design-checks`, `performance`, `brand-checks`) are not protected from renaming. Passing one of their ids renames it like any other group, and the new name persists for every user in the workspace. There is no way to restore the original name except by setting it again yourself.
</Warning>

# Endpoint

`POST https://api.velt.dev/v2/agents/groups/update`

# Headers

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/docs/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="groupId" type="string" required>
      Min 1 char. Agent group id.
    </ParamField>

    <ParamField body="name" type="string">
      New group name. Trimmed, min 1 char, max 200 chars. Required if `description` is omitted.
    </ParamField>

    <ParamField body="description" type="string">
      New description. Trimmed, max 2000 chars. Required if `name` is omitted.
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

```JSON theme={null}
{
  "data": {
    "groupId": "K3mR7pQxN2vB9wLdT4sY",
    "name": "Brand QA (v2)",
    "description": "Updated brand-quality agent set"
  }
}
```

# Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Agent group updated successfully",
    "data": {
      "group": {
        "id": "K3mR7pQxN2vB9wLdT4sY",
        "name": "Brand QA (v2)",
        "description": "Updated brand-quality agent set",
        "agentIds": ["abc123def456", "spell-check"],
        "metadata": { "apiKey": "ak_xxx" },
        "createdAt": 1711900000000,
        "updatedAt": 1711950000000
      }
    }
  }
}
```

Returns the updated group document, the same shape as [Get Group](/docs/api-reference/rest-apis/v2/agents/groups/get). System groups carry `system: true`; groups you created omit the field.

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "NOT_FOUND"
  }
}
```

**Errors:**

* `NOT_FOUND`: the group does not exist.
* `INVALID_ARGUMENT`: neither `name` nor `description` provided, over-length values, or unknown fields (e.g. `metadata`, `agentIds`) sent.

<ResponseExample>
  ```js theme={null}
  {
    "result": {
      "status": "success",
      "message": "Agent group updated successfully",
      "data": {
        "group": {
          "id": "K3mR7pQxN2vB9wLdT4sY",
          "name": "Brand QA (v2)",
          "agentIds": ["abc123def456"],
          "metadata": { "apiKey": "ak_xxx" },
          "createdAt": 1711900000000,
          "updatedAt": 1711950000000
        }
      }
    }
  }
  ```
</ResponseExample>