PATCH /agents/{agentId}/public-agent
Update public agent
Base URL: https://www.taskade.com/api/v1
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
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agentId |
path | string |
Yes | — |
Request body
application/json
| Field | Type | Required | Description |
|---|---|---|---|
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 PATCH "https://www.taskade.com/api/v1/agents/<agentId>/public-agent" \
-H "Authorization: Bearer $TASKADE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"preferences":{}}'
Responses
200 — Public Agent
| 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. |
4XX — Error description
| Field | Type | Required | Description |
|---|---|---|---|
ok |
boolean |
Yes | — |
message |
string |
Yes | — |
code |
string |
Yes | — |
statusMessage |
string |
Yes | — |
featureId |
string |
No | The plan entitlement the request needs, set on some PAYMENT_REQUIRED errors. |
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. Bundle import and export run under tighter limits than regular reads and writes, so schedule bulk transfers accordingly. See Rate limits.