Management
Create an agent
Create an agent scoped to the current environment. The identifier must be unique per environment. Set runtime to managed and supply managedRuntime to provision a provider-hosted agent brain.
POST
/
v1
/
agents
TypeScript
import { Novu } from "@novu/api";
const novu = new Novu({
secretKey: "YOUR_SECRET_KEY_HERE",
});
async function run() {
const result = await novu.agents.create({
name: "<value>",
identifier: "<value>",
}, "<value>");
console.log(result);
}
run();curl --request POST \
--url https://api.novu.co/v1/agents \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Novu-Analytics-Source: <novu-analytics-source>' \
--data '
{
"name": "<string>",
"identifier": "<string>",
"description": "<string>",
"active": true
}
'import requests
url = "https://api.novu.co/v1/agents"
payload = {
"name": "<string>",
"identifier": "<string>",
"description": "<string>",
"active": True
}
headers = {
"Novu-Analytics-Source": "<novu-analytics-source>",
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Novu-Analytics-Source': '<novu-analytics-source>',
Authorization: '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '<string>',
identifier: '<string>',
description: '<string>',
active: true
})
};
fetch('https://api.novu.co/v1/agents', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'identifier' => '<string>',
'description' => '<string>',
'active' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json",
"Novu-Analytics-Source: <novu-analytics-source>"
],
]);
$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"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"identifier\": \"<string>\",\n \"description\": \"<string>\",\n \"active\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Novu-Analytics-Source", "<novu-analytics-source>")
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.post("https://api.novu.co/v1/agents")
.header("Novu-Analytics-Source", "<novu-analytics-source>")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"identifier\": \"<string>\",\n \"description\": \"<string>\",\n \"active\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.novu.co/v1/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Novu-Analytics-Source"] = '<novu-analytics-source>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"identifier\": \"<string>\",\n \"description\": \"<string>\",\n \"active\": 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",
"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
API key authentication. Allowed headers-- "Authorization: ApiKey <novu_secret_key>".
Body
application/json
Required when not adopting an existing managed agent (i.e. when managedRuntime.externalAgentId is absent). Optional in adopt mode where the name is resolved from the provider.
Maximum string length:
60Required when not adopting an existing managed agent. Auto-generated from the provider agent name when omitted in adopt mode.
Pattern:
SLUG_IDENTIFIER_REGEXAvailable options:
self-hosted, managed Show child attributes
Show child attributes
Response
Created
Show child attributes
Show child attributes
Production bridge URL
Development bridge URL (set by npx novu dev)
Whether the dev bridge override is active
Whether the agent brain is self-hosted (bridge) or managed by a third-party provider
Available options:
self-hosted, managed Discovery scope of the agent. Always public today; reserved for the upcoming private-agents feature.
Available options:
public, private Present when runtime is "managed". Contains provider and external identifiers.
Show child attributes
Show child attributes
Mongo user id of the user who created the agent
Show child attributes
Show child attributes
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.
Was this page helpful?
⌘I
TypeScript
import { Novu } from "@novu/api";
const novu = new Novu({
secretKey: "YOUR_SECRET_KEY_HERE",
});
async function run() {
const result = await novu.agents.create({
name: "<value>",
identifier: "<value>",
}, "<value>");
console.log(result);
}
run();curl --request POST \
--url https://api.novu.co/v1/agents \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Novu-Analytics-Source: <novu-analytics-source>' \
--data '
{
"name": "<string>",
"identifier": "<string>",
"description": "<string>",
"active": true
}
'import requests
url = "https://api.novu.co/v1/agents"
payload = {
"name": "<string>",
"identifier": "<string>",
"description": "<string>",
"active": True
}
headers = {
"Novu-Analytics-Source": "<novu-analytics-source>",
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Novu-Analytics-Source': '<novu-analytics-source>',
Authorization: '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '<string>',
identifier: '<string>',
description: '<string>',
active: true
})
};
fetch('https://api.novu.co/v1/agents', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'identifier' => '<string>',
'description' => '<string>',
'active' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json",
"Novu-Analytics-Source: <novu-analytics-source>"
],
]);
$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"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"identifier\": \"<string>\",\n \"description\": \"<string>\",\n \"active\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Novu-Analytics-Source", "<novu-analytics-source>")
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.post("https://api.novu.co/v1/agents")
.header("Novu-Analytics-Source", "<novu-analytics-source>")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"identifier\": \"<string>\",\n \"description\": \"<string>\",\n \"active\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.novu.co/v1/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Novu-Analytics-Source"] = '<novu-analytics-source>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"identifier\": \"<string>\",\n \"description\": \"<string>\",\n \"active\": 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",
"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."