Updates the custom agent's configuration.

PUT

https://api.awork.com/api/v1/agents/:agentId

PUT

/api/v1/agents/:agentId

curl -X PUT https://api.awork.com/api/v1/agents/agentId \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Client Status Reporter",
  "description": "Prepares client-ready project status reports.",
  "workspaceAccessLevel": "manage",
  "reasoningLevel": "medium",
  "systemPrompt": "Prepare concise client-ready project updates from awork data.",
  "webSearchEnabled": true,
  "aworkAccessEnabled": true,
  "googleGenAiAccessEnabled": false,
  "openAiImageGenerationAccessEnabled": false
}'

{
  "id": "23e68187-91d6-4f7e-8d31-e3f2c60d7427",
  "createdOn": "2022-03-11T15:33:47.100Z",
  "createdBy": "9ad63972-4396-4b0b-9e7d-40b852cdebf8",
  "updatedOn": "2022-03-11T21:15:00.100Z",
  "updatedBy": "3d844c62-7410-4df9-a5b2-78805c0ee260",
  "type": "custom-agent",
  "connectors": [
    {
      "id": "23e68187-91d6-4f7e-8d31-e3f2c60d7427",
      "createdOn": "2022-03-11T15:33:47.100Z",
      "createdBy": "9ad63972-4396-4b0b-9e7d-40b852cdebf8",
      "updatedOn": "2022-03-11T21:15:00.100Z",
      "updatedBy": "3d844c62-7410-4df9-a5b2-78805c0ee260",
      "name": "Client CRM",
      "description": "HubSpot CRM for lead and client account research.",
      "url": null,
      "presetKey": "hubspot",
      "endpointValues": [
        {
          "key": "region",
          "labelKey": "dataRegion",
          "value": "eu",
          "displayLabelKey": "eu"
        }
      ],
      "logoPath": "images/integrations/hubspot_icon.svg",
      "status": "connected",
      "isSharedWithWorkspace": true,
      "isOwner": true,
      "currentUserConnectionStatus": "connected",
      "lastRefreshedOn": "2026-08-29T08:05:00Z",
      "currentUserLastAuthenticatedOn": "2026-08-29T08:00:00Z",
      "hasOAuthClientConfiguration": true,
      "connectionMode": "actingUser",
      "connectionId": "af18602d-c8aa-4f63-a21e-5a7f59b2412c",
      "currentUserConnectionId": "af18602d-c8aa-4f63-a21e-5a7f59b2412c",
      "connections": [
        {
          "id": "af18602d-c8aa-4f63-a21e-5a7f59b2412c",
          "connectorId": "7e376777-7834-4af6-9eb8-da065f568d30",
          "ownerUserId": "9ad63972-4396-4b0b-9e7d-40b852cdebf8",
          "name": "Client CRM connection",
          "externalIdentity": "account.manager@northstar.agency",
          "status": "connected",
          "isSharedWithWorkspace": true,
          "isOwner": true,
          "lastAuthenticatedOn": "2026-08-29T08:00:00Z",
          "lastRefreshedOn": "2026-08-29T08:05:00Z"
        }
      ]
    }
  ],
  "name": "Client Status Reporter",
  "description": "Prepares client-ready project status reports.",
  "currentSystemPromptVersionId": "fd077515-d4a8-4f79-9fbf-19271bd0123d",
  "modelProvider": "openai",
  "modelName": "gpt-5.6-terra",
  "presetKey": "balanced",
  "reasoningLevel": "medium",
  "systemPrompt": "Prepare concise client-ready project updates from awork data.",
  "webSearchEnabled": true,
  "aworkAccessEnabled": true,
  "googleGenAiAccessEnabled": false,
  "openAiImageGenerationAccessEnabled": false,
  "skillIds": [
    "string"
  ],
  "hasImage": true,
  "isArchived": false,
  "workspaceAccessLevel": "manage",
  "accessLevel": "manage"
}

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

Required Permissions

The user must have manage access to the agent. Changing workspace sharing also requires permission to contribute to the agent library.

Updates the custom agent's configuration and returns the saved agent. Saves a new system prompt version if the prompt changes. <Check title="Required Permissions" icon="key">The user must have manage access to the agent. Changing workspace sharing also requires permission to contribute to the agent library.</Check>

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

agentIdstringRequiredformat: "uuid"

The agent id.

Request

The new agent configuration.

namestringRequired1-255 characters

The name shown to users.

descriptionstringRequired<=25000 characters

A short explanation of what the agent does.

workspaceAccessLevelenumRequired

The access level granted to every member of the workspace.

reasoningLevelstringRequired>=1 character

The amount of reasoning the model uses.

systemPromptstringRequired<=25000 characters

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.

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.

Response

idstringOptionalformat: "uuid"

The id of the entity.

createdOnstringOptionalformat: "date-time"

The date this entity was created.

createdBystringOptionalformat: "uuid"

The id of the user who created this entity.

updatedOnstringOptionalformat: "date-time"

The date this entity was last modified.

updatedBystringOptionalformat: "uuid"

The id of the user who last modified this entity.

typestring or nullOptional

The public agent type.

connectorslist of objects or nullOptional

The linked connectors.

namestring or nullOptional

The name shown to users.

descriptionstring or nullOptional

A short explanation of what the agent does.

currentSystemPromptVersionIdstring or nullOptionalformat: "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.

skillIdslist of strings or nullOptional

The skills linked to the agent.

hasImagebooleanOptional

Whether the agent has a profile image.

isArchivedbooleanOptional

Whether the agent is archived.

workspaceAccessLevelenum or nullOptional

The workspace-wide access level.

accessLevelenumOptional

The requesting user's access level.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error