# Update public agent

> Update public agent

- Source: https://www.taskade.com/docs/actions/update-public-agent
- Section: Action API
- Endpoint: `POST /updatePublicAgent` (API v2)
- Index of all pages: https://www.taskade.com/docs/llms.txt

## POST `/updatePublicAgent`

Update public agent

Base URL: `https://www.taskade.com/api/v2`

### Authentication

Send a personal access token or an OAuth 2.0 access token as a bearer token. Create a personal access token at [taskade.com/settings/api](https://www.taskade.com/settings/api).

```http
Authorization: Bearer tskdp_your_token_here
```

### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agentId` | `string` | Yes | — |
| `preferences` | `object` | Yes | — |
| `preferences.mode` | `string` | No | Allowed values: `template`, `chatbot`. |
| `preferences.canCopyKnowledge` | `boolean` | No | — |
| `preferences.hideBranding` | `boolean` | No | — |
| `preferences.theme` | `string` | No | Allowed values: `light`, `dark`, `auto`. |
| `preferences.autoEndChats` | `boolean` | No | — |
| `preferences.meta` | `object` | No | — |
| `preferences.meta.title` | `string` | No | — |
| `preferences.meta.description` | `string` | No | — |
| `preferences.meta.image` | `object` | No | — |
| `preferences.meta.image.ownerID` | `string` | Yes | — |
| `preferences.meta.image.ownerType` | `string` | No | — |
| `preferences.meta.image.id` | `string` | Yes | — |
| `preferences.meta.image.namespace` | `string` | Yes | — |
| `preferences.meta.image.extension` | `string` | Yes | — |
| `preferences.meta.image.s3KeyOriginal` | `string` | Yes | — |
| `preferences.meta.image.userID` | `number` | No | — |
| `preferences.meta.image.spaceID` | `string` | No | — |
| `preferences.meta.image.documentID` | `string` | No | — |
| `preferences.meta.image.nodeID` | `string` | No | — |
| `preferences.meta.image.size` | `number` | Yes | — |
| `preferences.meta.image.mimetype` | `string` | Yes | — |
| `preferences.meta.image.metadata` | `object` | No | — |
| `preferences.meta.image.type` | `string` | No | — |
| `preferences.meta.image.name` | `string` | No | — |
| `preferences.meta.image.description` | `string` | No | — |
| `preferences.color` | `string` | No | — |
| `preferences.launcherIcon` | `object` | No | — |
| `preferences.launcherIcon.type` | `string` | Yes | Allowed values: `emoji`, `custom`. |
| `preferences.launcherIcon.value` | `string` | Depends | Required when `type` is `emoji`. |
| `preferences.launcherIcon.image` | `object` | Depends | Required when `type` is `custom`. |
| `preferences.launcherIcon.image.ownerID` | `string` | Yes | — |
| `preferences.launcherIcon.image.ownerType` | `string` | No | — |
| `preferences.launcherIcon.image.id` | `string` | Yes | — |
| `preferences.launcherIcon.image.namespace` | `string` | Yes | — |
| `preferences.launcherIcon.image.extension` | `string` | Yes | — |
| `preferences.launcherIcon.image.s3KeyOriginal` | `string` | Yes | — |
| `preferences.launcherIcon.image.userID` | `number` | No | — |
| `preferences.launcherIcon.image.spaceID` | `string` | No | — |
| `preferences.launcherIcon.image.documentID` | `string` | No | — |
| `preferences.launcherIcon.image.nodeID` | `string` | No | — |
| `preferences.launcherIcon.image.size` | `number` | Yes | — |
| `preferences.launcherIcon.image.mimetype` | `string` | Yes | — |
| `preferences.launcherIcon.image.metadata` | `object` | No | — |
| `preferences.launcherIcon.image.type` | `string` | No | — |
| `preferences.launcherIcon.image.name` | `string` | No | — |
| `preferences.launcherIcon.image.description` | `string` | No | — |
| `preferences.widget` | `object` | No | — |
| `preferences.widget.mode` | `string` | No | Allowed values: `bubble`, `modal`, `sidebar`. |
| `preferences.widget.theme` | `object` | No | — |
| `preferences.widget.theme.colorScheme` | `string` | No | Allowed values: `host`. |
| `preferences.widget.theme.radius` | `string` | No | Allowed values: `none`, `small`, `medium`, `large`, `full`. |
| `preferences.widget.theme.density` | `string` | No | Allowed values: `compact`, `comfortable`, `spacious`. |
| `preferences.widget.theme.fontFamily` | `string` | No | — |
| `preferences.widget.popup` | `object` | No | — |
| `preferences.widget.popup.position` | `string` | No | Allowed values: `bottom-right`, `bottom-left`, `top-right`, `top-left`. |
| `preferences.widget.popup.offset` | `integer` | No | — |
| `preferences.widget.launcher` | `object` | No | — |
| `preferences.widget.launcher.hidden` | `boolean` | No | — |
| `preferences.widget.launcher.size` | `string` | No | Allowed values: `sm`, `md`, `lg`. |
| `preferences.widget.launcher.label` | `string` | No | — |
| `preferences.widget.launcher.backgroundColor` | `string` | No | — |
| `preferences.widget.behavior` | `object` | No | — |
| `preferences.widget.behavior.autoOpenDelay` | `integer` | No | — |
| `preferences.widget.behavior.proactiveMessage` | `object` | No | — |
| `preferences.widget.behavior.proactiveMessage.text` | `string` | Yes | — |
| `preferences.widget.visibility` | `object` | No | — |
| `preferences.widget.visibility.revealAfterScroll` | `integer` | No | — |
| `preferences.widget.visibility.hidePaths` | `string[]` | No | — |
| `preferences.widget.visibility.mobile` | `string` | No | Allowed values: `hide`. |

A nested field marked Yes is required whenever its parent object is present.

### Example request

```bash
curl -X POST "https://www.taskade.com/api/v2/updatePublicAgent" \
  -H "Authorization: Bearer $TASKADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"<agentId>","preferences":{}}'
```

### Responses

#### `200` — Default response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ok` | `boolean` | Yes | — |
| `item` | `object` | Yes | — |
| `item.id` | `string` | Yes | — |
| `item.name` | `string` | Yes | — |
| `item.data` | `object` | Yes | — |
| `item.data.avatar` | `object` | No | — |
| `item.data.avatar.type` | `string` | Yes | Allowed values: `custom`, `emoji`. |
| `item.data.avatar.data` | `object` | Yes | — |
| `item.data.avatar.data.file` | `object` | Yes | — |
| `item.data.conversationStarters` | `object[]` | No | — |
| `item.data.conversationStarters[].id` | `string` | Yes | — |
| `item.data.conversationStarters[].text` | `string` | Yes | — |
| `item.data.conversationStarters[].prompt` | `string` | No | — |
| `item.preferences` | `object` | Yes | — |
| `item.preferences.mode` | `string` | No | Allowed values: `template`, `chatbot`. |
| `item.preferences.canCopyKnowledge` | `boolean` | No | — |
| `item.preferences.hideBranding` | `boolean` | No | — |
| `item.preferences.theme` | `string` | No | Allowed values: `light`, `dark`, `auto`. |
| `item.preferences.autoEndChats` | `boolean` | No | — |
| `item.preferences.meta` | `object` | No | — |
| `item.preferences.meta.title` | `string` | No | — |
| `item.preferences.meta.description` | `string` | No | — |
| `item.preferences.meta.image` | `object` | No | — |
| `item.preferences.meta.image.ownerID` | `string` | Yes | — |
| `item.preferences.meta.image.ownerType` | `string` | No | — |
| `item.preferences.meta.image.id` | `string` | Yes | — |
| `item.preferences.meta.image.namespace` | `string` | Yes | — |
| `item.preferences.meta.image.extension` | `string` | Yes | — |
| `item.preferences.meta.image.s3KeyOriginal` | `string` | Yes | — |
| `item.preferences.meta.image.userID` | `number` | No | — |
| `item.preferences.meta.image.spaceID` | `string` | No | — |
| `item.preferences.meta.image.documentID` | `string` | No | — |
| `item.preferences.meta.image.nodeID` | `string` | No | — |
| `item.preferences.meta.image.size` | `number` | Yes | — |
| `item.preferences.meta.image.mimetype` | `string` | Yes | — |
| `item.preferences.meta.image.metadata` | `object` | No | — |
| `item.preferences.meta.image.type` | `string` | No | — |
| `item.preferences.meta.image.name` | `string` | No | — |
| `item.preferences.meta.image.description` | `string` | No | — |
| `item.preferences.color` | `string` | No | — |
| `item.preferences.launcherIcon` | `object` | No | — |
| `item.preferences.launcherIcon.type` | `string` | Yes | Allowed values: `emoji`, `custom`. |
| `item.preferences.launcherIcon.value` | `string` | Depends | Required when `type` is `emoji`. |
| `item.preferences.launcherIcon.image` | `object` | Depends | Required when `type` is `custom`. |
| `item.preferences.launcherIcon.image.ownerID` | `string` | Yes | — |
| `item.preferences.launcherIcon.image.ownerType` | `string` | No | — |
| `item.preferences.launcherIcon.image.id` | `string` | Yes | — |
| `item.preferences.launcherIcon.image.namespace` | `string` | Yes | — |
| `item.preferences.launcherIcon.image.extension` | `string` | Yes | — |
| `item.preferences.launcherIcon.image.s3KeyOriginal` | `string` | Yes | — |
| `item.preferences.launcherIcon.image.userID` | `number` | No | — |
| `item.preferences.launcherIcon.image.spaceID` | `string` | No | — |
| `item.preferences.launcherIcon.image.documentID` | `string` | No | — |
| `item.preferences.launcherIcon.image.nodeID` | `string` | No | — |
| `item.preferences.launcherIcon.image.size` | `number` | Yes | — |
| `item.preferences.launcherIcon.image.mimetype` | `string` | Yes | — |
| `item.preferences.launcherIcon.image.metadata` | `object` | No | — |
| `item.preferences.launcherIcon.image.type` | `string` | No | — |
| `item.preferences.launcherIcon.image.name` | `string` | No | — |
| `item.preferences.launcherIcon.image.description` | `string` | No | — |
| `item.preferences.widget` | `object` | No | — |
| `item.preferences.widget.mode` | `string` | No | Allowed values: `bubble`, `modal`, `sidebar`. |
| `item.preferences.widget.theme` | `object` | No | — |
| `item.preferences.widget.theme.colorScheme` | `string` | No | Allowed values: `host`. |
| `item.preferences.widget.theme.radius` | `string` | No | Allowed values: `none`, `small`, `medium`, `large`, `full`. |
| `item.preferences.widget.theme.density` | `string` | No | Allowed values: `compact`, `comfortable`, `spacious`. |
| `item.preferences.widget.theme.fontFamily` | `string` | No | — |
| `item.preferences.widget.popup` | `object` | No | — |
| `item.preferences.widget.popup.position` | `string` | No | Allowed values: `bottom-right`, `bottom-left`, `top-right`, `top-left`. |
| `item.preferences.widget.popup.offset` | `integer` | No | — |
| `item.preferences.widget.launcher` | `object` | No | — |
| `item.preferences.widget.launcher.hidden` | `boolean` | No | — |
| `item.preferences.widget.launcher.size` | `string` | No | Allowed values: `sm`, `md`, `lg`. |
| `item.preferences.widget.launcher.label` | `string` | No | — |
| `item.preferences.widget.launcher.backgroundColor` | `string` | No | — |
| `item.preferences.widget.behavior` | `object` | No | — |
| `item.preferences.widget.behavior.autoOpenDelay` | `integer` | No | — |
| `item.preferences.widget.behavior.proactiveMessage` | `object` | No | — |
| `item.preferences.widget.visibility` | `object` | No | — |
| `item.preferences.widget.visibility.revealAfterScroll` | `integer` | No | — |
| `item.preferences.widget.visibility.hidePaths` | `string[]` | No | — |
| `item.preferences.widget.visibility.mobile` | `string` | No | Allowed values: `hide`. |

### Errors

Errors return an `ok: false` envelope. Rate limiting returns `429` with `x-rate-limit-limit`, `x-rate-limit-remaining` and `x-rate-limit-reset` headers. `x-rate-limit-reset` is the number of seconds until the window reopens. `Retry-After` is not sent, so schedule retries from `x-rate-limit-reset`; retrying sooner will fail again.

```json
{ "ok": false, "message": "Unauthorized", "code": "UNAUTHORIZED" }
```

Rate limits for this version: enforced per endpoint; ceilings are not published and can change without notice. A `429` response carries `x-rate-limit-limit`, `x-rate-limit-remaining`, and `x-rate-limit-reset` (seconds until the window reopens). Back off from those headers rather than hardcoding numbers. If you need sustained throughput, prefer batching (operations like `/createTask` accept arrays) over tightening polling loops. See [Rate limits](https://www.taskade.com/docs/getting-started/action-api-guide#rate-limits).