API Endpoints

ZestSSH’s automation API exposes five actions. Each can be invoked via the zestssh:// URL scheme (all platforms) or Android intents (Android only).

execute --- Run a Command

Connects to a server, runs a single command, captures output, and disconnects.

URL Scheme

zestssh://execute?connection=LABEL_OR_ID&command=COMMAND&key=API_KEY

Android Intent

• Action: com.affluentlabs.zestssh.EXECUTE
• Extras:
  • connection_id (String) --- connection label or UUID
  • command (String) --- the shell command
  • key (String) --- API key
  • timeout (int, optional) --- seconds, default 30

Query Parameters

Parameter	Required	Default	Description
connection	Yes	---	Connection label (case-insensitive) or UUID
command	Yes	---	Shell command to execute
key	Yes	---	API key
timeout	No	30	Timeout in seconds
grep	No	---	Regex pattern to filter output lines
head	No	---	Keep only first N lines after grep
tail	No	---	Keep only last N lines after head
callback	No	---	HTTPS webhook URL to POST results to

Response

Returns to the calling app via Android’s result mechanism:

• stdout --- command output (filtered if grep/head/tail were specified)
• exit_code --- 0 for success, non-zero for failure

---

snippet --- Run a Saved Snippet

Runs a snippet by name on a connection. Supports variable substitution.

URL Scheme

zestssh://snippet?connection=LABEL_OR_ID&name=SNIPPET_NAME&key=API_KEY

Android Intent

• Action: com.affluentlabs.zestssh.SNIPPET
• Extras:
  • connection_id (String)
  • snippet_name (String)
  • key (String)
  • var_VARNAME (String, optional) --- one extra per variable

Query Parameters

Parameter	Required	Default	Description
connection	Yes	---	Connection label or UUID
name	Yes	---	Snippet label (case-insensitive exact match)
key	Yes	---	API key
var_*	No	---	Variable substitutions. var_branch=main replaces {{branch}} in the snippet

Variable Substitution

If a snippet’s command contains {{placeholder}} patterns, pass matching variables with the var_ prefix:

zestssh://snippet?connection=prod&name=deploy&var_branch=main&var_tag=v2.1&key=KEY

This replaces {{branch}} with main and {{tag}} with v2.1 in the snippet command before execution.

---

batch --- Run on Multiple Connections

Executes the same command across multiple connections, either in parallel or sequentially.

URL Scheme

zestssh://batch?connections=A,B,C&command=COMMAND&key=API_KEY

Query Parameters

Parameter	Required	Default	Description
connections	Yes	---	Comma-separated list of connection labels or UUIDs
command	Yes	---	Shell command
key	Yes	---	API key
timeout	No	30	Timeout in seconds (per connection)
parallel	No	true	true for concurrent, false for sequential
grep	No	---	Regex filter applied to each connection’s output
head	No	---	First N lines per connection
tail	No	---	Last N lines per connection
callback	No	---	HTTPS webhook URL

Response

Combined output with headers per connection:

=== Web1 (exit=0) ===
output from Web1
=== Web2 (exit=0) ===
output from Web2
=== Web3 (exit=1) ===
STDERR: error message

Overall exit code is 0 only if all connections succeeded.

---

workflow --- Run a Workflow

Triggers a saved multi-step workflow by name or ID.

URL Scheme

zestssh://workflow?name=WORKFLOW_NAME&key=API_KEY

Or by ID:

zestssh://workflow?id=WORKFLOW_UUID&key=API_KEY

Android Intent

• Action: com.affluentlabs.zestssh.WORKFLOW
• Extras:
  • workflow_name (String) or workflow_id (String)
  • key (String)

Query Parameters

Parameter	Required	Default	Description
name	Yes*	---	Workflow name (case-insensitive)
id	Yes*	---	Workflow UUID
key	Yes	---	API key

*Either name or id is required.

Response

Summary of workflow execution including step count, success count, and total elapsed time.

---

connect --- Verify Connectivity

Tests that a connection can be established and authenticated. Runs echo "ZestSSH: connected successfully" and disconnects.

Android Intent

• Action: com.affluentlabs.zestssh.CONNECT
• Extras:
  • connection_id (String)
  • key (String)

URL Scheme

There is no dedicated connect URL scheme endpoint. Use execute with a simple command like echo ok for the same effect.

Response

• stdout --- “Connected to [connection] successfully” or error message
• exit_code --- 0 for success, 1 for failure

---

Webhook Callback Format

When a callback URL is provided, ZestSSH sends an HTTPS POST with:

{
  "connection": "server-label",
  "command": "the executed command",
  "stdout": "command output",
  "stderr": "error output if any",
  "exit_code": 0,
  "elapsed_ms": 1234,
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Requirements:

• The callback URL must use HTTPS. HTTP URLs are rejected.
• The POST is fire-and-forget --- ZestSSH does not retry on failure.
• Content-Type is application/json.

---

Error Responses

All endpoints return errors in the same format:

Condition	stdout	exit_code
Pro subscription required	ERROR: ZestSSH Pro subscription required for automation.	1
Automation disabled	ERROR: Automation is disabled in ZestSSH settings.	1
Invalid API key	ERROR: Invalid or missing automation API key.	1
Connection not found	ERROR: Connection not found: [name]	1
Snippet not found	ERROR: Snippet not found: [name]	1
Workflow not found	ERROR: Workflow not found: [name]	1
Missing parameters	ERROR: No command specified.	1
Timeout	Timeout: [details]	1
SSH error	Error description	1