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. A 403 with errorCode=CONNECTION_SCOPE_MISSING means the connection has not granted access the tool needs; its details rows name the connectionId, the toolSlug, and canGrant - whether this caller may grant it itself (else the connection’s owner must). Grant access on the connection in Engini, then retry. 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>"
}
]
}Query Parameters
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.
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.