Test Execute Tool

POST /api/public/v2/tool-registry/{identifier}/test-execute

Test Execute Tool

cURL

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": {}
}
'

200

{
  "success": true,
  "message": "<string>",
  "result": {
    "result": "<unknown>",
    "stdout": "<string>",
    "stderr": "<string>",
    "duration_ms": 123,
    "error": {}
  }
}

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.

Show child attributes

tool_definition · object

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

Response

200

application/json

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

Show child attributes