Custom Tool OpenAPI Integration#

Dify's custom tool system (ApiTool) lets users register arbitrary HTTP APIs by supplying an OpenAPI 3.x, Swagger 2.x, or OpenAI plugin JSON schema. At registration time the schema is parsed into one or more ApiToolBundle objects — one per operation — each carrying a frozen server_url, HTTP method, parameter list, and the raw OpenAPI operation dict. These bundles are persisted to the database and drive every subsequent tool invocation.

Parsing Pipeline#

Entry point: ApiBasedToolSchemaParser.auto_parse_to_tool_bundle() in api/core/tools/utils/parser.py.

The function auto-detects format and attempts three parse strategies in order 1:

1. OpenAPI 3.x — direct parse via parse_openapi_to_tool_bundle()
2. Swagger 2.x — upgraded to OpenAPI 3.0 by parse_swagger_to_openapi(), then re-parsed
3. OpenAI plugin JSON — fetches the referenced OpenAPI YAML over HTTP and re-parses

The service layer entry is ApiToolManageService.parser_api_schema(), which calls auto_parse_to_tool_bundle() and wraps the result with a credentials schema (auth type, api key header, api key value).

Server URL Extraction#

Inside parse_openapi_to_tool_bundle(), server URL selection follows this logic 2:

1. Default to servers[0]["url"].
2. If a Flask request context is active and the X-Request-Env header is set, scan servers for the first entry whose "env" field matches and use that URL instead.
3. Fall back to servers[0]["url"] when no matching "env" entry is found.

The "env" field is a non-standard Dify extension — standard OpenAPI specs don't define it. Accessing it safely requires server.get("env") rather than server["env"]; the bracket-access form caused a KeyError on standard schemas whenever X-Request-Env was present, fixed in PR #42025.

For each path + method combination, the resolved server_url is concatenated with the path string and stored as ApiToolBundle.server_url — a plain str field baked in at parse time 3 4.

Invocation Flow#

At runtime, ApiTool._invoke() passes self.api_bundle.server_url directly to do_http_request(). Inside that method:

• Path parameters (in: path) are interpolated via string replacement: url.replace(f"{{{name}}}", f"{value}") 5. The host portion of the URL is never touched.
• Query / header / cookie parameters are merged into the request.
• Auth is assembled by assembling_request(): supports none, api_key_header (with Basic/Bearer/custom prefixes), and api_key_query modes.
• All requests are dispatched via ssrf_proxy to prevent SSRF 6.

Limitations on Dynamic Parameterization#

Multi-Environment Server Extension#

To route the same tool bundle to different backends (e.g. staging vs. production), add multiple servers entries with a custom "env" key:

servers:
  - url: https://api.example.com
  - url: https://staging.example.com
    env: staging

Send X-Request-Env: staging on the parse request to select the staging URL. If no server matches, the parser falls back to servers[0] 9 10.

Key Files#