Update an agent

PATCH

agents

{identifier}

TypeScript

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});

async function run() {
  const result = await novu.agents.update({}, "<value>");

  console.log(result);
}

run();

curl --request PATCH \
  --url https://api.novu.co/v1/agents/{identifier} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "active": true,
  "behavior": {
    "acknowledgeOnReceived": true,
    "reactionOnResolved": "check"
  },
  "bridgeUrl": "<string>",
  "devBridgeUrl": "<string>",
  "devBridgeActive": true
}
'

import requests

url = "https://api.novu.co/v1/agents/{identifier}"

payload = {
    "name": "<string>",
    "description": "<string>",
    "active": True,
    "behavior": {
        "acknowledgeOnReceived": True,
        "reactionOnResolved": "check"
    },
    "bridgeUrl": "<string>",
    "devBridgeUrl": "<string>",
    "devBridgeActive": True
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    active: true,
    behavior: {acknowledgeOnReceived: true, reactionOnResolved: 'check'},
    bridgeUrl: '<string>',
    devBridgeUrl: '<string>',
    devBridgeActive: true
  })
};

fetch('https://api.novu.co/v1/agents/{identifier}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.novu.co/v1/agents/{identifier}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'active' => true,
    'behavior' => [
        'acknowledgeOnReceived' => true,
        'reactionOnResolved' => 'check'
    ],
    'bridgeUrl' => '<string>',
    'devBridgeUrl' => '<string>',
    'devBridgeActive' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.novu.co/v1/agents/{identifier}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"active\": true,\n  \"behavior\": {\n    \"acknowledgeOnReceived\": true,\n    \"reactionOnResolved\": \"check\"\n  },\n  \"bridgeUrl\": \"<string>\",\n  \"devBridgeUrl\": \"<string>\",\n  \"devBridgeActive\": true\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.novu.co/v1/agents/{identifier}")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"active\": true,\n  \"behavior\": {\n    \"acknowledgeOnReceived\": true,\n    \"reactionOnResolved\": \"check\"\n  },\n  \"bridgeUrl\": \"<string>\",\n  \"devBridgeUrl\": \"<string>\",\n  \"devBridgeActive\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.novu.co/v1/agents/{identifier}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"active\": true,\n  \"behavior\": {\n    \"acknowledgeOnReceived\": true,\n    \"reactionOnResolved\": \"check\"\n  },\n  \"bridgeUrl\": \"<string>\",\n  \"devBridgeUrl\": \"<string>\",\n  \"devBridgeActive\": true\n}"

response = http.request(request)
puts response.read_body

{
  "_id": "<string>",
  "name": "<string>",
  "identifier": "<string>",
  "active": true,
  "_environmentId": "<string>",
  "_organizationId": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "description": "<string>",
  "behavior": {
    "acknowledgeOnReceived": true,
    "reactionOnResolved": "check"
  },
  "bridgeUrl": "<string>",
  "devBridgeUrl": "<string>",
  "devBridgeActive": true,
  "managedRuntime": {
    "providerId": "<string>",
    "integrationId": "<string>",
    "externalAgentId": "<string>",
    "externalEnvironmentId": "<string>",
    "externalWorkspaceId": "<string>",
    "consoleUrl": "<string>",
    "tools": [
      {
        "externalId": "<string>",
        "name": "<string>",
        "description": "<string>"
      }
    ],
    "mcpServers": [
      {
        "externalId": "<string>",
        "name": "<string>",
        "url": "<string>"
      }
    ],
    "systemPrompt": "<string>"
  },
  "createdBy": "<string>",
  "integrations": [
    {
      "integrationId": "<string>",
      "providerId": "<string>",
      "name": "<string>",
      "identifier": "<string>",
      "active": true
    }
  ],
  "exceedsPlanLimit": true
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "errors": {
    "fieldName1": {
      "messages": [
        "Field is required",
        "Must be a valid email address"
      ],
      "value": "invalidEmail"
    },
    "fieldName2": {
      "messages": [
        "Must be at least 18 years old"
      ],
      "value": 17
    },
    "fieldName3": {
      "messages": [
        "Must be a boolean value"
      ],
      "value": true
    },
    "fieldName4": {
      "messages": [
        "Must be a valid object"
      ],
      "value": {
        "key": "value"
      }
    },
    "fieldName5": {
      "messages": [
        "Field is missing"
      ],
      "value": null
    },
    "fieldName6": {
      "messages": [
        "Undefined value"
      ]
    }
  },
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"API rate limit exceeded"

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"Please wait some time, then try again."

Authorizations

Authorization

string

header

required

API key authentication. Allowed headers-- "Authorization: ApiKey <novu_secret_key>".

Headers

idempotency-key

string

A header for idempotency purposes

Path Parameters

identifier

string

required

Body

application/json

name

string

Maximum string length: 60

description

string

active

boolean

behavior

object

Show child attributes

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

_id

string

required

name

string

required

identifier

string

required

active

boolean

required

_environmentId

string

required

_organizationId

string

required

createdAt

string

required

updatedAt

string

required

description

string

behavior

object

Show child attributes

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

enum<string>

Whether the agent brain is self-hosted (bridge) or managed by a third-party provider

Available options:

self-hosted,

managed

visibility

enum<string>

Discovery scope of the agent. Always public today; reserved for the upcoming private-agents feature.

Available options:

public,

private

managedRuntime

object

Present when runtime is "managed". Contains provider and external identifiers.

Show child attributes

createdBy

string

Mongo user id of the user who created the agent

integrations

object[]

Show child attributes

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.

Retrieve an agent

Delete an agent

⌘I

TypeScript

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});

async function run() {
  const result = await novu.agents.update({}, "<value>");

  console.log(result);
}

run();

curl --request PATCH \
  --url https://api.novu.co/v1/agents/{identifier} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "active": true,
  "behavior": {
    "acknowledgeOnReceived": true,
    "reactionOnResolved": "check"
  },
  "bridgeUrl": "<string>",
  "devBridgeUrl": "<string>",
  "devBridgeActive": true
}
'

import requests

url = "https://api.novu.co/v1/agents/{identifier}"

payload = {
    "name": "<string>",
    "description": "<string>",
    "active": True,
    "behavior": {
        "acknowledgeOnReceived": True,
        "reactionOnResolved": "check"
    },
    "bridgeUrl": "<string>",
    "devBridgeUrl": "<string>",
    "devBridgeActive": True
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    active: true,
    behavior: {acknowledgeOnReceived: true, reactionOnResolved: 'check'},
    bridgeUrl: '<string>',
    devBridgeUrl: '<string>',
    devBridgeActive: true
  })
};

fetch('https://api.novu.co/v1/agents/{identifier}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.novu.co/v1/agents/{identifier}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'active' => true,
    'behavior' => [
        'acknowledgeOnReceived' => true,
        'reactionOnResolved' => 'check'
    ],
    'bridgeUrl' => '<string>',
    'devBridgeUrl' => '<string>',
    'devBridgeActive' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.novu.co/v1/agents/{identifier}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"active\": true,\n  \"behavior\": {\n    \"acknowledgeOnReceived\": true,\n    \"reactionOnResolved\": \"check\"\n  },\n  \"bridgeUrl\": \"<string>\",\n  \"devBridgeUrl\": \"<string>\",\n  \"devBridgeActive\": true\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.novu.co/v1/agents/{identifier}")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"active\": true,\n  \"behavior\": {\n    \"acknowledgeOnReceived\": true,\n    \"reactionOnResolved\": \"check\"\n  },\n  \"bridgeUrl\": \"<string>\",\n  \"devBridgeUrl\": \"<string>\",\n  \"devBridgeActive\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.novu.co/v1/agents/{identifier}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"active\": true,\n  \"behavior\": {\n    \"acknowledgeOnReceived\": true,\n    \"reactionOnResolved\": \"check\"\n  },\n  \"bridgeUrl\": \"<string>\",\n  \"devBridgeUrl\": \"<string>\",\n  \"devBridgeActive\": true\n}"

response = http.request(request)
puts response.read_body

{
  "_id": "<string>",
  "name": "<string>",
  "identifier": "<string>",
  "active": true,
  "_environmentId": "<string>",
  "_organizationId": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "description": "<string>",
  "behavior": {
    "acknowledgeOnReceived": true,
    "reactionOnResolved": "check"
  },
  "bridgeUrl": "<string>",
  "devBridgeUrl": "<string>",
  "devBridgeActive": true,
  "managedRuntime": {
    "providerId": "<string>",
    "integrationId": "<string>",
    "externalAgentId": "<string>",
    "externalEnvironmentId": "<string>",
    "externalWorkspaceId": "<string>",
    "consoleUrl": "<string>",
    "tools": [
      {
        "externalId": "<string>",
        "name": "<string>",
        "description": "<string>"
      }
    ],
    "mcpServers": [
      {
        "externalId": "<string>",
        "name": "<string>",
        "url": "<string>"
      }
    ],
    "systemPrompt": "<string>"
  },
  "createdBy": "<string>",
  "integrations": [
    {
      "integrationId": "<string>",
      "providerId": "<string>",
      "name": "<string>",
      "identifier": "<string>",
      "active": true
    }
  ],
  "exceedsPlanLimit": true
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "errors": {
    "fieldName1": {
      "messages": [
        "Field is required",
        "Must be a valid email address"
      ],
      "value": "invalidEmail"
    },
    "fieldName2": {
      "messages": [
        "Must be at least 18 years old"
      ],
      "value": 17
    },
    "fieldName3": {
      "messages": [
        "Must be a boolean value"
      ],
      "value": true
    },
    "fieldName4": {
      "messages": [
        "Must be a valid object"
      ],
      "value": {
        "key": "value"
      }
    },
    "fieldName5": {
      "messages": [
        "Field is missing"
      ],
      "value": null
    },
    "fieldName6": {
      "messages": [
        "Undefined value"
      ]
    }
  },
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"API rate limit exceeded"

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"Please wait some time, then try again."

Getting Started

Notification delivery

Agents

Data

Workflows & content

Platform & channels

Update an agent

Authorizations

Headers

Path Parameters

Body

Response