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.
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.