INinteractly
Tools

Execute Tool Inline

Changed on

Execute a fully inline tool config (not yet persisted) against the supplied argument values and return its output.

Runtime failures (bad args, thrown exceptions, timeouts) are returned as HTTP 200 with success=False and a clean error message rather than a 500, so callers can render them inline.

Note: inline-Python tools run their code via exec server-side and are not sandboxed. This endpoint is intended for authoring/debugging within a team's own workspace.

post/workflows/v1/tools/execute

Request

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

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

  • 4a885f58a270Revision changes
    • breaking

      removed from the request property oneOf list

    • info

      mapped value for discriminator key external_api changed from to for request property

    • info

      added to the request property oneOf list

  • 313ea3ccd136Revision changes
    • info

      added the new optional request property //