---
title: "Update an agent"
method: PATCH
path: "/v1/agents/{identifier}"
tags: ["Agents"]
---

# Update an agent

`PATCH /v1/agents/{identifier}`

## Request

- Base URL: `https://api.notifly.io`
- URL: `https://api.notifly.io/v1/agents/{identifier}`
- Auth: API key in header `Authorization`

Update an agent by its external identifier.

## Path parameters

- `identifier` string, required

## Request body

- UpdateAgentRequestDto
  - `name` string
  - `description` string
  - `active` boolean
  - `behavior` AgentBehaviorDto
    - `acknowledgeOnReceived` boolean: Acknowledge incoming messages. On platforms that support a native typing indicator (e.g. Slack, WhatsApp, Microsoft Teams, Telegram), shows a "Typing…" indicator while the agent processes the message. On platforms that do not (e.g. Email), reacts with an "eyes" emoji to the first inbound message in a thread. Default: true
    - `reactionOnResolved` object, nullable: Cross-platform emoji name for resolved conversations (e.g. "check", "star"). Set to null to disable. Default: "check"
    - `subscriberAccess` 'open' | 'restricted': Controls whether the agent accepts inbound messages from senders not yet linked to a subscriber, across all channels. "open" on managed agents auto-creates a lightweight subscriber so the agent can reply; on custom-code / self-hosted agents, the turn is forwarded to the bridge with a null subscriber. "restricted" rejects unknown senders with a managed denial reply (any runtime). Optional on update (partial PATCH). Persisted agents always have a value — managed create defaults to "open"; self-hosted create defaults to "restricted".
  - `bridgeUrl` string: Production bridge URL for this agent
  - `devBridgeUrl` string: Development bridge URL (set by npx novu dev)
  - `devBridgeActive` boolean: Whether the dev bridge override is active

## Response `200`

OK

- object
  - `data` AgentResponseDto
    - `_id` string, required
    - `name` string, required
    - `identifier` string, required
    - `description` string
    - `behavior` AgentBehaviorDto, required
      - `acknowledgeOnReceived` boolean: Acknowledge incoming messages. On platforms that support a native typing indicator (e.g. Slack, WhatsApp, Microsoft Teams, Telegram), shows a "Typing…" indicator while the agent processes the message. On platforms that do not (e.g. Email), reacts with an "eyes" emoji to the first inbound message in a thread. Default: true
      - `reactionOnResolved` object, nullable: Cross-platform emoji name for resolved conversations (e.g. "check", "star"). Set to null to disable. Default: "check"
      - `subscriberAccess` 'open' | 'restricted': Controls whether the agent accepts inbound messages from senders not yet linked to a subscriber, across all channels. "open" on managed agents auto-creates a lightweight subscriber so the agent can reply; on custom-code / self-hosted agents, the turn is forwarded to the bridge with a null subscriber. "restricted" rejects unknown senders with a managed denial reply (any runtime). Optional on update (partial PATCH). Persisted agents always have a value — managed create defaults to "open"; self-hosted create defaults to "restricted".
    - `active` boolean, required
    - `bridgeUrl` string: Production bridge URL
    - `devBridgeUrl` string: Development bridge URL (set by npx novu dev)
    - `devBridgeActive` boolean: Whether the dev bridge override is active
    - `runtime` 'self-hosted' | 'managed': Whether the agent brain is self-hosted (bridge) or managed by a third-party provider
    - `visibility` 'public' | 'private': Discovery scope of the agent. Always `public` today; reserved for the upcoming private-agents feature.
    - `managedRuntime` ManagedRuntimeResponseDto
      - `providerId` string, required
      - `integrationId` string, required
      - `externalAgentId` string, required
      - `externalEnvironmentId` string: The provider-side environment that hosts this agent. Hydrated from the linked integration credentials. Absent when the integration has not been provisioned.
      - `externalWorkspaceId` string: The provider-side workspace id used in console deep links. Defaults to `'default'` (the auto-created Default Workspace). Hydrated from the linked integration credentials.
      - `consoleUrl` string: Deep link to the agent in the provider console (e.g. platform.claude.com).
      - `tools` AgentToolDto[]: Live tools enabled on the managed-runtime provider for this agent. Sourced from the provider on read; omitted when the provider is temporarily unreachable.
        - `externalId` string, required
        - `name` string, required
        - `type` 'builtin' | 'custom', required
        - `description` string
      - `mcpServers` AgentMcpServerDto[]: MCP servers enabled on this agent, projected onto the runtime catalog `{ externalId, name, url }` shape. Mongo is the source of truth; the projection matches what the provider sees. Omitted when the provider read fails after a managed-agent write.
        - `externalId` string, required
        - `name` string, required
        - `url` string, required
      - `systemPrompt` string: System prompt used when invoking the agent.
    - `_environmentId` string, required
    - `_organizationId` string, required
    - `createdBy` string: Mongo user id of the user who created the agent
    - `createdAt` string, required
    - `updatedAt` string, required
    - `integrations` AgentIntegrationSummaryDto[]
      - `integrationId` string, required: Integration document id.
      - `providerId` string, required
      - `name` string, required
      - `identifier` string, required
      - `channel` 'in_app' | 'email' | 'sms' | 'chat' | 'push' | 'tool': Channel type through which the message is sent
      - `active` boolean, required
    - `exceedsPlanLimit` boolean: Cloud only. `true` when the agent falls outside the organization plan agent limit (by creation order among active agents — inactive agents do not consume slots). Only plan limits produce this flag — system-capped organizations (enterprise/unlimited tiers) are never over-limit. Over-limit agents are still stored but will not respond to inbound messages until the plan is upgraded or older agents are deactivated.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: The agent was not found.
- `405`: Method Not Allowed
- `409`: Conflict
- `413`: Payload Too Large
- `414`: URI Too Long
- `415`: Unsupported Media Type
- `422`: Unprocessable Entity
- `429`: The client has sent too many requests in a given amount of time.
- `500`: Internal Server Error
- `503`: The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

---

[API](https://skmtc.dev/notifly/apis/notifly-api.md) · [All operations](https://skmtc.dev/notifly/apis/notifly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/notifly/apis/notifly-api/revisions/af909b9e1e57?raw)