Test Workflow Tool

Test a workflow tool

curl --request POST \
  --url https://api.getnexor.ai/api/public/workflows/{id}/tools/{toolId}/test \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "args": {
    "professional_id": 7,
    "date": "2026-10-02"
  },
  "lead_metadata": {
    "patient_id": "P-20431"
  }
}
'

import requests

url = "https://api.getnexor.ai/api/public/workflows/{id}/tools/{toolId}/test"

payload = {
    "args": {
        "professional_id": 7,
        "date": "2026-10-02"
    },
    "lead_metadata": { "patient_id": "P-20431" }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    args: {professional_id: 7, date: '2026-10-02'},
    lead_metadata: {patient_id: 'P-20431'}
  })
};

fetch('https://api.getnexor.ai/api/public/workflows/{id}/tools/{toolId}/test', 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.getnexor.ai/api/public/workflows/{id}/tools/{toolId}/test",
  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([
    'args' => [
        'professional_id' => 7,
        'date' => '2026-10-02'
    ],
    'lead_metadata' => [
        'patient_id' => 'P-20431'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$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.getnexor.ai/api/public/workflows/{id}/tools/{toolId}/test"

	payload := strings.NewReader("{\n  \"args\": {\n    \"professional_id\": 7,\n    \"date\": \"2026-10-02\"\n  },\n  \"lead_metadata\": {\n    \"patient_id\": \"P-20431\"\n  }\n}")

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

	req.Header.Add("X-API-Key", "<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.getnexor.ai/api/public/workflows/{id}/tools/{toolId}/test")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"args\": {\n    \"professional_id\": 7,\n    \"date\": \"2026-10-02\"\n  },\n  \"lead_metadata\": {\n    \"patient_id\": \"P-20431\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getnexor.ai/api/public/workflows/{id}/tools/{toolId}/test")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"args\": {\n    \"professional_id\": 7,\n    \"date\": \"2026-10-02\"\n  },\n  \"lead_metadata\": {\n    \"patient_id\": \"P-20431\"\n  }\n}"

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

{
  "success": true,
  "tool_id": "88888888-8888-4888-8888-888888888888",
  "name": "check_availability",
  "method": "GET",
  "passed": true,
  "called": true,
  "request": {
    "method": "GET",
    "url": "https://api.example.com/v1/professionals/7/availability?token=[Redacted]&date=2026-10-02",
    "args": {
      "date": "2026-10-02"
    }
  },
  "response": {
    "status": 200,
    "ok": true,
    "duration_ms": 412,
    "error": null,
    "body_excerpt": "{\"data\":[{\"slot_id\":9031,\"start\":\"2026-10-02T09:00:00-03:00\",\"end\":\"2026-10-02T09:30:00-03:00\",\"room\":\"B\"},{\"slot_id\":9034,\"start\":\"2026-10-02T11:30:00-03:00\",\"end\":\"2026-10-02T12:00:00-03:00\",\"room\":\"B\"}]}"
  },
  "agent_sees": "{\"data\":[{\"start\":\"2026-10-02T09:00:00-03:00\",\"end\":\"2026-10-02T09:30:00-03:00\"},{\"start\":\"2026-10-02T11:30:00-03:00\",\"end\":\"2026-10-02T12:00:00-03:00\"}]}",
  "checks": {
    "unresolved_placeholders": []
  }
}

{
  "error": "internal_tool_not_testable",
  "message": "Nexor platform tools are tested in Playground."
}

{
  "error": "Invalid API key",
  "message": "The provided API key is not valid"
}

{
  "error": "Forbidden",
  "message": "This API key is missing the required scope: workflows:write"
}

{
  "error": "Not found",
  "message": "Tool not found"
}

{
  "error": "write_requires_confirmation",
  "message": "PUT changes data in the external system. Repeat with confirm_write: true only after the operator agreed, using test data, and undo the effect afterwards."
}

{
  "error": "Internal server error",
  "message": "Unexpected error"
}

POST

workflows

{id}

tools

{toolId}

test

Test a workflow tool

curl --request POST \
  --url https://api.getnexor.ai/api/public/workflows/{id}/tools/{toolId}/test \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "args": {
    "professional_id": 7,
    "date": "2026-10-02"
  },
  "lead_metadata": {
    "patient_id": "P-20431"
  }
}
'

import requests

url = "https://api.getnexor.ai/api/public/workflows/{id}/tools/{toolId}/test"

payload = {
    "args": {
        "professional_id": 7,
        "date": "2026-10-02"
    },
    "lead_metadata": { "patient_id": "P-20431" }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    args: {professional_id: 7, date: '2026-10-02'},
    lead_metadata: {patient_id: 'P-20431'}
  })
};

fetch('https://api.getnexor.ai/api/public/workflows/{id}/tools/{toolId}/test', 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.getnexor.ai/api/public/workflows/{id}/tools/{toolId}/test",
  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([
    'args' => [
        'professional_id' => 7,
        'date' => '2026-10-02'
    ],
    'lead_metadata' => [
        'patient_id' => 'P-20431'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$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.getnexor.ai/api/public/workflows/{id}/tools/{toolId}/test"

	payload := strings.NewReader("{\n  \"args\": {\n    \"professional_id\": 7,\n    \"date\": \"2026-10-02\"\n  },\n  \"lead_metadata\": {\n    \"patient_id\": \"P-20431\"\n  }\n}")

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

	req.Header.Add("X-API-Key", "<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.getnexor.ai/api/public/workflows/{id}/tools/{toolId}/test")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"args\": {\n    \"professional_id\": 7,\n    \"date\": \"2026-10-02\"\n  },\n  \"lead_metadata\": {\n    \"patient_id\": \"P-20431\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getnexor.ai/api/public/workflows/{id}/tools/{toolId}/test")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"args\": {\n    \"professional_id\": 7,\n    \"date\": \"2026-10-02\"\n  },\n  \"lead_metadata\": {\n    \"patient_id\": \"P-20431\"\n  }\n}"

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

{
  "success": true,
  "tool_id": "88888888-8888-4888-8888-888888888888",
  "name": "check_availability",
  "method": "GET",
  "passed": true,
  "called": true,
  "request": {
    "method": "GET",
    "url": "https://api.example.com/v1/professionals/7/availability?token=[Redacted]&date=2026-10-02",
    "args": {
      "date": "2026-10-02"
    }
  },
  "response": {
    "status": 200,
    "ok": true,
    "duration_ms": 412,
    "error": null,
    "body_excerpt": "{\"data\":[{\"slot_id\":9031,\"start\":\"2026-10-02T09:00:00-03:00\",\"end\":\"2026-10-02T09:30:00-03:00\",\"room\":\"B\"},{\"slot_id\":9034,\"start\":\"2026-10-02T11:30:00-03:00\",\"end\":\"2026-10-02T12:00:00-03:00\",\"room\":\"B\"}]}"
  },
  "agent_sees": "{\"data\":[{\"start\":\"2026-10-02T09:00:00-03:00\",\"end\":\"2026-10-02T09:30:00-03:00\"},{\"start\":\"2026-10-02T11:30:00-03:00\",\"end\":\"2026-10-02T12:00:00-03:00\"}]}",
  "checks": {
    "unresolved_placeholders": []
  }
}

{
  "error": "internal_tool_not_testable",
  "message": "Nexor platform tools are tested in Playground."
}

{
  "error": "Invalid API key",
  "message": "The provided API key is not valid"
}

{
  "error": "Forbidden",
  "message": "This API key is missing the required scope: workflows:write"
}

{
  "error": "Not found",
  "message": "Tool not found"
}

{
  "error": "write_requires_confirmation",
  "message": "PUT changes data in the external system. Repeat with confirm_write: true only after the operator agreed, using test data, and undo the effect afterwards."
}

{
  "error": "Internal server error",
  "message": "Unexpected error"
}

This endpoint answers “does this tool work the way the agent will call it?”. It runs one of a task’s custom HTTP tools once, through the same path the agent uses in a real conversation, and returns what was sent, what came back, and what the agent would read. Use it right after you set up or change a tool, before you turn the task live.

What the test does

It builds the request exactly like the agent: {{env.KEY}} secrets, context placeholders, {argument} path parameters, the remaining arguments as query parameters (GET) or as the body (other methods), and the tool’s saved headers.
It works on inactive tools, so you can test a tool before you turn it on.
It calls your external system for real.
Unlike a conversation, it only reaches public hosts, does not follow redirects, and runs at most once. A URL that points to a loopback, private, link-local, or cloud metadata address is refused before anything is sent.
Nothing changes in Nexor: no lead, stage, field, or conversation is touched, and the run does not appear in Tool health.

Before you start

MCP keys need workflows:write, because the test reaches your system for real. Full-access REST keys need nothing else.
Get toolId from List workflow tools. Only the task’s custom tools can be tested.
Nexor platform tools return 400 internal_tool_not_testable. Test those in Playground.

Tools that change data

GET tools run directly. A tool whose method is POST, PUT, PATCH, or DELETE changes data in your system, so the test only runs with confirm_write: true. Without it the answer is 409 write_requires_confirmation and nothing is sent.

Send confirm_write: true only after the person who owns the external system agreed, use test data, and define the cleanup before the call. Cancel an appointment created by a booking test. For rescheduling and cancellation, use a disposable fixture or a restore operation supported by the provider.

What to send

Field	Detail
`args`	The arguments the agent would pass, checked against the tool’s `parameters`. Optional, default `{}`.
`lead_metadata`	Sample lead metadata, used to fill `{{lead.metadata.X}}` and `{X}` placeholders as a real lead’s metadata would. Optional, default `{}`.
`confirm_write`	`true` to run a tool that changes data. Ignored for GET tools.

A test has no real lead. Placeholders that read other lead data, such as {{lead.phone}}, stay unresolved and appear in checks.unresolved_placeholders. {{lead_id}} is sent empty.

Placeholders in the tool URL

Write	For	Example
`{name}` (single braces)	A tool argument. Nexor puts the argument’s value in the URL and does not send it again in the query or body. When the lead’s metadata has a key with the same name, that value is used instead.	`/appointments/{appointment_id}`
`{{...}}` (double braces)	A value Nexor fills before the call: an account secret `{{env.KEY}}`, lead data such as `{{lead.metadata.X}}`, or context such as `{{lead_id}}`.	`?token={{env.SCHEDULING_TOKEN}}`

A tool argument in double braces, such as /appointments/{{appointment_id}}, never gets a value: the literal text reaches your system. Saving a tool like that is rejected with 400 invalid_url_placeholder, which names the arguments in fields and proposes the corrected URL in suggested_url:

{
  "error": "invalid_url_placeholder",
  "message": "The URL uses {{appointment_id}} for a tool argument. Tool arguments use single braces: {appointment_id}. Double braces are only for context values such as {{env.KEY}}, {{lead.metadata.X}} and {{lead_id}}.",
  "fields": ["appointment_id"],
  "suggested_url": "https://api.example.com/v1/appointments/{appointment_id}"
}

Tools saved before this check existed are not changed. Test them: a leftover argument in double braces shows up in checks.unresolved_placeholders.

How to read the result

success only says the test could run. The verdict is passed, which is true when the request was sent, your system answered with a 2xx and a usable body, and the final URL has no unresolved placeholder.

What you see	What it usually means	What to do
`called: false`	No answer came back. Usually the request never left Nexor: `args` do not match the tool’s parameters, a `{{env.KEY}}` secret is missing, or the final URL points to a host that is not public. It also happens when the request timed out.	Read `agent_sees`: it names the invalid arguments, the missing keys, the refused address, or the timeout.
Items in `checks.unresolved_placeholders`	The final URL still has a `{{...}}` placeholder. Usually a tool argument written in double braces, or lead data that a test does not have.	Use single braces for arguments. Send the value in `lead_metadata` when it comes from the lead.
`response.status` 401 or 403	Your system rejected the credential.	Check the secret or header configured on the tool.
`response.status` 3xx	Your system answered with a redirect. The test does not follow redirects, so `passed` is `false`.	Point the tool at the final URL.
`response.status` 404	The path is wrong, or a path parameter was not filled.	Compare `request.url` with your API’s documentation.
`response.ok: true` but the wrong data	The endpoint answers, but it is not the one the agent needs. For example, a list of booked appointments instead of free slots.	Point the tool at the endpoint that answers the agent’s question.
`agent_sees` shorter than `body_excerpt`	Nexor cleans the response and, when the tool has `llm_response_fields`, keeps only those fields.	Check that the fields the agent needs are still there.

Limits

One attempt per request, up to the tool’s timeout. A test that times out is not retried, so a tool that changes data runs at most once.
body_excerpt and agent_sees are cut at 2,000 characters.
Values that come from {{env.KEY}} appear in request.url as [Redacted]. Headers are not returned. Values you send in args or lead_metadata are returned as sent.

Authorizations

X-API-Key

string

header

required

API key for authentication. Keys are prefixed with nxr_live_.

Path Parameters

string<uuid>

required

Task ID (workflow in the API) that owns the tool.

toolId

string<uuid>

required

Tool ID, as returned by List workflow tools.

Body

application/json

args

object

The arguments the AI agent would pass, checked against the tool's parameters. Arguments named in the URL as {argument} fill the path; the rest go as query parameters on GET or in the body on other methods. Default {}. Anything other than an object returns 400 Invalid input.

lead_metadata

object

Sample lead metadata used to fill {{lead.metadata.X}} and {X} placeholders, as a real lead's metadata would. Default {}. Anything other than an object returns 400 Invalid input.

confirm_write

boolean

default:false

Required as true for tools whose method is POST, PUT, PATCH, or DELETE, because the test really changes data in the external system. Send it only after the operator agreed, with test data, and undo the effect afterwards. The test runs at most once: a timeout is not retried. Ignored for GET tools.

Response

The test ran. success only means the test could run; read passed for the verdict. passed is true when the request was sent, the external system answered with a 2xx and a usable body, and the final URL has no unresolved {{...}} placeholder.

success

boolean

required

tool_id

string<uuid>

required

name

string

required

Tool name as the agent calls it.

method

enum<string>

required

Available options:

GET,

POST,

PUT,

PATCH,

DELETE

passed

boolean

required

true when called is true, response.ok is true, and checks.unresolved_placeholders is empty.

called

boolean

required

false when no answer came back. Usually the request never left Nexor, for example because args do not match the tool's parameters, a {{env.KEY}} secret is missing, or the final URL points to a host that is not public; it is also false when the single attempt timed out. agent_sees then explains why.

request

object | null

required

What Nexor sent. null when called is false. Headers are not returned.

Show child attributes

response

object | null

required

What the external system answered. null when called is false.

Show child attributes

agent_sees

string | null

required

What the AI model receives, as text, cut at 2,000 characters. It can differ from body_excerpt, because Nexor cleans the response and keeps only the fields in the tool's llm_response_fields when they are set.

checks

object

required

Show child attributes

Last modified on October 2, 2026

Start here

Quickstart

API reference

Build and launch

WhatsApp

Channels

Agents

Meetings

Integrations

Account

Inbox

Developer tools

Support reference

Test Workflow Tool

What the test does

Before you start

Tools that change data

What to send

Placeholders in the tool URL

How to read the result

Limits

Authorizations

Path Parameters

Body

Response

​What the test does

​Before you start

​Tools that change data

​What to send

​Placeholders in the tool URL

​How to read the result

​Limits

Authorizations

Path Parameters

Body

Response

What the test does

Before you start

Tools that change data

What to send

Placeholders in the tool URL

How to read the result

Limits