Skip to main content
POST
/
api
/
public
/
v2
/
tool-registry
/
{identifier}
/
test-execute
Test Execute Tool
curl --request POST \
  --url https://api.promptlayer.com/api/public/v2/tool-registry/{identifier}/test-execute \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "inputs": {},
  "execution": {
    "code": "<string>"
  },
  "tool_definition": {}
}
'
{
  "success": true,
  "message": "<string>",
  "result": {
    "result": "<unknown>",
    "stdout": "<string>",
    "stderr": "<string>",
    "duration_ms": 123,
    "error": {}
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.promptlayer.com/llms.txt

Use this file to discover all available pages before exploring further.

Run a tool’s execution body in the sandbox against test inputs. This is what the editor’s Test Run button calls behind the scenes; useful for verifying a body works as expected before promoting the version.

​
Resolving the version

Without label or version query params, the latest version is used. Pass label=production to test the production version, or version=3 to pin to a specific number.

​
In-flight overrides

Both execution and tool_definition in the body are optional overrides. If you supply them, they take precedence over what’s stored on the version. This lets you test changes without saving a new version first.

​
Result shape

The endpoint returns 200 for both successful runs and user-code errors. Inspect result.status:
  • "success" → your body returned a value, available at result.result
  • "error" → your body raised, with details under result.error.message
Sandbox infrastructure failures (sandbox unreachable, internal errors) return 502. These are operational issues, not your code’s fault.

Authorizations

​
X-API-KEY
string
header
required

Headers

​
X-API-KEY
string
required

Path Parameters

​
identifier
string
required

Tool ID (numeric) or name

Query Parameters

​
label
string

Resolve version by label name (e.g. production). Falls back to latest if neither label nor version supplied.

​
version
string

Resolve by specific version number

Body

application/json
​
inputs
object

Arguments passed to the tool body. Same shape the LLM would emit — keys match the tool's parameter names.

​
execution
object

In-flight override of the stored execution config. Lets you test unsaved code.

​
tool_definition
object

In-flight override of the stored tool definition. Used to test against a different function name without saving.

Response

Tool executed (success or user-code error). User-code errors return status="error" inside the result object — they do NOT raise.

​
success
boolean
​
message
string
​
result
object