> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # InvokeTool # Package: appTools # Namespace: ToolsHost # Method link: https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-host/invoke-tool.md ## Permission Scopes: Invoke App Tools: SCOPE.APP_TOOLS.INVOKE ## Introduction Runs a tool of an app installed on the site in context and returns the app's response. Wix passes `payload` to the app's Tools Provider service plugin as is, without checking it against the tool's `requestSchema`, and returns whatever the app returns in `response`. Build the payload from the schema returned by List Tools Providers. The call fails when the app isn't installed on the site, when the app doesn't declare an activated tool with this `methodName`, or when the site owner disabled the app's tools or this tool. --- ## REST API ### Schema ``` Method: invokeTool Description: Runs a tool of an app installed on the site in context and returns the app's response. Wix passes `payload` to the app's Tools Provider service plugin as is, without checking it against the tool's `requestSchema`, and returns whatever the app returns in `response`. Build the payload from the schema returned by List Tools Providers. The call fails when the app isn't installed on the site, when the app doesn't declare an activated tool with this `methodName`, or when the site owner disabled the app's tools or this tool. URL: https://www.wixapis.com/_api/tools-host/v1/invoke-tool Method: POST Method parameters: param name: methodName | type: methodName | description: Method name of the tool to run, as returned in `methodName` by List Tools Providers. | validation: minLength 1, maxLength 50 param name: payload | type: payload | description: Request payload for the tool, following the tool's `requestSchema`. Wix passes it to the app without validating it. param name: providerAppId | type: providerAppId | description: GUID of the app that provides the tool, as returned in `appId` by List Tools Providers. | validation: format GUID Return type: InvokeToolResponse - name: response | type: object | description: Response returned by the app, passed through as is. Wix doesn't validate it against the tool's `responseSchema`; treat that schema as the app's own declaration, not a guarantee. Possible Errors: HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: PROVIDER_NOT_FOUND | Description: Couldn't find the tools provider. The app isn't installed on the site or has no Tools Provider extension. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: TOOL_DISABLED | Description: The site owner disabled this tool for the site. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: PROVIDER_DISABLED | Description: The site owner disabled this app's tools for the site. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: TOOL_METHOD_NOT_FOUND | Description: The app doesn't declare an activated tool with this `methodName`. ``` ### Examples ### Run an app's tool Runs the getPackageTracking tool of an installed app with a payload built from the tool's request schema. The site is set by the wix-site-id header when calling with an API key. ```curl curl -X POST \ 'https://www.wixapis.com/_api/tools-host/v1/invoke-tool' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -H 'wix-site-id: ' \ -d '{ "providerAppId": "6c4d3373-2afc-46a6-b7e0-9b98a43df146", "methodName": "getPackageTracking", "payload": { "trackingNumber": "1Z999AA10123456784" } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.appTools.toolsHost.invokeTool(options) Description: Runs a tool of an app installed on the site in context and returns the app's response. Wix passes `payload` to the app's Tools Provider service plugin as is, without checking it against the tool's `requestSchema`, and returns whatever the app returns in `response`. Build the payload from the schema returned by List Tools Providers. The call fails when the app isn't installed on the site, when the app doesn't declare an activated tool with this `methodName`, or when the site owner disabled the app's tools or this tool. Method parameters: param name: options | type: InvokeToolOptions none - name: providerAppId | type: string | description: GUID of the app that provides the tool, as returned in `appId` by List Tools Providers. | validation: format GUID - name: methodName | type: string | description: Method name of the tool to run, as returned in `methodName` by List Tools Providers. | validation: minLength 1, maxLength 50 - name: payload | type: object | description: Request payload for the tool, following the tool's `requestSchema`. Wix passes it to the app without validating it. Return type: PROMISE - name: response | type: object | description: Response returned by the app, passed through as is. Wix doesn't validate it against the tool's `responseSchema`; treat that schema as the app's own declaration, not a guarantee. Possible Errors: HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: PROVIDER_NOT_FOUND | Description: Couldn't find the tools provider. The app isn't installed on the site or has no Tools Provider extension. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: TOOL_DISABLED | Description: The site owner disabled this tool for the site. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: PROVIDER_DISABLED | Description: The site owner disabled this app's tools for the site. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: TOOL_METHOD_NOT_FOUND | Description: The app doesn't declare an activated tool with this `methodName`. ``` ### Examples ### Run an app's tool Runs the getPackageTracking tool of an installed app with a payload built from the tool's request schema, and returns the app's response as is. ```javascript import { toolsHost } from "@wix/app-tools"; async function invokeTool() { const response = await toolsHost.invokeTool({ providerAppId: "6c4d3373-2afc-46a6-b7e0-9b98a43df146", methodName: "getPackageTracking", payload: { trackingNumber: "1Z999AA10123456784", }, }); } /* Promise resolves to: * { * "response": { * "trackingNumber": "1Z999AA10123456784", * "status": "In Transit", * "location": "Distribution Center, New York", * "estimatedDelivery": "2026-10-30" * } * } */ ``` ### invokeTool (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { toolsHost } from '@wix/app-tools'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { toolsHost }, // Include the auth strategy and host as relevant }); async function invokeTool(options) { const response = await myWixClient.toolsHost.invokeTool(options); }; ``` ---