API Reference
REST API endpoints for automation control
These API endpoints allow you to programmatically control automations on devices. All endpoints require authentication via Bearer token in the Authorization header.
Authentication
All API requests must include an Authorization header with a valid Bearer token:
Authorization: Bearer your_api_token/api/v2/devices/launchAutomationLaunch Automation
Launches a saved automation project on one or more devices. Use this to run automations that have been created and saved in the IDE.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
device_ids | string[] | Yes | Array of device IDs to run the automation on |
automationId | string | Yes | The ID of the saved automation project |
command | string | Yes | Command to execute: "start" or "stop" |
automationParameters | object | No | Parameters defined in the automation schema |
jobVariables | object | No | Job-specific variables for the automation |
{ "device_ids": ["device_123456", "device_789012"], "automationId": "83ba7359-d8eb-4374-8ecb-055af01fddfe", "command": "start", "automationParameters": { "maxRetries": 3, "timeout": 30000 }, "jobVariables": { "email": "user@example.com", "password": "secret123" }}Responses
{ "success": true, "message": "Action performed successfully"}{ "success": false, "message": "Some devices offline or not found."}/api/v2/devices/launchDirectAutomationLaunch Direct Automation
Launches automation code directly on a device without saving it as a project. You provide a unique launch ID (UUID) to track the automation and retrieve logs.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
device_id | string | Yes | The ID of the device to run automation on |
launch_id | string (UUID) | Yes | Unique identifier for this automation launch (generate a UUID) |
command | string | Yes | Command to execute: "start" or "stop" |
code | string | Yes | JavaScript/TypeScript code to execute on the device |
automationParameters | object | No | Parameters accessible via agent.arguments.automationParameters |
jobVariables | object | No | Variables accessible via agent.arguments.jobVariables |
{ "device_id": "device_123456", "launch_id": "550e8400-e29b-41d4-a716-446655440000", "command": "start", "code": "console.log('Hello from automation!');", "automationParameters": { "maxRetries": 3 }, "jobVariables": { "targetUrl": "https://example.com" }}Responses
{ "success": true, "message": "Action performed successfully"}{ "success": false, "message": "Some devices offline or not found."}Using the launch_id
The launch_id you provide is used to track this specific automation instance. Use this same ID when calling automationLogs to retrieve logs for this automation.
/api/v2/devices/stopAllAutomationsStop All Automations
Stops all running automations on the specified device.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
device_id | string | Yes | The ID of the device to stop automations on |
{ "device_id": "device_123456"}Responses
{ "success": true, "message": "All automations stopped successfully"}Invalid device_id or device not found
/api/v2/devices/automationLogsGet Automation Logs
Retrieves console logs from running automations. Only returns logs from the last 10 minutes. Use the from parameter for pagination to get logs after a specific log ID.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
device_id | string | Yes | The ID of the device to get logs from |
automation_ids | string[] | Yes | Array of automation IDs or launch IDs (for direct automations) to get logs for |
from | string | No | Log ID to get logs after (for pagination) |
automation_ids for Direct Automations
When using launchDirectAutomation, pass the launch_id you provided in the automation_ids array to retrieve logs for that specific automation.
{ "device_id": "device_123456", "automation_ids": ["550e8400-e29b-41d4-a716-446655440000"], "from": "e0e1a3ef-7b2a-42b5-8f21-b845fa41c8b9"}Responses
{ "logs": [ { "id": "e0e1a3ef-7b2a-42b5-8f21-b845fa41c8b9", "automationId": "550e8400-e29b-41d4-a716-446655440000", "message": "Processing screen content...", "lineNumber": 42, "messageLevel": "log", "timestamp": 1755811585870 }, { "id": "f1f2b4ff-8c3b-53c6-9g32-c956gb52d9ca", "automationId": "550e8400-e29b-41d4-a716-446655440000", "message": "Button clicked successfully", "lineNumber": 45, "messageLevel": "log", "timestamp": 1755811586120 } ]}Log Levels
| Level | Description |
|---|---|
log | Standard console.log output |
warn | Warning messages from console.warn |
error | Error messages from console.error |
/api/v2/automation/file/:idWrite Project File
Creates or updates a file within an automation project. For TypeScript files, the content is automatically compiled to JavaScript.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The automation project ID |
Request Body
| Parameter | Type | Description |
|---|---|---|
path | string | Relative file path within the project (e.g., main.ts, utils/helpers.ts) |
content | string | The file content (max ~50MB) |
{ "path": "main.ts", "content": "async function main() {\n console.log('Hello!');\n stopCurrentAutomation();\n}\n\nmain();"}Responses
{ "success": true, "path": "main.ts", "compiledPath": "main.js", "compiled": true}{ "success": false, "message": "TypeScript compilation failed", "errors": ["Error at 5:10: Property 'foo' does not exist on type 'string'."]}Automation project not found or access denied
TypeScript Compilation
When writing .ts files, the TypeScript is automatically compiled and both the source (.ts) and compiled (.js) files are saved. You cannot directly edit .js files that have a paired .ts source.
/api/v2/automation/file/:idRead Project File
Reads the content of a file within an automation project.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The automation project ID |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
path | string | Relative file path within the project (e.g., main.ts) |
curl "https://xgodo.com/api/v2/automation/file/83ba7359-d8eb-4374-8ecb-055af01fddfe?path=main.ts" \ -H "Authorization: Bearer your_api_token"Responses
{ "success": true, "content": "async function main() {\n console.log('Hello!');\n stopCurrentAutomation();\n}\n\nmain();", "path": "main.ts"}File or automation project not found
/api/v2/automation/commit/:idCommit Project Changes
Creates a new commit with all current changes in the automation project. The project must have uncommitted changes for this to succeed.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The automation project ID |
Request Body
| Parameter | Type | Description |
|---|---|---|
message | string | The commit message describing the changes (1-1000 characters) |
{ "message": "Add error handling to main automation flow"}Responses
{ "success": true, "commit": { "hash": "a1b2c3d4e5f6789012345678901234567890abcd", "message": "Add error handling to main automation flow" }}{ "success": false, "message": "No changes to commit"}Automation project not found or access denied
Version Control
Each automation project has built-in version control. After making changes with the Write Project File API, use this endpoint to commit those changes. The commit hash can be used to track versions and revert if needed.
Usage Example
Here's a complete example of launching a direct automation and polling for logs:
const API_BASE = "https://xgodo.com";const TOKEN = "your_api_token";
// Generate a unique launch IDfunction generateUUID(): string { return crypto.randomUUID();}
async function runDirectAutomation(deviceId: string, code: string) { const launchId = generateUUID();
// Launch the automation const launchRes = await fetch(`${API_BASE}/api/v2/devices/launchDirectAutomation`, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TOKEN}` }, body: JSON.stringify({ device_id: deviceId, launch_id: launchId, command: "start", code: code, automationParameters: { maxRetries: 3 }, jobVariables: { targetUrl: "https://example.com" } }) });
const launchData = await launchRes.json();
if (!launchData.success) { throw new Error(launchData.message); }
console.log("Automation started with launch ID:", launchId);
// Poll for logs using the launch_id let lastLogId: string | undefined;
const pollLogs = async () => { const logsRes = await fetch(`${API_BASE}/api/v2/devices/automationLogs`, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TOKEN}` }, body: JSON.stringify({ device_id: deviceId, automation_ids: [launchId], // Use launch_id here from: lastLogId }) });
const logsData = await logsRes.json();
for (const log of logsData.logs) { console.log(`[${log.messageLevel}] ${log.message}`); lastLogId = log.id; } };
// Poll every 2 seconds const interval = setInterval(pollLogs, 2000);
// Stop after 60 seconds setTimeout(async () => { clearInterval(interval);
// Stop the automation await fetch(`${API_BASE}/api/v2/devices/stopAllAutomations`, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TOKEN}` }, body: JSON.stringify({ device_id: deviceId }) });
console.log("Automation stopped"); }, 60000);}
// UsagerunDirectAutomation("device_123456", ` const params = agent.arguments.automationParameters; const vars = agent.arguments.jobVariables;
console.log("Max retries:", params.maxRetries); console.log("Target URL:", vars.targetUrl);
await agent.actions.goHome(); console.log("Done!");
stopCurrentAutomation();`);Error Handling
401 Unauthorized
The API token is missing, invalid, or expired. Ensure you're passing a valid Bearer token in the Authorization header.
400 Bad Request
The request parameters are invalid or missing. Check that all required fields are provided with correct types.
Device Offline
The target device is not connected. Ensure the device is online and has the Xgodo app running before launching automations.