Agents

Update agent

Changed on Oct 28, 2026

Apply a partial update to an existing agent configuration.

Gateway contract

The Node gateway validates the request body via Zod middleware before forwarding to the Python agent service. The agentKey path param and the request body are both validated. Query parameters are ignored by the controller, and body fields the validator does not know are dropped rather than refused. The body may be omitted: an empty update succeeds and changes nothing.

Update semantics

Only fields present in the request body are updated. models may be omitted (the agent's existing models are kept), set to an empty array (clears the agent's models so it falls back to the organization's default LLM at chat time), or set to a non-empty array. When a non-empty array is provided, the gateway Zod middleware requires at least one object entry with isReasoning: true.

Permissions

The authenticated user must have can_edit on the agent (typically the owner). Service-account and shareWithOrg transitions follow additional Python business rules.

Success response

Returns a lightweight success envelope only. Use GET /agents/{agentKey} to read the persisted agent after an update.

put/agents/{agentKey}

Request

Base URL
https://app.pipeshub.com/api/v1
URL
https://app.pipeshub.com/api/v1/agents/{agentKey}
Auth
- HTTP bearer
- or OAuth 2
  Authorization code: /api/v1/oauth2/authorize
  Client credentials
  Token URL: /api/v1/oauth2/token scopes: agent:write

Path parameters

agentKeystring required

Unique agent identifier

Request body

namestring

Agent display name. Surrounding whitespace is trimmed; a blank name is refused with 400 (VALIDATION_ERROR).

descriptionstring

What the agent does

startMessagestring

Initial greeting shown when conversation starts

systemPromptstring

System instructions for the agent

instructionsstring

Additional agent execution instructions

tagsstring[]

shareWithOrgboolean

Share agent with the organization

isServiceAccountboolean

Mark agent as a service account

serviceAccountUserIdstring nullable

The userId of the service account this agent should search knowledge as. Only valid on a service-account agent, checked against what the agent will be once the request is applied, so one request may convert an agent and bind it. Null is accepted on any agent and clears the binding, going back to searching as the agent's creator. Whitespace around it is removed first; 1-128 characters.

defaultReasoningEffort'none' | 'low' | 'medium' | 'high' | 'max' nullable

Agent-level reasoning effort used when a chat request omits its own.

apiToolsetToolsstring[]

API toolset operations the agent may call, each <toolsetId>:<operation> (see /api-toolsets). A service-account agent may only use toolsets with a shared credential.

sendUserContextboolean

When true (default), include the current user's name, email, and organization in this agent's system prompt. When false, omit that profile data.

Example request

{
  "name": "Renamed Agent"
}

Response

Agent updated successfully

status'success' required

messagestring required

Example response

{
  "message": "Agent updated successfully"
}

Changes

Oct 28, 2026dbb5e203b445 Revision changes
- breaking
  added to the // request property allOf list
- breaking
  removed subschema #1 subschema #2 from the request property anyOf list
- breaking
  removed the enum value calendar of the request property //
- breaking
  removed the enum value clickup of the request property //
- breaking
  removed the enum value confluence of the request property //
- breaking
  removed the enum value confluencedatacenter of the request property //
- breaking
  removed the enum value docs of the request property //
- breaking
  removed the enum value drive of the request property //
- breaking
  removed the enum value github of the request property //
- breaking
  removed the enum value gmail of the request property //
- breaking
  removed the enum value jira of the request property //
- breaking
  removed the enum value jiradatacenter of the request property //
- breaking
  removed the enum value lumos of the request property //
- breaking
  removed the enum value mariadb of the request property //
- breaking
  removed the enum value onedrive of the request property //
- breaking
  removed the enum value outlook of the request property //
- breaking
  removed the enum value redshift of the request property //
- breaking
  removed the enum value salesforce of the request property //
- breaking
  removed the enum value sharepoint of the request property //
- breaking
  removed the enum value sheets of the request property //
- breaking
  removed the enum value slack of the request property //
- breaking
  removed the enum value teams of the request property //
- breaking
  removed the enum value zoom of the request property //
- breaking
  the // request property's minLength was increased from 0 to 1
- breaking
  the request property's minLength was increased from 0 to 1
- breaking
  the //// request property's minLength was increased from 0 to 1
- breaking
  the //// request property's minLength was increased from 0 to 1
- breaking
  removed subschema #1 subschema #2 from the / request property oneOf list
- breaking
  added the pattern \S to the request property //
- breaking
  added the pattern \S to the request property
- breaking
  added the pattern \S to the request property ////
- breaking
  added the pattern \S to the request property ////
- breaking
  the // request property type changed from string to no type
- warning
  the request property's maxLength was set to 128
- info
  added the new optional request property
- info
  request body became optional
- info
  added subschema #1 subschema #2 to the request property anyOf list
- info
  added subschema #1 subschema #2 to the / request property oneOf list
Oct 26, 2026fc76aa045994 Revision changes
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new docs enum value to the request property //
- info
  added the new sheets enum value to the request property //

Operation history (6 revisions)