Update a collab agent's draft | Athena

Write a collab agent’s configuration (system prompt, model, tools, sources, behavior and channel settings) to its draft. Only the fields you send change; an omitted field keeps its current value, and a list or text field you send replaces the old one whole. The write goes to the live draft, the same draft the Athena editor shows, under the asset’s existing id. Once the asset has been published, runs keep using the published version until you publish the draft with POST /api/v0/assets/{asset_id}/publish; one never published runs from its draft. Requires edit access to the asset; an archived asset is refused with 409. Unknown fields are refused with 422. A model must be available in the agent’s workspace (422 otherwise). Tool or toolkit IDs the registry does not know are written and reported under warnings. A new name also becomes the asset title. The agent’s email address and its outbound approval recipients are not set here.

Authentication

X-API-KEYstring

API Key authentication via header

Path parameters

asset_idstringRequired

ID of the collab agent to update

Request

This endpoint expects an object.

accent_colorstring or nullOptional

UI accent color (hex)

auto_compaction_enabledboolean or nullOptional

Auto-compaction

available_toolkitslist of strings or nullOptional

Toolkit IDs available for the agent to select

blacklisted_toolslist of strings or nullOptional

Tool IDs the agent may not use

can_be_subagentboolean or nullOptional

Whether the agent can be used as a sub-agent

comments_pane_enabledboolean or nullOptional

Allow @-mentioning the agent in an asset’s comments pane

context_injectionboolean or nullOptional

Inject contextual information into replies

descriptionstring or nullOptional

What the agent does and when to use it

handlestring or nullOptional

Voice-friendly handle (lowercase words and spaces) used to address the agent as a sub-agent

iconstring or nullOptional

Icon identifier

knowledge_baselist of strings or nullOptional

Knowledge base references available to the agent

knowledge_base_tagslist of strings or nullOptional

Tags used to filter knowledge base context

max_past_messages_for_subagentsinteger or nullOptional

Maximum number of past messages passed to sub-agents

meeting_attendance_enabledboolean or nullOptional

Allow the agent to attend meetings

meeting_voice_enabledboolean or nullOptional

The agent's meeting voice

modelstring or nullOptional

Model ID the agent runs on; must be available in its workspace

muses_enabledboolean or nullOptional

Muses long-term memory

muses_recall_enabledboolean or nullOptional

Inject relevant Muses memory before each reply

namestring or nullOptional

Display name of the agent; also becomes the asset title

parallel_tool_callsboolean or nullOptional

Parallel tool calls

permanent_enabled_toolslist of strings or nullOptional

Tool IDs that stay enabled whatever else is configured

plan_mode_enabledboolean or nullOptional

Plan Mode

remove_session_computerboolean or nullOptional

True stops giving the agent’s sessions a computer (existing computers are kept). Not together with session_computer.

session_computerobject or nullOptional

Give the agent's sessions a computer the platform creates from an environment

show_only_for_adminboolean or nullOptional

Show the agent only to workspace admins

sms_blocked_sender_modestring or nullOptional

How the agent answers a text from a workspace member it isn’t shared with: ‘default’ (the standard no-access message), ‘silent’ (no reply) or ‘custom’ (sms_blocked_sender_reply verbatim). The text is always saved in the agent’s SMS thread and the agent never runs; senders without an Athena account in the workspace never get a reply.

sms_blocked_sender_replystring or nullOptional

Reply text sent to blocked SMS senders when sms_blocked_sender_mode is ‘custom’, e.g. ‘Got it, thanks.’ (max 320 characters).

sms_enabledboolean or nullOptional

SMS access

sourceslist of strings or nullOptional

Knowledge source references: native source IDs, or collab_source:<asset_id>; replaces the list

strict_agent_configurationboolean or nullOptional

Whether the agent must follow strict configuration constraints

sub_agentslist of strings or nullOptional

Collab agent IDs available as sub-agents

suggestionslist of maps from strings to any or nullOptional

Suggested prompts or actions shown for the agent

system_promptstring or nullOptional

The instructions the agent follows (markdown); replaces the whole prompt

temperaturedouble or nullOptional

Sampling temperature override

toolkitslist of strings or nullOptional

Toolkit IDs the agent can use; replaces the list

toolslist of strings or nullOptional

Tool IDs the agent can use; replaces the list

voice_enabledboolean or nullOptional

Voice access

voice_sub_agentslist of strings or nullOptional

Collab agent IDs available as voice sub-agents

whitelisted_emailslist of strings or nullOptional

Email addresses allowed to use the agent

Response

Successful Response

asset_idstring

ID of the updated asset

asset_typestring

Type of the asset: skill or collab_agent

publishedboolean

Always false: the write changed the draft only. Publish it with POST /api/v0/assets/{asset_id}/publish.

titlestring

Title of the asset after the write

warningslist of stringsOptional

Non-fatal notes, such as tool or toolkit IDs the registry does not know

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

503

Service Unavailable Error