# Tag API - Update

Use this endpoint to update an existing tag. You can update the name, group assignment, description, and display names.

---

## Endpoint

```
PATCH https://e1.envoke.com/v2/tags/{ID}
```

Replace `{ID}` with the Envoke tag ID you want to update. Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON.

---

## Request Body

At least one field must be provided.

| Field | Type | Description |
|---|---|---|
| `name` | string | New tag name. |
| `group` | string or integer | Group name or group ID to assign. Pass `""` (empty string) or `null` to remove the group assignment. |
| `description` | string | Updated internal description. |
| `display_names` | object | Translated display labels keyed by ISO language code. |

`external_id` is silently ignored if included in the request body. If `id` is included, it must match the `{ID}` in the URL — if they differ, a validation error is returned: `"Provided 'id': {url_id} does not match 'id' in request body ({body_id})"`.

---

## Response

On success, the API returns the updated tag object:

```json
{
  "success": true,
  "result_text": "Updated",
  "result_data": {
    "id": "42",
    "external_id": "a1b2c3d4e5f6",
    "name": "Updated Tag Name",
    "group": "Events",
    "description": "Updated description",
    "display_names": { "en": "Updated Tag" }
  }
}
```

---

## Validation Errors

```json
{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": [
      "Item with id '999999' not found"
    ]
  }
}
```

Common errors:

| Error | Cause |
|---|---|
| `Request body may not be empty` | No JSON body was provided. |
| `Item with id '{id}' not found` | The `{ID}` in the URL does not match any tag in your account. |
| `Invalid 'group': '{value}'` | The group was not found or is not of type `interest`. |
| `Provided 'id': {url_id} does not match 'id' in request body ({body_id})` | `id` in the request body differs from `{ID}` in the URL. |

---

## Examples

### Rename a tag

```bash
curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Organic Certification Members"}' \
  "https://e1.envoke.com/v2/tags/42"
```

### Assign to a group

```bash
curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group": "Certification Programs"}' \
  "https://e1.envoke.com/v2/tags/42"
```

### Remove group assignment

```bash
curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group": ""}' \
  "https://e1.envoke.com/v2/tags/42"
```

### Update display names

```bash
curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_names": {"en": "Organic", "fr": "Biologique"}}' \
  "https://e1.envoke.com/v2/tags/42"
```

### Update multiple fields at once

```bash
curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Organic Members", "group": "Certification Programs", "description": "Members pursuing organic certification"}' \
  "https://e1.envoke.com/v2/tags/42"
```

---

*Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.*

*Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).*