INinteractly
Tools

Execute Tool

Changed on

Execute a saved custom tool against the supplied argument values and return its output.

Runtime failures are returned as HTTP 200 with success=False and a clean error message (see :func:execute_tool_inline).

post/workflows/v1/tools/{tool_id}/execute

Request

  • Base URL
    https://api-qa.interactly.ai
  • URL
    https://api-qa.interactly.ai/workflows/v1/tools/{tool_id}/execute
  • Auth
    HTTP bearer

Path parameters

tool_idstring required
Example:5eb7cf5a86d9755df3a6c593

Request body

argsobject

Argument values to invoke the tool with, keyed by the tool's parameter names.

dry_runboolean

When True, side-effecting tools (writes/sends/unknown) are validated but NOT executed - no external effect occurs and a simulated result is returned. Pure/read-only tools run normally.

dynamic_variablesobject

Test values for {{dynamic}} placeholders in the tool config (endpoint/headers/body/code). Resolved before execution to mirror the live workflow runtime. The team's global variables are applied automatically, exactly as the live runtime does; values supplied here override them.

runtime_variablesobject

Test values for [[runtime]] placeholders in the tool config (endpoint/headers/body/code). Resolved before execution to mirror the live workflow runtime.

Response

Successful Response

successboolean required
resultunknown
errorstring nullable

Full human-readable error description when success is False. Always set on failure.

latency_msinteger nullable

Wall-clock execution time in milliseconds.

dry_runboolean

Whether this run was a validate-only dry run.

side_effectstring nullable

The tool's side-effect classification (none/reads/writes/sends/unknown).

error_typestring nullable

Error category: validation | timeout | runtime | connection | http_status | not_found.

error_codestring nullable

Machine-readable error code: HTTP status (e.g. '404') for external API tools, or the exception class name (e.g. 'ValueError') otherwise.

field_errorsobject nullable

Per-argument validation messages keyed by the offending field name.

truncatedboolean

Whether the result was truncated because it was too large.

effective_result_runtime_variable_namestring nullable

The runtime variable this tool's result belongs in, read from the config that actually ran. For a tool attached by tool_id that is the saved tool's name, which the attachment does not carry — so a caller that stores the result must use this rather than reading the config it passed in. None only when the config could not be resolved at all, since naming a variable for a config that never resolved would be a guess.

result_variable_updatesobject nullable

Runtime variables the tool's own config asks for its result to be mapped onto — result_variable_mappings plus expand_result_into_runtime_variables. None when the config declares neither (the common case); an empty map means it declared some and none could be produced. Like the name above, these are reachable only after the by-reference merge.

result_workflow_variable_updatesobject nullable

The same, for mappings the tool declares with scope='workflow'. Kept separate rather than merged because they belong in a different store — the run's shared memory rather than this thread's — and a caller that wrote them to the thread instead would give each one a thread-local shadow that then wins over it everywhere. A caller with no workflow run (the Test-Tool routes) has nowhere to put these and may ignore them.

result_mapping_errorsstring[] nullable

Required result mappings that could not be satisfied. The tool still SUCCEEDED — a mapping failure is a statement about the workflow's expectation of the result, not about the call — so this is populated alongside success=True and a full result.

Changes

  • 777675c8a285Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • 47b3d1acaddaRevision changes
    • info

      added the optional property to the response with the status