---
title: "Import Tool"
method: POST
path: "/workflows/v1/tools/import"
tags: ["Tools"]
---

# Import Tool

`POST /workflows/v1/tools/import`

Create a new tool from an exported bundle (see GET /tools/{tool_id}/export).

Re-injects redacted secrets from ``secret_overrides``, resolves non-portable
references, assigns a fresh identity to the importing team, and persists through
the same validation path as create_tool.

## Request body

- ToolBundleImportRequest
  - `bundle` ToolBundleExportResponse, required — Self-describing envelope for an exported custom tool. ``tool_config`` is a plain dict (not the ``ToolConfig`` model) so the ``<REDACTED>`` sentinels survive serialization instead of being coerced away by the discriminated union.
    - `export_format` string — Export format identifier
    - `source_tool_id` string, nullable — Original tool _id
    - `source_tool_name` string, nullable — Original tool name
    - `tool_type` string, nullable — ToolType of the exported tool (discriminator)
    - `tool_config` object, required — Sanitized ToolConfig as a dict (identity fields stripped, secrets redacted)
    - `redactions` ToolRedaction[] — Fields whose values were replaced with the '<REDACTED>' sentinel
      - `path` string, required — Dotted path to the redacted field, e.g. 'api_headers.Authorization'
      - `reason` string, required — Why it was redacted, e.g. 'sensitive header'
    - `required_dynamic_variables` string[] — Names of the dynamic/global variables this tool references. Values are team-scoped and are not carried in the bundle, so the importing team must define each name before the tool runs.
    - `exported_at` string, date-time — Timestamp of export
    - `warnings` string[] — Non-fatal notes (team-scoped refs cleared, env-specific endpoint, raw api_body, etc.)
  - `name_override` string, nullable — Override for the imported tool's name
  - `secret_overrides` object — Dotted-path -> value for each redacted field being re-supplied, e.g. {'api_headers.Authorization': 'Bearer ...'}
  - `clear_unresolved_refs` boolean — Clear team-scoped refs (KB ids) that cannot resolve in the importing team
  - `confirm_executable` boolean — Required True to import an inline_python tool (executable code)

## Response `200`

Successful Response

- ToolsResponse — Response model for a single tool. Contains a ToolsModel object.
  - `tool` ToolsModel, required — Stores a tool config present in the workflow system. It contains configuration fields for different types of tools (inbuilt_function, inline_python, external_api).
    - `team_id` string, nullable — ID of the team that owns this edge
    - `created_by` string, nullable — ID of the user who created this edge
    - `updated_by` string, nullable — ID of the user who last updated this edge
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `_id` string
    - `tool_config` union — Tool Configuration
      - InlinePythonToolConfig — Configuration for an inline Python tool. The "code" field should contain a self-contained executable Python function. Example value of "code" string could be: def add( a: float, b: float, ) -> float: return float(a + b)
        - `logical_id` string, nullable — Unique identifier for the tool
        - `tool_id` string, nullable — Reference to the tool already created in the Workflow System. If not provided, the tool config is assumed to be provided inline here.
        - `name` string, nullable — Name for the tool
        - `description` string, nullable — Human friendly description for the tool (not used by AI)
        - `category` string, nullable — Category for the tool. E.g math, ehr, etc
        - `side_effect` string, nullable — Side-effect classification used by the test-tool feature to decide whether the tool can be safely executed directly, or must be dry-run / confirmation-gated first. One of 'none', 'reads', 'writes', 'sends', 'unknown'. When not set, it is inferred from the tool type.
        - `signature` string, nullable — Docstring or signature for the tool used by AI. If provided and there is a default signature already, it will override the default signature.
        - `args_schema` object, nullable — Schema for the arguments that the tool accepts. This should be a JSON schema dictionary. Information provided here will override any default arguments schema.
        - `static_messages_config` StaticMessagesConfig
          - `static_messages` string[] — List of pre-configured messages from which one will be emitted
          - `static_messages_selection_mode` 'random' | 'sequence'
        - `result_runtime_variable_name` string, nullable — Name of the runtime variable to store the result from this tool call
        - `ignore_content_received_during_llm_tool_call_specification` boolean — If true, any free-text content the LLM returns in the same response as a call to this tool is ignored: not emitted via AssistantResponseEvent, not added to chat history, and not added to the node's structured output. When a response contains multiple tool calls, the text is ignored only if every tool call targets a tool for which this flag is set.
        - `timeout_seconds` integer, nullable — Wall-clock ceiling in seconds for one invocation of this tool. Leave empty to use the platform default. Raise it for a tool that is legitimately slow (a large EHR sync, say) rather than letting it be cut off. Note: an inline-Python body that is CPU-bound with no await points cannot be interrupted - the timeout frees the conversation to continue, but the work carries on in the background.
        - `variable_arguments` ToolVariableArgument[] — Arguments supplied to this tool from the workflow's runtime/dynamic variables, resolved at invocation time and passed as native Python values. Use this instead of embedding [[variables]] in an inline tool's source code: the value keeps its type, and it is passed as an argument rather than spliced into the code.
          - `argument_name` string, required — The keyword argument name passed to the tool function.
          - `source` 'auto' | 'runtime' | 'dynamic' | 'literal' — Which namespace a variable-bound tool argument is read from.
          - `variable_path` string, nullable — Path to the value, e.g. 'patient_record', 'patient_record.dob', 'items[0].id', or a node-qualified key such as 'Collect Insurance.dob'. Required unless source is 'literal'.
          - `literal_value` unknown
          - `default` unknown
          - `required` boolean — When true, a missing variable fails the tool call with a named error instead of passing the default. Use for arguments the tool genuinely cannot run without.
          - `expose_to_llm` boolean — When false (the default) this argument is stripped from the args_schema the model sees, so the model is never asked for it and cannot supply it. Set true only when the model should be able to override the bound value.
          - `override_provided_value` boolean — When true the bound value replaces anything the caller (the model, or the node's tool_arguments) supplied under the same name. When false the bound value acts as a fallback used only if the caller omitted the argument.
        - `result_variable_mappings` ToolResultVariableMapping[] — Assigns parts of this tool's return value to named runtime variables, so a tool that returns a dict can populate several variables at once.
          - `target_variable_name` string, required — Runtime variable to write. Readable downstream as [[<name>]]. Must be a plain name: letters, digits and underscores, not starting with a digit or an underscore.
          - `result_path` string, nullable — Path into the returned value, e.g. 'score', 'patient.dob' or 'rows[0].id'. Leave empty to assign the whole return value.
          - `scope` 'thread' | 'workflow' — Which variable store a mapped tool result is written to.
          - `default` unknown
          - `required` boolean — When true, a missing result_path marks the tool call as failed and records the reason in <result_runtime_variable_name>_error, instead of writing the default.
        - `expand_result_into_runtime_variables` boolean — When true and the tool returns a dict, every top-level key is also written as a runtime variable of the same name. A convenience alternative to listing every mapping explicitly; explicit result_variable_mappings win on a name collision.
        - `type` 'inline_python' — Type of the tool. Must be 'inline_python'
        - `code` string, nullable — Python code to be executed by the tool. It should define a function with proper signature and descriptions for its parameters.
        - `allow_code_variable_substitution` boolean — Whether {{dynamic}} and [[runtime]] placeholders inside 'code' are replaced with their values before the code is compiled. Turning this off leaves the source exactly as written, so any placeholder in it stays literal text. Prefer variable_arguments, which passes a value in as a typed argument instead of pasting it into the source.
      - InbuiltFunctionToolConfig — Configuration for an inbuilt function tool. This tool type refers to functions that are already registered in the tools registry. The "tool_id" field must match the ID (decorated with "@tool_id") of a registered tool.
        - `logical_id` string, nullable — Unique identifier for the tool
        - `tool_id` string, nullable — Reference to the tool already created in the Workflow System. If not provided, the tool config is assumed to be provided inline here.
        - `name` string, nullable — Name for the tool
        - `description` string, nullable — Human friendly description for the tool (not used by AI)
        - `category` string, nullable — Category for the tool. E.g math, ehr, etc
        - `side_effect` string, nullable — Side-effect classification used by the test-tool feature to decide whether the tool can be safely executed directly, or must be dry-run / confirmation-gated first. One of 'none', 'reads', 'writes', 'sends', 'unknown'. When not set, it is inferred from the tool type.
        - `signature` string, nullable — Docstring or signature for the tool used by AI. If provided and there is a default signature already, it will override the default signature.
        - `args_schema` object, nullable — Schema for the arguments that the tool accepts. This should be a JSON schema dictionary. Information provided here will override any default arguments schema.
        - `static_messages_config` StaticMessagesConfig
          - `static_messages` string[] — List of pre-configured messages from which one will be emitted
          - `static_messages_selection_mode` 'random' | 'sequence'
        - `result_runtime_variable_name` string, nullable — Name of the runtime variable to store the result from this tool call
        - `ignore_content_received_during_llm_tool_call_specification` boolean — If true, any free-text content the LLM returns in the same response as a call to this tool is ignored: not emitted via AssistantResponseEvent, not added to chat history, and not added to the node's structured output. When a response contains multiple tool calls, the text is ignored only if every tool call targets a tool for which this flag is set.
        - `timeout_seconds` integer, nullable — Wall-clock ceiling in seconds for one invocation of this tool. Leave empty to use the platform default. Raise it for a tool that is legitimately slow (a large EHR sync, say) rather than letting it be cut off. Note: an inline-Python body that is CPU-bound with no await points cannot be interrupted - the timeout frees the conversation to continue, but the work carries on in the background.
        - `variable_arguments` ToolVariableArgument[] — Arguments supplied to this tool from the workflow's runtime/dynamic variables, resolved at invocation time and passed as native Python values. Use this instead of embedding [[variables]] in an inline tool's source code: the value keeps its type, and it is passed as an argument rather than spliced into the code.
          - `argument_name` string, required — The keyword argument name passed to the tool function.
          - `source` 'auto' | 'runtime' | 'dynamic' | 'literal' — Which namespace a variable-bound tool argument is read from.
          - `variable_path` string, nullable — Path to the value, e.g. 'patient_record', 'patient_record.dob', 'items[0].id', or a node-qualified key such as 'Collect Insurance.dob'. Required unless source is 'literal'.
          - `literal_value` unknown
          - `default` unknown
          - `required` boolean — When true, a missing variable fails the tool call with a named error instead of passing the default. Use for arguments the tool genuinely cannot run without.
          - `expose_to_llm` boolean — When false (the default) this argument is stripped from the args_schema the model sees, so the model is never asked for it and cannot supply it. Set true only when the model should be able to override the bound value.
          - `override_provided_value` boolean — When true the bound value replaces anything the caller (the model, or the node's tool_arguments) supplied under the same name. When false the bound value acts as a fallback used only if the caller omitted the argument.
        - `result_variable_mappings` ToolResultVariableMapping[] — Assigns parts of this tool's return value to named runtime variables, so a tool that returns a dict can populate several variables at once.
          - `target_variable_name` string, required — Runtime variable to write. Readable downstream as [[<name>]]. Must be a plain name: letters, digits and underscores, not starting with a digit or an underscore.
          - `result_path` string, nullable — Path into the returned value, e.g. 'score', 'patient.dob' or 'rows[0].id'. Leave empty to assign the whole return value.
          - `scope` 'thread' | 'workflow' — Which variable store a mapped tool result is written to.
          - `default` unknown
          - `required` boolean — When true, a missing result_path marks the tool call as failed and records the reason in <result_runtime_variable_name>_error, instead of writing the default.
        - `expand_result_into_runtime_variables` boolean — When true and the tool returns a dict, every top-level key is also written as a runtime variable of the same name. A convenience alternative to listing every mapping explicitly; explicit result_variable_mappings win on a name collision.
        - `type` 'inbuilt_function' — Type of the tool. Must be 'inbuilt_function'
        - `configurable_key` string, nullable — Stable key identifying which configurable inbuilt tool this is (e.g. 'call_forward'). None for plain static inbuilt references.
        - `extra_config` object, nullable — Tool-specific user configuration values. Schema is defined per configurable key.
      - ExternalAPIToolConfig — Configuration for an external API tool. This tool type represents an external API endpoint that the LLM can call.
        - `logical_id` string, nullable — Unique identifier for the tool
        - `tool_id` string, nullable — Reference to the tool already created in the Workflow System. If not provided, the tool config is assumed to be provided inline here.
        - `name` string, nullable — Name for the tool
        - `description` string, nullable — Human friendly description for the tool (not used by AI)
        - `category` string, nullable — Category for the tool. E.g math, ehr, etc
        - `side_effect` string, nullable — Side-effect classification used by the test-tool feature to decide whether the tool can be safely executed directly, or must be dry-run / confirmation-gated first. One of 'none', 'reads', 'writes', 'sends', 'unknown'. When not set, it is inferred from the tool type.
        - `signature` string, nullable — Docstring or signature for the tool used by AI. If provided and there is a default signature already, it will override the default signature.
        - `args_schema` object, nullable — Schema for the arguments that the tool accepts. This should be a JSON schema dictionary. Information provided here will override any default arguments schema.
        - `static_messages_config` StaticMessagesConfig
          - `static_messages` string[] — List of pre-configured messages from which one will be emitted
          - `static_messages_selection_mode` 'random' | 'sequence'
        - `result_runtime_variable_name` string, nullable — Name of the runtime variable to store the result from this tool call
        - `ignore_content_received_during_llm_tool_call_specification` boolean — If true, any free-text content the LLM returns in the same response as a call to this tool is ignored: not emitted via AssistantResponseEvent, not added to chat history, and not added to the node's structured output. When a response contains multiple tool calls, the text is ignored only if every tool call targets a tool for which this flag is set.
        - `timeout_seconds` integer, nullable — Wall-clock ceiling in seconds for one invocation of this tool. Leave empty to use the platform default. Raise it for a tool that is legitimately slow (a large EHR sync, say) rather than letting it be cut off. Note: an inline-Python body that is CPU-bound with no await points cannot be interrupted - the timeout frees the conversation to continue, but the work carries on in the background.
        - `variable_arguments` ToolVariableArgument[] — Arguments supplied to this tool from the workflow's runtime/dynamic variables, resolved at invocation time and passed as native Python values. Use this instead of embedding [[variables]] in an inline tool's source code: the value keeps its type, and it is passed as an argument rather than spliced into the code.
          - `argument_name` string, required — The keyword argument name passed to the tool function.
          - `source` 'auto' | 'runtime' | 'dynamic' | 'literal' — Which namespace a variable-bound tool argument is read from.
          - `variable_path` string, nullable — Path to the value, e.g. 'patient_record', 'patient_record.dob', 'items[0].id', or a node-qualified key such as 'Collect Insurance.dob'. Required unless source is 'literal'.
          - `literal_value` unknown
          - `default` unknown
          - `required` boolean — When true, a missing variable fails the tool call with a named error instead of passing the default. Use for arguments the tool genuinely cannot run without.
          - `expose_to_llm` boolean — When false (the default) this argument is stripped from the args_schema the model sees, so the model is never asked for it and cannot supply it. Set true only when the model should be able to override the bound value.
          - `override_provided_value` boolean — When true the bound value replaces anything the caller (the model, or the node's tool_arguments) supplied under the same name. When false the bound value acts as a fallback used only if the caller omitted the argument.
        - `result_variable_mappings` ToolResultVariableMapping[] — Assigns parts of this tool's return value to named runtime variables, so a tool that returns a dict can populate several variables at once.
          - `target_variable_name` string, required — Runtime variable to write. Readable downstream as [[<name>]]. Must be a plain name: letters, digits and underscores, not starting with a digit or an underscore.
          - `result_path` string, nullable — Path into the returned value, e.g. 'score', 'patient.dob' or 'rows[0].id'. Leave empty to assign the whole return value.
          - `scope` 'thread' | 'workflow' — Which variable store a mapped tool result is written to.
          - `default` unknown
          - `required` boolean — When true, a missing result_path marks the tool call as failed and records the reason in <result_runtime_variable_name>_error, instead of writing the default.
        - `expand_result_into_runtime_variables` boolean — When true and the tool returns a dict, every top-level key is also written as a runtime variable of the same name. A convenience alternative to listing every mapping explicitly; explicit result_variable_mappings win on a name collision.
        - `type` 'external_api' — Type of the tool. Must be 'external_api'
        - `api_endpoint` string, nullable — The endpoint URL of the external API
        - `api_method` 'GET' | 'POST' | 'PUT' | 'DELETE' — Enumeration of HTTP methods for API calls.
        - `api_headers` object — HTTP headers to include with the API request (e.g., authorization, content-type)
        - `api_body` union — The request body payload for the API call. Usually applicable for POST/PUT methods.
          - object
          - string
        - `integration_auth` IntegrationAuthConfig — Configuration for integration-backed bearer-token authentication. Provider-agnostic: any integration that exposes an OAuth2 client-credentials token endpoint (Okta, Athena, ECW, ...) can be referenced here. The runtime only needs the integration ID – the integrations service resolves the provider and returns the bearer token.
          - `integration_id` string, nullable — ID of an integration to use for bearer-token authentication. When set, the runtime fetches a cached OAuth token from this integration and injects it as the Authorization header. Ignored when api_key or an Authorization default_header is already provided.
      - KnowledgeBaseToolConfig — Configuration for a knowledge base tool. This tool type represents a knowledge base endpoint that the LLM can call.
        - `logical_id` string, nullable — Unique identifier for the tool
        - `tool_id` string, nullable — Reference to the tool already created in the Workflow System. If not provided, the tool config is assumed to be provided inline here.
        - `name` string, nullable — Name for the tool
        - `description` string, nullable — Human friendly description for the tool (not used by AI)
        - `category` string, nullable — Category for the tool. E.g math, ehr, etc
        - `side_effect` string, nullable — Side-effect classification used by the test-tool feature to decide whether the tool can be safely executed directly, or must be dry-run / confirmation-gated first. One of 'none', 'reads', 'writes', 'sends', 'unknown'. When not set, it is inferred from the tool type.
        - `signature` string, nullable — Docstring or signature for the tool used by AI. If provided and there is a default signature already, it will override the default signature.
        - `args_schema` object, nullable — Schema for the arguments that the tool accepts. This should be a JSON schema dictionary. Information provided here will override any default arguments schema.
        - `static_messages_config` StaticMessagesConfig
          - `static_messages` string[] — List of pre-configured messages from which one will be emitted
          - `static_messages_selection_mode` 'random' | 'sequence'
        - `result_runtime_variable_name` string, nullable — Name of the runtime variable to store the result from this tool call
        - `ignore_content_received_during_llm_tool_call_specification` boolean — If true, any free-text content the LLM returns in the same response as a call to this tool is ignored: not emitted via AssistantResponseEvent, not added to chat history, and not added to the node's structured output. When a response contains multiple tool calls, the text is ignored only if every tool call targets a tool for which this flag is set.
        - `timeout_seconds` integer, nullable — Wall-clock ceiling in seconds for one invocation of this tool. Leave empty to use the platform default. Raise it for a tool that is legitimately slow (a large EHR sync, say) rather than letting it be cut off. Note: an inline-Python body that is CPU-bound with no await points cannot be interrupted - the timeout frees the conversation to continue, but the work carries on in the background.
        - `variable_arguments` ToolVariableArgument[] — Arguments supplied to this tool from the workflow's runtime/dynamic variables, resolved at invocation time and passed as native Python values. Use this instead of embedding [[variables]] in an inline tool's source code: the value keeps its type, and it is passed as an argument rather than spliced into the code.
          - `argument_name` string, required — The keyword argument name passed to the tool function.
          - `source` 'auto' | 'runtime' | 'dynamic' | 'literal' — Which namespace a variable-bound tool argument is read from.
          - `variable_path` string, nullable — Path to the value, e.g. 'patient_record', 'patient_record.dob', 'items[0].id', or a node-qualified key such as 'Collect Insurance.dob'. Required unless source is 'literal'.
          - `literal_value` unknown
          - `default` unknown
          - `required` boolean — When true, a missing variable fails the tool call with a named error instead of passing the default. Use for arguments the tool genuinely cannot run without.
          - `expose_to_llm` boolean — When false (the default) this argument is stripped from the args_schema the model sees, so the model is never asked for it and cannot supply it. Set true only when the model should be able to override the bound value.
          - `override_provided_value` boolean — When true the bound value replaces anything the caller (the model, or the node's tool_arguments) supplied under the same name. When false the bound value acts as a fallback used only if the caller omitted the argument.
        - `result_variable_mappings` ToolResultVariableMapping[] — Assigns parts of this tool's return value to named runtime variables, so a tool that returns a dict can populate several variables at once.
          - `target_variable_name` string, required — Runtime variable to write. Readable downstream as [[<name>]]. Must be a plain name: letters, digits and underscores, not starting with a digit or an underscore.
          - `result_path` string, nullable — Path into the returned value, e.g. 'score', 'patient.dob' or 'rows[0].id'. Leave empty to assign the whole return value.
          - `scope` 'thread' | 'workflow' — Which variable store a mapped tool result is written to.
          - `default` unknown
          - `required` boolean — When true, a missing result_path marks the tool call as failed and records the reason in <result_runtime_variable_name>_error, instead of writing the default.
        - `expand_result_into_runtime_variables` boolean — When true and the tool returns a dict, every top-level key is also written as a runtime variable of the same name. A convenience alternative to listing every mapping explicitly; explicit result_variable_mappings win on a name collision.
        - `type` 'knowledge_base' — Type of the tool. Must be 'knowledge_base'
        - `target_knowledge_base_ids` string[] — The IDs of the knowledge bases to query
  - `warnings` string[] — Advisory notes: the write succeeded, but the config will not work yet — e.g. an imported tool whose dynamic variables this team has not defined.

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-24** `777675c8a285` — 3 info
  - added the new optional request property `bundle/required_dynamic_variables`
  - added the optional property `tool/tool_config/anyOf[subschema #1]/oneOf[subschema #1: Inline Python Tool]/allow_code_variable_substitution` to the response with the `200` status
  - added the optional property `warnings` to the response with the `200` status
- **2026-08-19** `68e88496bf11` — 17 info
  - added the optional property `tool/tool_config/anyOf[subschema #1]/oneOf[subschema #1: Inline Python Tool]/expand_result_into_runtime_variables` to the response with the `200` status
  - added the optional property `tool/tool_config/anyOf[subschema #1]/oneOf[subschema #1: Inline Python Tool]/result_variable_mappings` to the response with the `200` status
  - added the optional property `tool/tool_config/anyOf[subschema #1]/oneOf[subschema #1: Inline Python Tool]/timeout_seconds` to the response with the `200` status
  - added the optional property `tool/tool_config/anyOf[subschema #1]/oneOf[subschema #1: Inline Python Tool]/variable_arguments` to the response with the `200` status
  - …13 more
- **2026-07-21** `d276be705570` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/interactly/apis/interactly-api-3/changes/workflows/v1/tools/import/post.md)

---

[API](https://skmtc.dev/interactly/apis/interactly-api-3.md) · [All operations](https://skmtc.dev/interactly/apis/interactly-api-3/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/interactly/interactly-api-3/revisions/35cbea12a781/schema)