from engini import Engini
client = Engini() # reads ENGINI_API_KEY
result = client.tools.execute(
"salesforce_getrecords", {"sobject": "Account"}, connection_id=42
)
print(result.output, result.history_id)import { Engini } from "@engini/sdk";
const client = new Engini(); // reads ENGINI_API_KEY
const result = await client.tools.execute(
"salesforce_getrecords",
{ sobject: "Account" },
{ connectionId: 42 },
);
console.log(result.output, result.historyId);engini tools call salesforce_getrecords --args '{"sobject": "Account"}' --connection 42const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({fields: {to: 'recipient@example.com', subject: 'Hello from Engini'}})
};
fetch('https://api.engini.io/v1/tools/{toolSlug}/execute', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.engini.io/v1/tools/{toolSlug}/execute",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'fields' => [
'to' => 'recipient@example.com',
'subject' => 'Hello from Engini'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.engini.io/v1/tools/{toolSlug}/execute"
payload := strings.NewReader("{\n \"fields\": {\n \"to\": \"recipient@example.com\",\n \"subject\": \"Hello from Engini\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.engini.io/v1/tools/{toolSlug}/execute")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"fields\": {\n \"to\": \"recipient@example.com\",\n \"subject\": \"Hello from Engini\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.engini.io/v1/tools/{toolSlug}/execute")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"fields\": {\n \"to\": \"recipient@example.com\",\n \"subject\": \"Hello from Engini\"\n }\n}"
response = http.request(request)
puts response.read_body{
"isSuccess": true,
"errorMessage": null,
"executionInfo": {
"statusCode": 200,
"executionTime": 182.4,
"dataSize": 512
},
"output": {
"messageId": "00000000-0000-0000-0000-000000000000"
},
"historyId": 123456
}{
"errorCode": "<string>",
"message": "<string>",
"requestId": "<string>",
"timestamp": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>"
}
]
}{
"errorCode": "<string>",
"message": "<string>",
"requestId": "<string>",
"timestamp": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>"
}
]
}{
"errorCode": "<string>",
"message": "<string>",
"requestId": "<string>",
"timestamp": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>"
}
]
}{
"errorCode": "<string>",
"message": "<string>",
"requestId": "<string>",
"timestamp": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>"
}
]
}{
"errorCode": "<string>",
"message": "<string>",
"requestId": "<string>",
"timestamp": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>"
}
]
}{
"errorCode": "<string>",
"message": "<string>",
"requestId": "<string>",
"timestamp": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>"
}
]
}{
"errorCode": "<string>",
"message": "<string>",
"requestId": "<string>",
"timestamp": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>"
}
]
}Execute tool
Executes the named tool with the given input fields. The connection to use is resolved implicitly: an explicit connectionId takes precedence, then toolsetId scopes resolution to that toolset’s connection for the tool’s application, and otherwise the caller’s default connection for the application is used. Tool-runtime failures - the downstream call itself failing - are reported as a 200 response with isSuccess=false and an errorMessage, not as a 4xx/5xx, so callers must check isSuccess even on a successful HTTP response. A 409 is returned only when no connection can be resolved at all (no toolset connection for the app, or no default connection configured), and a 403 with errorCode=CONNECTION_BLOCKED when the resolved connection is blocked (no licence, or licence expired) - the tool is not executed at all in that case, which is why it is a 403 rather than a 200 with isSuccess=false. Every other failure uses the standard error envelope.
from engini import Engini
client = Engini() # reads ENGINI_API_KEY
result = client.tools.execute(
"salesforce_getrecords", {"sobject": "Account"}, connection_id=42
)
print(result.output, result.history_id)import { Engini } from "@engini/sdk";
const client = new Engini(); // reads ENGINI_API_KEY
const result = await client.tools.execute(
"salesforce_getrecords",
{ sobject: "Account" },
{ connectionId: 42 },
);
console.log(result.output, result.historyId);engini tools call salesforce_getrecords --args '{"sobject": "Account"}' --connection 42const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({fields: {to: 'recipient@example.com', subject: 'Hello from Engini'}})
};
fetch('https://api.engini.io/v1/tools/{toolSlug}/execute', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.engini.io/v1/tools/{toolSlug}/execute",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'fields' => [
'to' => 'recipient@example.com',
'subject' => 'Hello from Engini'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.engini.io/v1/tools/{toolSlug}/execute"
payload := strings.NewReader("{\n \"fields\": {\n \"to\": \"recipient@example.com\",\n \"subject\": \"Hello from Engini\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.engini.io/v1/tools/{toolSlug}/execute")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"fields\": {\n \"to\": \"recipient@example.com\",\n \"subject\": \"Hello from Engini\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.engini.io/v1/tools/{toolSlug}/execute")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"fields\": {\n \"to\": \"recipient@example.com\",\n \"subject\": \"Hello from Engini\"\n }\n}"
response = http.request(request)
puts response.read_body{
"isSuccess": true,
"errorMessage": null,
"executionInfo": {
"statusCode": 200,
"executionTime": 182.4,
"dataSize": 512
},
"output": {
"messageId": "00000000-0000-0000-0000-000000000000"
},
"historyId": 123456
}{
"errorCode": "<string>",
"message": "<string>",
"requestId": "<string>",
"timestamp": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>"
}
]
}{
"errorCode": "<string>",
"message": "<string>",
"requestId": "<string>",
"timestamp": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>"
}
]
}{
"errorCode": "<string>",
"message": "<string>",
"requestId": "<string>",
"timestamp": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>"
}
]
}{
"errorCode": "<string>",
"message": "<string>",
"requestId": "<string>",
"timestamp": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>"
}
]
}{
"errorCode": "<string>",
"message": "<string>",
"requestId": "<string>",
"timestamp": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>"
}
]
}{
"errorCode": "<string>",
"message": "<string>",
"requestId": "<string>",
"timestamp": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>"
}
]
}{
"errorCode": "<string>",
"message": "<string>",
"requestId": "<string>",
"timestamp": "<string>",
"details": [
{
"field": "<string>",
"issue": "<string>"
}
]
}Authorizations
Enter your JWT token
Path Parameters
The slug identifying the tool to execute.
Query Parameters
Optional toolset identifier used to scope connection resolution.
Optional explicit connection identifier to use instead of the implicitly resolved connection.
Body
The execution request containing the tool's input arguments.
Body shape for POST /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.
Input field values for the tool, keyed by field name.
Show child attributes
Show child attributes
Optional context value passed to the tool.
Filter conditions to apply to the tool's results.
Show child attributes
Show child attributes
Sort clauses to apply to the tool's results.
Show child attributes
Show child attributes
Number of leading results to skip (pagination offset).
Maximum number of results to return.
Accepted for forward compatibility but not yet honoured on this endpoint - a caller-supplied value here is silently ignored and never reaches the tool.
Show child attributes
Show child attributes
Per-call overrides for the resolved connection's fields; only fields marked overridable are accepted.
Show child attributes
Show child attributes
Response
The tool execution result, including success status and any output.
200 response shape for POST /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.
Whether the tool executed successfully. When false, see ErrorMessage.
Human-readable failure reason when IsSuccess is false; otherwise null.
Metadata about the execution (HTTP status, headers, timing, payload size).
Show child attributes
Show child attributes
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.
Identifier of the workflow-history record for this execution, when one was created.