Run an agent now
curl --request POST \
--url https://api.neoagent.io/public-api/agents/{agent_id}/run-now \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"additional_custom_instructions": "<string>",
"bypass_entities_filter": true,
"supervised_run": {
"approver_ids": [
"<string>"
]
},
"target_entity_id": "<string>",
"target_entity_ids": [
"<string>"
],
"test_ticket": {
"description": "<string>",
"psa_company_id": "<string>",
"title": "<string>",
"psa_contact_id": "<string>"
}
}
'import requests
url = "https://api.neoagent.io/public-api/agents/{agent_id}/run-now"
payload = {
"additional_custom_instructions": "<string>",
"bypass_entities_filter": True,
"supervised_run": { "approver_ids": ["<string>"] },
"target_entity_id": "<string>",
"target_entity_ids": ["<string>"],
"test_ticket": {
"description": "<string>",
"psa_company_id": "<string>",
"title": "<string>",
"psa_contact_id": "<string>"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
additional_custom_instructions: '<string>',
bypass_entities_filter: true,
supervised_run: {approver_ids: ['<string>']},
target_entity_id: '<string>',
target_entity_ids: ['<string>'],
test_ticket: {
description: '<string>',
psa_company_id: '<string>',
title: '<string>',
psa_contact_id: '<string>'
}
})
};
fetch('https://api.neoagent.io/public-api/agents/{agent_id}/run-now', 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.neoagent.io/public-api/agents/{agent_id}/run-now",
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([
'additional_custom_instructions' => '<string>',
'bypass_entities_filter' => true,
'supervised_run' => [
'approver_ids' => [
'<string>'
]
],
'target_entity_id' => '<string>',
'target_entity_ids' => [
'<string>'
],
'test_ticket' => [
'description' => '<string>',
'psa_company_id' => '<string>',
'title' => '<string>',
'psa_contact_id' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.neoagent.io/public-api/agents/{agent_id}/run-now"
payload := strings.NewReader("{\n \"additional_custom_instructions\": \"<string>\",\n \"bypass_entities_filter\": true,\n \"supervised_run\": {\n \"approver_ids\": [\n \"<string>\"\n ]\n },\n \"target_entity_id\": \"<string>\",\n \"target_entity_ids\": [\n \"<string>\"\n ],\n \"test_ticket\": {\n \"description\": \"<string>\",\n \"psa_company_id\": \"<string>\",\n \"title\": \"<string>\",\n \"psa_contact_id\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.neoagent.io/public-api/agents/{agent_id}/run-now")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"additional_custom_instructions\": \"<string>\",\n \"bypass_entities_filter\": true,\n \"supervised_run\": {\n \"approver_ids\": [\n \"<string>\"\n ]\n },\n \"target_entity_id\": \"<string>\",\n \"target_entity_ids\": [\n \"<string>\"\n ],\n \"test_ticket\": {\n \"description\": \"<string>\",\n \"psa_company_id\": \"<string>\",\n \"title\": \"<string>\",\n \"psa_contact_id\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.neoagent.io/public-api/agents/{agent_id}/run-now")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"additional_custom_instructions\": \"<string>\",\n \"bypass_entities_filter\": true,\n \"supervised_run\": {\n \"approver_ids\": [\n \"<string>\"\n ]\n },\n \"target_entity_id\": \"<string>\",\n \"target_entity_ids\": [\n \"<string>\"\n ],\n \"test_ticket\": {\n \"description\": \"<string>\",\n \"psa_company_id\": \"<string>\",\n \"title\": \"<string>\",\n \"psa_contact_id\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": "<unknown>",
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"timings_ms": {},
"pagination": {
"has_more": true,
"next_cursor": "<string>"
},
"warnings": [
"<string>"
]
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}Agents
Run an agent now
Triggers a run immediately. Async — returns {"execution_id": "<temporal_run_id>", "status": "queued"}; poll GET /executions/<execution_id> for completion. Triggered agents need target_entity_id in the body; scheduled agents need nothing. target_entity_ids (1 to 100, instead of target_entity_id) starts one run per entity in one call and returns {"runs": [{"target_entity_id", "execution_id", "status": "queued" | "failed", "error"}]}; a failed entity does not stop the others. bypass_entities_filter: true runs a triggered agent on its target entities even when they do not match the agent’s ticket filter. Both are refused (400 validation_error) on a scheduled agent. test_ticket (instead of a target entity) runs a triggered agent with an Agent step on a ticket written for this run: title, description, psa_company_id and an optional psa_contact_id of that company. The ticket is in no PSA. The agent’s changes to it (notes, time entries, fields, merges, messages through it) stay in the run, and everything else it does is real. The run’s entity_id is the ticket’s neo-test- id, and its entity_number is Test ticket. Refused (400 validation_error) when the company or contact is not in the PSA, on a scheduled agent, and on a workflow without an Agent step. Conversational agents are rejected (400 invalid_for_conversational) — reach them via POST /chat/sessions. supervised_run makes this one run supervised: every change waits for one of the named approver_ids to approve it, and those technicians replace the agent’s own approvers for the run. An agent in test mode can run supervised: it still asks, but every change is simulated, approved or not. Refused (400 validation_error) for a workflow or an agent that processes entities sequentially, and (409 agent_run_in_progress) when the agent is already running on that entity, because a start against a live execution arrives as a signal whose arguments are dropped. A target_entity_ids call still returns 202 and reports that conflict as the entity’s failed result. A disabled agent runs too, as with the dashboard’s Run now, and stays disabled for its own triggers and schedule. At-least-once: a retried 5xx can produce a duplicate run. additional_custom_instructions reaches only an Agent step and Dispatch Ticket, here or in a workflow this one triggers; every other step ignores it and runs in full; the run still starts, and meta.warnings says so. An acting user needs view access to the agent, and a Viewer may run it.
POST
/
public-api
/
agents
/
{agent_id}
/
run-now
Run an agent now
curl --request POST \
--url https://api.neoagent.io/public-api/agents/{agent_id}/run-now \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"additional_custom_instructions": "<string>",
"bypass_entities_filter": true,
"supervised_run": {
"approver_ids": [
"<string>"
]
},
"target_entity_id": "<string>",
"target_entity_ids": [
"<string>"
],
"test_ticket": {
"description": "<string>",
"psa_company_id": "<string>",
"title": "<string>",
"psa_contact_id": "<string>"
}
}
'import requests
url = "https://api.neoagent.io/public-api/agents/{agent_id}/run-now"
payload = {
"additional_custom_instructions": "<string>",
"bypass_entities_filter": True,
"supervised_run": { "approver_ids": ["<string>"] },
"target_entity_id": "<string>",
"target_entity_ids": ["<string>"],
"test_ticket": {
"description": "<string>",
"psa_company_id": "<string>",
"title": "<string>",
"psa_contact_id": "<string>"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
additional_custom_instructions: '<string>',
bypass_entities_filter: true,
supervised_run: {approver_ids: ['<string>']},
target_entity_id: '<string>',
target_entity_ids: ['<string>'],
test_ticket: {
description: '<string>',
psa_company_id: '<string>',
title: '<string>',
psa_contact_id: '<string>'
}
})
};
fetch('https://api.neoagent.io/public-api/agents/{agent_id}/run-now', 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.neoagent.io/public-api/agents/{agent_id}/run-now",
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([
'additional_custom_instructions' => '<string>',
'bypass_entities_filter' => true,
'supervised_run' => [
'approver_ids' => [
'<string>'
]
],
'target_entity_id' => '<string>',
'target_entity_ids' => [
'<string>'
],
'test_ticket' => [
'description' => '<string>',
'psa_company_id' => '<string>',
'title' => '<string>',
'psa_contact_id' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.neoagent.io/public-api/agents/{agent_id}/run-now"
payload := strings.NewReader("{\n \"additional_custom_instructions\": \"<string>\",\n \"bypass_entities_filter\": true,\n \"supervised_run\": {\n \"approver_ids\": [\n \"<string>\"\n ]\n },\n \"target_entity_id\": \"<string>\",\n \"target_entity_ids\": [\n \"<string>\"\n ],\n \"test_ticket\": {\n \"description\": \"<string>\",\n \"psa_company_id\": \"<string>\",\n \"title\": \"<string>\",\n \"psa_contact_id\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.neoagent.io/public-api/agents/{agent_id}/run-now")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"additional_custom_instructions\": \"<string>\",\n \"bypass_entities_filter\": true,\n \"supervised_run\": {\n \"approver_ids\": [\n \"<string>\"\n ]\n },\n \"target_entity_id\": \"<string>\",\n \"target_entity_ids\": [\n \"<string>\"\n ],\n \"test_ticket\": {\n \"description\": \"<string>\",\n \"psa_company_id\": \"<string>\",\n \"title\": \"<string>\",\n \"psa_contact_id\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.neoagent.io/public-api/agents/{agent_id}/run-now")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"additional_custom_instructions\": \"<string>\",\n \"bypass_entities_filter\": true,\n \"supervised_run\": {\n \"approver_ids\": [\n \"<string>\"\n ]\n },\n \"target_entity_id\": \"<string>\",\n \"target_entity_ids\": [\n \"<string>\"\n ],\n \"test_ticket\": {\n \"description\": \"<string>\",\n \"psa_company_id\": \"<string>\",\n \"title\": \"<string>\",\n \"psa_contact_id\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": "<unknown>",
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"timings_ms": {},
"pagination": {
"has_more": true,
"next_cursor": "<string>"
},
"warnings": [
"<string>"
]
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
},
"meta": {
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
}Authorizations
Authorization: Bearer <token> where <token> is either a neo_sk_<env>_<secret> API key (service account) or a Microsoft Entra ID access token (dashboard user).
Path Parameters
Body
application/json
POST /public-api/agents/<id>/run-now body.
The supervised_run object of the run-now body.
Show child attributes
Show child attributes
Required array length:
1 - 100 elementsMinimum string length:
1The test_ticket object of the run-now body: a ticket written for this run, in no PSA.
Show child attributes
Show child attributes