curl --request GET \
--url https://api.naturalead.ai/api/agent-config \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.naturalead.ai/api/agent-config"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.naturalead.ai/api/agent-config', 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.naturalead.ai/api/agent-config",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.naturalead.ai/api/agent-config"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.naturalead.ai/api/agent-config")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.naturalead.ai/api/agent-config")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body[
{
"_id": "<string>",
"accountId": "<string>",
"name": "<string>",
"systemPrompt": "<string>",
"goal": "<string>",
"status": "active",
"language": "English",
"instructions": "<string>",
"qualificationCriteria": "<string>",
"handoffMessage": "I'll connect you with a specialist who can help further!",
"stages": [
{
"id": "<string>",
"name": "<string>",
"order": 123,
"prompt": "<string>",
"transitionCriteria": "<string>",
"maxMessages": 0,
"nextStages": [
{
"id": "<string>",
"condition": "<string>"
}
],
"nextStageIds": [
"<string>"
],
"knowledgeBaseIds": [
"<string>"
],
"stageInsights": [
{
"fieldName": "<string>",
"instructions": "<string>"
}
],
"position": {
"x": 123,
"y": 123
}
}
],
"inboundEntries": [
{
"targetStageId": "<string>",
"condition": "<string>"
}
],
"guardrails": {
"maxTotalMessages": 40,
"inactivityTimeoutMinutes": 1440,
"forbiddenTopics": "",
"escalationTriggers": ""
},
"knowledgeBaseIds": [
"<string>"
],
"mcpServerIds": [
"<string>"
],
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
]{
"error": "<string>"
}List Agents
Returns all agent configurations for the current account.
Pass ?single=true for legacy single-agent mode (returns a single object
instead of an array, creating a default agent if none exists).
Requires agent_config:view permission.
curl --request GET \
--url https://api.naturalead.ai/api/agent-config \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.naturalead.ai/api/agent-config"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.naturalead.ai/api/agent-config', 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.naturalead.ai/api/agent-config",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.naturalead.ai/api/agent-config"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.naturalead.ai/api/agent-config")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.naturalead.ai/api/agent-config")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body[
{
"_id": "<string>",
"accountId": "<string>",
"name": "<string>",
"systemPrompt": "<string>",
"goal": "<string>",
"status": "active",
"language": "English",
"instructions": "<string>",
"qualificationCriteria": "<string>",
"handoffMessage": "I'll connect you with a specialist who can help further!",
"stages": [
{
"id": "<string>",
"name": "<string>",
"order": 123,
"prompt": "<string>",
"transitionCriteria": "<string>",
"maxMessages": 0,
"nextStages": [
{
"id": "<string>",
"condition": "<string>"
}
],
"nextStageIds": [
"<string>"
],
"knowledgeBaseIds": [
"<string>"
],
"stageInsights": [
{
"fieldName": "<string>",
"instructions": "<string>"
}
],
"position": {
"x": 123,
"y": 123
}
}
],
"inboundEntries": [
{
"targetStageId": "<string>",
"condition": "<string>"
}
],
"guardrails": {
"maxTotalMessages": 40,
"inactivityTimeoutMinutes": 1440,
"forbiddenTopics": "",
"escalationTriggers": ""
},
"knowledgeBaseIds": [
"<string>"
],
"mcpServerIds": [
"<string>"
],
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
]{
"error": "<string>"
}Authorizations
Bearer token using an API key (format nl_live_* or nl_test_*)
Query Parameters
Legacy flag — when true, returns a single AgentConfig object via getOrCreate
Response
Agent configurations
MongoDB ObjectId
Account ObjectId this agent belongs to
Agent display name
System prompt sent to the LLM for every conversation
High-level goal for the agent
active, inactive, draft Conversation language
Additional instructions for the agent
Deprecated. Ignored by the conversation engine. Journey outcomes are terminal stages (no outgoing edges); advancement uses transitionCriteria and nextStages edge conditions.
Message sent when the conversation is handed off to a human
Ordered conversation stages
Show child attributes
Show child attributes
First-touch inbound landings (WhatsApp). Evaluated only when a conversation is created from an inbound message — not on later replies. Empty condition is the default landing.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
ObjectIds of attached knowledge bases
ObjectIds of attached MCP servers. Populated as full objects (minus
credentials) on GET /api/agent-config/{id}. Managed through the
dedicated attach/detach endpoints; sending it on create or update
also works and is validated for account ownership.