> ## Documentation Index > Fetch the complete documentation index at: https://docs.engini.io/llms.txt > Use this file to discover all available pages before exploring further. # Execute tool > Execute a tool. Connection is resolved implicitly from the caller's account-user, the tool's parent application, and optional toolsetId. Tool-runtime failures return 200 with isSuccess=false; all other failures use the standard error envelope. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/tools/{toolSlug}/execute openapi: 3.0.0 info: title: Engini DeveloperAPI version: v1 description: 'Merged public developer API spec: Identity + WorkflowApi.' servers: - url: https://api.engini.io security: - Bearer: [] - ApiKey: [] paths: /v1/tools/{toolSlug}/execute: post: tags: - Tools summary: Execute tool description: >- Execute a tool. Connection is resolved implicitly from the caller's account-user, the tool's parent application, and optional toolsetId. Tool-runtime failures return 200 with isSuccess=false; all other failures use the standard error envelope. operationId: Tools_ExecuteTool parameters: - name: toolSlug in: path required: true description: The slug identifying the tool to execute. schema: type: string x-position: 1 - name: toolsetId in: query description: Optional toolset identifier used to scope connection resolution. schema: type: string nullable: true x-position: 3 - name: connectionId in: query description: >- Optional explicit connection identifier to use instead of the implicitly resolved connection. schema: type: integer format: int32 nullable: true x-position: 4 requestBody: x-name: request description: The execution request containing the tool's input arguments. content: application/json: schema: $ref: '#/components/schemas/ToolExecuteRequest' required: true x-position: 2 responses: '200': description: The tool execution result, including success status and any output. content: application/json: schema: $ref: '#/components/schemas/ToolExecuteResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many requests — rate limit exceeded. headers: Retry-After: description: Number of seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error — an unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - Bearer: [] - ApiKey: [] components: schemas: ToolExecuteRequest: type: object description: >- Body shape for POST /api/DeveloperAPI/v1/tools/{toolSlug}/execute. activityName is intentionally absent — the activity is resolved from the path slug (+ optional ?applicationSlug=). Connection is resolved implicitly from the caller's account-user, the tool's parent application, and the optional ?toolsetId= query param. See applications-tools-spec.md §"POST /api/DeveloperAPI/v1/tools/{toolSlug}/execute". additionalProperties: false properties: fields: type: object description: Input field values for the tool, keyed by field name. nullable: true additionalProperties: {} contextValue: type: string description: Optional context value passed to the tool. nullable: true filters: type: array description: Filter conditions to apply to the tool's results. nullable: true items: $ref: '#/components/schemas/ActivityCondition' sort: type: array description: Sort clauses to apply to the tool's results. nullable: true items: $ref: '#/components/schemas/ActivitySort' offset: type: integer description: Number of leading results to skip (pagination offset). format: int32 nullable: true top: type: integer description: Maximum number of results to return. format: int32 nullable: true subItems: type: object description: Sub-item input values for the tool, keyed by name. nullable: true additionalProperties: {} customConnectionData: type: array description: >- Per-call overrides for the resolved connection's fields; only fields marked overridable are accepted. nullable: true items: $ref: '#/components/schemas/CustomConnectionDataItem' ToolExecuteResponse: type: object description: >- 200 response shape for POST /api/DeveloperAPI/v1/tools/{toolSlug}/execute. Tool-runtime failures (downstream API errors) return 200 + IsSuccess=false + ErrorMessage — not the standard error envelope. All non-200 responses use the standard ErrorResponse envelope, not this type. See applications-tools-spec.md §"Response 200". additionalProperties: false required: - isSuccess properties: isSuccess: type: boolean description: >- Whether the tool executed successfully. When false, see ErrorMessage. errorMessage: type: string description: >- Human-readable failure reason when IsSuccess is false; otherwise null. nullable: true executionInfo: description: >- Metadata about the execution (HTTP status, headers, timing, payload size). nullable: true oneOf: - $ref: '#/components/schemas/ExecutionInfo' output: description: >- The tool's result payload. Intentionally free-form (any JSON): its shape is defined by the individual tool's output schema, not by this envelope (api-spec-feedback.md C3). nullable: true historyId: type: integer description: >- Identifier of the workflow-history record for this execution, when one was created. format: int32 nullable: true ErrorResponse: type: object description: >- Unified error envelope for every non-200 response from /api/DeveloperAPI/v1/*. See applications-tools-spec.md §"Error envelope". additionalProperties: false required: - errorCode - message - requestId - timestamp - path properties: errorCode: type: string description: Machine-readable error code identifying the failure. message: type: string description: Human-readable error message. requestId: type: string description: Identifier of the request, for support/correlation. timestamp: type: string description: Timestamp when the error occurred (ISO 8601). path: type: string description: Request path that produced the error. details: type: array description: Per-field validation details, when applicable. nullable: true items: $ref: '#/components/schemas/ErrorDetail' ActivityCondition: type: object additionalProperties: false required: - fieldName - operator - value properties: fieldName: type: string operator: type: string value: type: string ActivitySort: type: object additionalProperties: false required: - fieldName - orderDirection properties: fieldName: type: string orderDirection: $ref: '#/components/schemas/OrderDirection' CustomConnectionDataItem: type: object description: A single per-call override of a connection field value. additionalProperties: false required: - fieldName - value properties: fieldName: type: string description: Name of the connection field to override. value: type: string description: Override value for the field. ExecutionInfo: type: object description: >- Metadata about a tool execution (downstream HTTP status, headers, timing, payload size). additionalProperties: false properties: statusCode: type: integer description: HTTP status code returned by the downstream call. format: int32 nullable: true headers: type: object description: Response headers from the downstream call, keyed by header name. nullable: true additionalProperties: type: string executionTime: type: number description: Execution time in milliseconds. format: double nullable: true dataSize: type: integer description: Size of the response payload in bytes. format: int64 nullable: true ErrorDetail: type: object description: A single field-level error detail within an ErrorResponse. additionalProperties: false required: - field - issue properties: field: type: string description: Name of the field the issue relates to. issue: type: string description: Description of the issue with the field. OrderDirection: type: integer description: '' x-enumNames: - Ascending - Descending enum: - 1 - -1 securitySchemes: Bearer: type: http description: Enter your JWT token scheme: bearer bearerFormat: JWT ApiKey: type: apiKey description: >- Opaque Developer API key (prefix `eng_`). Authenticates as the key's owner and resolves the account automatically — no Bearer or companytoken needed. name: x-api-key in: header ````