API v1 Reference › Custom Agents

Updates the custom agent's configuration.

PUThttps://api.awork.com/api/v1/agents/{agentId}
PUT https://api.awork.com/api/v1/agents/{agentId}

Updates the custom agent's configuration and returns the saved agent. Saves a new system prompt version if the prompt changes.

Authentication

AuthorizationBearer

Send your token in the Authorization: Bearer <token> header. See Authentication for API keys and OAuth.

Path parameters

agentIdstringRequired
format: uuid

The agent id.

Request body Required

The new agent configuration.

application/json

namestringRequired
minLength: 1 maxLength: 255

The name shown to users.

descriptionstringRequired
maxLength: 25000

A short explanation of what the agent does.

workspaceAccessLevelstringRequired

Allowed: "none" "read" "manage"

minLength: 1 maxLength: 25

The access level granted to every member of the workspace.

modelProviderstring or nullOptional

The model provider when no preset is selected.

modelNamestring or nullOptional

The model name when no preset is selected.

presetKeystring or nullOptional

The workspace model preset to use.

reasoningLevelstringRequired
minLength: 1

The amount of reasoning the model uses.

systemPromptstringRequired
maxLength: 50000

The instructions that control the agent's behavior.

webSearchEnabledbooleanRequired

Whether web search is enabled.

aworkAccessEnabledbooleanRequired

Whether awork access is enabled.

googleGenAiAccessEnabledbooleanRequired

Whether Google image generation is enabled.

openAiImageGenerationAccessEnabledbooleanRequired

Whether OpenAI image generation is enabled.

Responses

200 OK

application/json

idstringOptional
format: uuid

The id of the entity.

createdOnstringOptional
format: date-time

The date this entity was created.

createdBystringOptional
format: uuid

The id of the user who created this entity.

updatedOnstringOptional
format: date-time

The date this entity was last modified.

updatedBystringOptional
format: uuid

The id of the user who last modified this entity.

isOfficialbooleanOptional

Whether a workspace admin marked this item as official. False when metadata is disabled.

tagsarray of object or nullOptional

The canonical AI tags. Empty when metadata is disabled.

Show 4 properties
idstringOptional
format: uuid

The stable identifier of this workspace tag.

namestring or nullOptional

The shared display name.

colorstring or nullOptional

The shared display color.

assignmentCountinteger or nullOptional
format: int32

The number of active agents, skills, and connectors that use this tag. Only set by the tag list.

canEditTagsbooleanOptional

Whether the current viewer can replace this item's tags.

canSetOfficialbooleanOptional

Whether the current viewer can change this item's official status.

typestring or nullOptional

The public agent type.

connectorsarray of object or nullOptional

The linked connectors.

Show 5 properties
idstringOptional
format: uuid

The linked connector identifier.

namestring or nullOptional

The connector name.

statusstring or nullOptional

Always pending in this shared response. It does not indicate whether an account is connected. Read the agent's configuration endpoint for the current user's connection status.

connectionModestring or nullOptional

How the agent chooses an account: actingUser lets each user supply their own; specificConnection uses the editor-provided account for everyone.

connectionIdstring or nullOptional
format: uuid

The editor-provided account id in specificConnection mode; otherwise null.

namestring or nullOptional

The name shown to users.

descriptionstring or nullOptional

A short explanation of what the agent does.

currentSystemPromptVersionIdstring or nullOptional
format: uuid

The current system prompt version.

modelProviderstring or nullOptional

The configured model provider when no preset is selected.

modelNamestring or nullOptional

The configured model name when no preset is selected.

presetKeystring or nullOptional

The configured workspace model preset key.

reasoningLevelstring or nullOptional

The configured reasoning level.

systemPromptstring or nullOptional

The current system prompt.

webSearchEnabledbooleanOptional

Whether web search is enabled.

aworkAccessEnabledbooleanOptional

Whether awork access is enabled.

googleGenAiAccessEnabledbooleanOptional

Whether Google image generation is enabled.

openAiImageGenerationAccessEnabledbooleanOptional

Whether OpenAI image generation is enabled.

skillIdsarray of string or nullOptional

The skills linked to the agent.

hasImagebooleanOptional

Whether the agent has a profile image.

isArchivedbooleanOptional

Whether the agent is archived.

workspaceAccessLevelstring or nullOptional

Allowed: "read" "manage"

The workspace-wide access level.

hasAdminAccessOnlybooleanOptional

Whether the agent is visible only through workspace administration access.

accessLevelstringOptional

Allowed: "read" "manage"

The requesting user's access level.

400 Bad Request

application/json

codestringRequired
minLength: 1

The error code.

descriptionstringRequired
minLength: 1

The description of the error.

linkstringRequired
minLength: 1

The link to the API documentation page.

detailsarray of string or nullOptional

A list of details describing the error.

validationErrorsarray of object or nullOptional

If a validation error occurred, this contains the validation errors for each property.

Show 2 properties
propertystring or nullOptional

The name of the property that failed validation.

messagestring or nullOptional

The reason why this property failed validation.

traceIdstring or nullOptional

The request trace id for tracking the request.

401 Unauthorized

application/json

codestringRequired
minLength: 1

The error code.

descriptionstringRequired
minLength: 1

The description of the error.

linkstringRequired
minLength: 1

The link to the API documentation page.

detailsarray of string or nullOptional

A list of details describing the error.

validationErrorsarray of object or nullOptional

If a validation error occurred, this contains the validation errors for each property.

Show 2 properties
propertystring or nullOptional

The name of the property that failed validation.

messagestring or nullOptional

The reason why this property failed validation.

traceIdstring or nullOptional

The request trace id for tracking the request.

404 Not Found

application/json

codestringRequired
minLength: 1

The error code.

descriptionstringRequired
minLength: 1

The description of the error.

linkstringRequired
minLength: 1

The link to the API documentation page.

detailsarray of string or nullOptional

A list of details describing the error.

validationErrorsarray of object or nullOptional

If a validation error occurred, this contains the validation errors for each property.

Show 2 properties
propertystring or nullOptional

The name of the property that failed validation.

messagestring or nullOptional

The reason why this property failed validation.

traceIdstring or nullOptional

The request trace id for tracking the request.

Search documentation