Xgodo API Documentation

Retrieves a list of job applicants for a specified job. Allows for sorting, pagination, and searching within job applicants. Note: per-job task count aggregates (`total_task`, `job_done`, `running_tasks`, `pending_tasks`, `satisfied_tasks`, `declined_tasks`, `failed_tasks`) are intentionally NOT included in the v2 response — they were rarely consumed and computing them under concurrent load is the cluster's hottest read. If you need them, derive client-side by paging with `status` filters.

Updates the status of specified job tasks. It supports changing the status, adding comments, and handles referral bonuses if the task is confirmed. By default (stopRunningAutomation=true) tasks that are still `running` are included: their automation is stopped on the device before the status is applied. Optionally accepts result_types ({ [job_task_id]: { [field]: value } }): sets or overrides the recorded result types of the listed unreviewed tasks — strictly validated against the job's result_type_pricing — re-deriving each task's price (max(0, job_price + sum of the selected values' deltas)) and storing a price_breakdown snapshot before the payout is computed. Already-confirmed tasks are never affected.

Returns job details for a specific job ID. When the job is linked to an automation (`automation_id` is set), the response also includes the automation's `automation_parameters_schema`, `job_variables_schema`, and `bucket_schema` so callers can validate / build UIs around the `automationParameters`, `jobVariables`, and bucket payloads accepted by the automation. Each schema follows the `IInputSchema` shape (`{ fields: IFieldSchema[] }`) and is `null` when the automation has no schema configured or the job has no linked automation. Note: per-job task count fields (`totla_tasks_count`, `tasks_done_count`, `tasks_confirmed_count`, `tasks_running_count`, `tasks_pending_count`) are intentionally NOT included in the v2 response — they were rarely consumed and computing them under concurrent load is the cluster's hottest read.

{
  "_id": "68910c4a5e1c7092a1fdc03a",
  "job_id": "68910c4a5e1c7092a1fdc03a",
  "job_type": "devices_automation",
  "payment_type": "action",
  "title": "Create a Google account",
  "category": ["Google"],
  "description": "Create a Google account. ...",
  "proof": "Google account email. ...",
  "Target_Workers": ["worldwide"],
  "few_times": true,
  "premium": false,
  "featured": false,
  "duration": "3",
  "positions": "3",
  "job_price": 0.06,
  "price": "0.30",
  "status": "active",
  "files": [...],
  "added": "2025-08-04T19:38:50.204Z",
  "user": {...},
  "automation_id": "83ba7359-d8eb-4374-8ecb-055af01fddfe",
  "automation_parameters_schema": {
    "fields": [
      { "name": "maxRetries", "type": "number", "required": false, "min": 1, "max": 10 }
    ]
  },
  "job_variables_schema": {
    "fields": [
      { "name": "email", "type": "string", "required": true },
      { "name": "password", "type": "string", "required": true }
    ]
  },
  "bucket_schema": {
    "fields": [
      { "name": "sessionToken", "type": "string", "required": false }
    ]
  }
}

This endpoint checks if a given search term exists in the job proofs. You can specify the search option to look for exact words or substrings.

Returns a paginated list of jobs the caller has posted under `data` (with `count`, paginated by `page`), plus a separate list of jobs shared with the caller under `shared_data` (with `shared_count`, paginated independently by `shared_page` — the current shared page is echoed back as `shared_page`). Each entry in `shared_data` carries `permission: "view" | "edit"` and `owner_username`. The response is a thin projection of the Job documents — `job_price` and `price` are stringified. Results are sorted by `added` descending. Note: per-job task counters (`job_done`, `running_task`, `pending_task`) and planned-task counters (`used_planned_tasks`, `added_planned_tasks`) are not included. To get per-task data for a specific job, use the `/api/v2/jobs/applicants` endpoint.

Returns a paginated list of jobs matching the provided filters. Supports search, category, price, location, and other filters.

This endpoint allows users to create a new job posting. It requires specific details about the job, including title, description, category, number of positions, job price, and duration.

Updates the status of a specific job.

This API must be called before tasks/submit API for jobs that have job variables. This endpoint allows workers to apply to an active job. Job variables (if any) will be returned.

{
  "_id": "68910c4a5e1c7092a1fdc03c",
  "var1": "Custom variable value 1",
  "var2": "Custom variable value 2"
}

Returns the list of recent tasks of the user, optionally filtered by job_id and by a search over job_proof. If task_id query param is provided, it will return details of a single task (search is ignored).

{
  "_id": "686f668db9c27eea026e60c7",
  "job_task_id": "686f668db9c27eea026e60c7",
  "worker_id": "676d3525e618d4ad99dae7ff",
  "job_id": "686f44cf8abf68ace53ebc8f",
  "job_title": "Create a Google account",
  "job_price": 0.06,
  "job_proof": "",
  "comment": "",
  "country_code": "IN",
  "worker_ip": "192.168.249.223",
  "status": "confirmed",
  "failureReason": null,
  "reviewed": null,
  "device_owner_share": null,
  "added": "2025-07-10T07:06:53.631Z",
  "updated": "2025-07-10T07:06:53.631Z",
  "proof_files_info": []
}

Submits a task to an active job. The endpoint operates in one of two modes selected by the target job: 1. Manual mode (default) — for regular jobs. Honors job-level gates (worker rating, country, allowed_workers, premium, few_times, custom_vars, predeclared file fields, positions, task_limit, decline_ban, Worker_Invites) and triggers task/job completion emails. The decline_ban gate is evaluated on every submission: if the job configures decline_ban, the caller is rejected while serving a ban, and is banned (and rejected) when at least min_tasks of their tasks on that job were reviewed within the last window_minutes and at least decline_rate_percent% of those were declined. Only reviewed tasks (confirmed / declined) count, measured by review time — tasks still awaiting review are ignored. 2. Automation data-dump mode — selected automatically when the target job is of type devices_automation, has automation_id set, and has no planned tasks. Used by an automation agent running another job to write structured data into a separate sink job. In this mode the endpoint: • requires the caller's token to carry job_task_id and remote_device_id (i.e. a running agent token); • requires job_proof to be valid JSON; • accepts files in the {name, extension, base64Data} shape, embedded into the JSON proof under proof[name]; • accepts an explicit status of "pending" (default), "failed", or "declined"; • derives device_id and the device-owner share from the agent's remote_device_id; • authorizes by requiring the running agent's parent job and the target data-dump job to share the same automation_id, AND the running job's owner to be the target job's owner or to appear in the target's shared_view / shared_edit; • skips manual-mode gates (rating/country/few_times/custom_vars/proof_files/positions/task_limit/Worker_Invites) and skips completion emails; • does not update automation iteration / success-rate / blacklist analytics — those are reserved for "real" agent-driven tasks created by the automation engine.

Lets an automation agent report the result type of its current task (e.g. Account Type = "Old Account" vs "New Account"). The map is strictly validated against the result_type_schema defined on the automation by its developer, and the task's price snapshot is re-derived from the job's employer-defined result_type_pricing: every value carries a price DELTA relative to the default job_price, and the task price becomes max(0, job_price + sum of the recorded values' deltas). A price_breakdown snapshot (base, per-value adjustments, total) is stored on the task so the price stays explainable even if the job's pricing is edited later. Only allowed while the task is still running — once the task finishes, its price is frozen for review and payout. Can be called multiple times; the last value before finishing wins. The agent never sends a price, only a schema-validated combination. Also available as agent.utils.job.setResultType() in automation scripts, or via the resultType parameter of agent.utils.job.submitTask().

Returns the free-form extras object of a job task owned by the calling worker. A job task starts with the extras of the planned task it was created from. Also available as agent.utils.job.getExtras() in automation scripts.

Writes the free-form extras object of a running job task owned by the calling worker. By default the keys are merged into the existing extras; pass merge: false to replace the whole object. Only allowed while the task is running. Also available as agent.utils.job.setExtras() in automation scripts.

Returns planned tasks for a job that have not yet been assigned to a job task (i.e. job_task_id is null). Supports search, pagination, and sort order. Only the job owner (or a user the job is shared with) can list its planned tasks.

This endpoint allows users to submit multiple planned tasks for a specific job. Planned tasks are pre-defined inputs that will be used when workers apply for the job.

This endpoint allows employers to delete a job task. The task must belong to a job owned by (or shared with edit permission to) the caller. Accepts either a job_task_id or planned_task_id (a planned_task_id is resolved to its associated job task). Only tasks with certain statuses can be deleted to maintain data integrity (failed, declined, confirmed) — plus running, when stopRunningAutomation is true (default), in which case the live automation is stopped on the device before deletion. The associated planned task is deleted along with the job task by default; pass keep_planned_task: true to instead preserve it (its job_task_id is reset to null) so it can be reused. Deleting does not reset the job's rate limits: for device-automation jobs the deleted task is archived and still counts toward the per-device, per-user, global and lifetime limits. Tasks declined because the agent failed to start never count toward limits, live or deleted.

Deletes unassigned planned tasks by their IDs. Planned tasks already assigned to a pending or successful job task cannot be deleted — reinitiate or delete the job task first. All IDs must belong to jobs owned by (or shared with edit permission to) the caller.

This endpoint allows employers to re-initiate one or more failed or declined tasks. Accepts either a single task_id or an array of task_ids. This makes the planned tasks available again for workers to apply. The replaced job tasks are archived and still count toward the job's per-device, per-user, global and lifetime limits (tasks declined because the agent failed to start never count), so the device that just failed waits out the interval before it can pick the task up again.

Initiate a withdrawal to a wallet address.

Returns the list & details of recent withdrawals made by the user.

{
  "total_count": 3,
  "transactions": [
    {
      "_id": "67d9f0b57131be1625d301c4",
      "reference_id": "26795145",
      "user_id": "676d3619e618d4ad99dae899",
      "recipient_id": null,
      "crypto_uuid": null,
      "payment_type": "Withdrawal",
      "payment_method": "cryptomus",
      "payment_details": "",
      "transaction_fee": "0",
      "currency": "USD",
      "amount": "-10",
      "wallet_address": "2w",
      "status": "paid",
      "reason": null,
      "created": "2025-03-18T22:16:21.895Z",
      "updated": "2025-03-18T22:16:21.895Z",
      "process_date": "2025-03-18T22:16:21.895Z",
      "transaction_id": "67d9f0b57131be1625d301c4",
      "transaction_proof": "2ca560b36dcdd7c8",
      "__v": 0
    }
  ],
  "page": 1,
  "balance": 3.54,
  "total_withdraw": -30,
  "total_deposit": 0
}

Returns the user's current balance, active balance and pending earnings.

{
  "balance": 4.434,
  "active_balance": 4.434,
  "pending_earnings": 1.25
}

Retrieves a list of devices that are either owned by the user or rented with live payment type.

[
  {
    "remote_device_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "added": "2025-08-19T10:00:00Z",
    "automations": [],
    "brand": "Samsung",
    "country": "US",
    "isEmulator": false,
    "model": "Galaxy S21",
    "name": "Atomic Mammal",
    "networkType": "wifi",
    "numberOfCores": 8,
    "online": true,
    "processor": "Snapdragon 888",
    "ramMb": 8192,
    "sdkVersion": "31",
    "version": "12"
  }
]

Returns devices that are listed on the market with payment_type 'action', currently online and not under an active automation ban. Each item includes the device id (remote_device_id — the same identifier every other device endpoint takes), the device name, country, and an isAvailable flag (false when the device has at least one job task in 'running' status, true otherwise; when job_id names a job priced above $0, running $0 tasks don't count, since a paid task can interrupt them). Results can be filtered by country and are sorted by country.

[
  {
    "remote_device_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Atomic Mammal",
    "country": "BR",
    "isAvailable": true
  },
  {
    "remote_device_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "name": "Enormous Elephant",
    "country": "US",
    "isAvailable": false
  }
]

Agent-scoped endpoint. Identifies the device from the automation agent token and returns the phone number stored on the device record only when phoneNumberVerified is true. Returns null otherwise. Backs `agent.info.getVerifiedPhoneNumber` in the automation bootstrap.

{
  "phoneNumber": "+14155550123"
}

Agent-scoped endpoint. Identifies the device from the automation agent token (or, for a token not bound to a device, from remote_device_id) and returns the server's last-known status of it: battery level and charging, online/network, ADB and media-projection state, screen lock, notification access, XGODO keyboard enabled/active, signal, memory, storage, power-save mode, granted/missing permissions, and whether a device password is saved (never the password itself). Values are what the app last reported, not live reads. Backs `agent.info.getDeviceInfoFromServer` in the automation bootstrap.

{
  "device": {
    "remote_device_id": "8fca9f3f-3206-4f6b-9778-fd80c0e9e963",
    "name": "Christian Pinniped",
    "status": "started",
    "brand": "Xiaomi",
    "model": "Redmi Note 7 Pro",
    "sdkVersion": 29,
    "processor": "Qualcomm Technologies, Inc SM6150",
    "numberOfCores": 8,
    "ramMb": 5740,
    "country": "in",
    "isEmulator": false,
    "version": "3.9.2",
    "versionCode": 30024,
    "online": true,
    "statusUpdatedAt": 1793612400000,
    "networkType": "wifi",
    "batteryLevel": 87,
    "batteryUpdatedAt": 1793612400000,
    "isCharging": true,
    "isAssistant": false,
    "isAdbConnected": true,
    "isMediaProjectionActive": false,
    "mediaProjectionUpdatedAt": null,
    "isScreenLockSet": true,
    "screenLockUpdatedAt": "2026-11-02T09:00:00.000Z",
    "notificationAccessGranted": false,
    "notificationListenerConnected": false,
    "deviceLanguage": "en-IN",
    "deviceTimezone": "Asia/Kolkata",
    "signalLevel": 4,
    "signalDbm": -52,
    "carrierName": "Jio",
    "availableRamMb": 2210,
    "isLowMemory": false,
    "availableStorageMb": 40312,
    "totalStorageMb": 109521,
    "isPowerSaveMode": false,
    "xgodoKeyboardEnabled": true,
    "xgodoKeyboardActive": false,
    "deviceStatsUpdatedAt": "2026-11-02T09:00:00.000Z",
    "granted_permissions": ["Accessibility", "NotificationAccess"],
    "missing_permissions": [],
    "permissions_updated_at": "2026-11-02T09:00:00.000Z",
    "has_device_password": true,
    "device_password_check_result": "supported",
    "device_password_check_at": "2026-11-02T09:00:00.000Z"
  }
}

Allocates a fresh 8-digit pairing PIN bound to the caller's account, valid for 10 minutes. Open the XGODO app on the phone (e.g. via an https://xgodo.com/xlink?pin=… deep link) and the app redeems the PIN through RMS, registering-if-needed and signing the device into the caller's account. Rate limited per user.

{
  "success": true,
  "pin": "48213705",
  "expiresIn": 600
}

Returns onboarding/connection status for every device the caller owns: whether the agent is connected (online), the assistant/ADB capability, whether the device phone number is verified, the best-effort granted/missing Android permission lists, and market-readiness (can_publish + missing_for_market), plus optional_missing_permissions (optional AppPermission ids worth offering, e.g. NotificationAccess, or XgodoKeyboard on Android 12 and below; never blocking). Pass remote_device_id to narrow to one device.

{
  "success": true,
  "devices": [
    {
      "remote_device_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Atomic Mammal",
      "brand": "Samsung",
      "model": "Galaxy S21",
      "online": true,
      "agent_connected": true,
      "is_onMarket": false,
      "is_rented": false,
      "is_inuse": false,
      "payment_type": "action",
      "isAssistant": true,
      "isAdbConnected": false,
      "phoneNumberVerified": true,
      "granted_permissions": ["Accessibility", "UsageAccess", "Phone", "Sms"],
      "missing_permissions": [],
      "permissions_updated_at": "2026-07-22T10:00:00Z",
      "can_publish": true,
      "missing_for_market": [],
      "optional_missing_permissions": []
    }
  ]
}

Whether a newer app version is rolled out to one of the caller's own devices, resolved against the active rollouts exactly as the device itself checks. should_update is true when a targeted version newer than the device's is available; is_mandatory is true when the device's current version is below the highest mandatory rollout (it must update before it can keep working). Pass a package to check a specific app, otherwise the platform app is used.

{
  "success": true,
  "should_update": true,
  "is_mandatory": false,
  "version_name": "3.4.1",
  "version_code": 341,
  "current_version": "3.3.0",
  "current_version_code": 330
}

Returns the caller's earnings for one owned device — the payout from confirmed tasks over the last 7 and 30 days — plus the device's pending, processing and confirmed task counts. Only tasks performed by the caller (as worker) on this device are counted; earnings are windowed by when each task was performed.

{
  "success": true,
  "remote_device_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Atomic Mammal",
  "earnings": {
    "last_7_days": 4.25,
    "last_30_days": 18.9
  },
  "tasks": {
    "pending": 2,
    "processing": 1,
    "confirmed": 137
  }
}

Removes one of the caller's devices from their account: deletes the device record, declines its running tasks, and cascades cleanup of automations, airplane-trigger links and proxy connections; RMS is told to revoke the device token and drop its socket. The device must be paired again with a fresh PIN to be used afterwards.

{
  "success": true,
  "message": "Device removed from your account"
}

Lists one or more of the caller's devices on the per-action (PPA) market. The device must be idle, not already listed/rented, have the voice-assistant role (or an active ADB connection), and have a verified device phone number. No rental pricing applies to PPA. The device stays wanted on PPA until you unpublish it: if it loses one of these capabilities, or its battery drops to the owner's battery-rule threshold, the system takes it off the market and relists it automatically once it is eligible again. A missing capability must be back within 30 minutes, otherwise the device stays unlisted; a low battery has no time limit.

{
  "success": true,
  "published": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
}

Removes one or more of the caller's devices from the market (and cancels any active live rental). Also cancels the automatic relist of a PPA device the system has temporarily taken off the market.

{
  "success": true
}

Saves (or clears) the screen-lock password for one of the caller's devices. The automatic-unlock automation uses it to enter the lock screen so passkey/credential tasks can run; it is stored encrypted and never returned. Send an empty string or null to clear it. Advisory only — it never affects whether the device can connect or be published. Saving a new value resets any previous automatic-unlock check result.

{
  "success": true,
  "password_set": true
}

Reads log rows stored on the device (app/service logs and automation console logs) for a time window, via the device itself, so the device must be online and responsive. Devices keep roughly the last 24 hours of logs. Requires the admin API token.

{
  "success": true,
  "remote_device_id": "add02036-6754-4cf7-8432-cc28be4468f0",
  "from": 1790150400000,
  "to": 1790154000000,
  "order": "desc",
  "limit": 500,
  "offset": 0,
  "count": 2,
  "has_more": false,
  "logs": [
    {
      "id": "1879442",
      "event": "Automation-6650f1c2a9b3e4d5f6a7b8c9-3f2a1b0",
      "data": "{\"message\":\"Opening app\",\"messageLevel\":\"LOG\"}",
      "timestamp": 1790153990000
    },
    {
      "id": "1879441",
      "event": null,
      "data": "recv 'action' name=automation",
      "timestamp": 1790153985000
    }
  ]
}

All connections owned by, or currently routed through, devices the caller owns. The `password` is plaintext — RMS owns the credential.

{
  "success": true,
  "connections": [
    {
      "connectionId": "wXyZ04827193",
      "password": "p9F7bX3cVqLt",
      "ownerUserId": "add02036-6754-4cf7-8432-cc28be4468f0",
      "name": "client-A",
      "createdAt": "2026-04-25T13:22:11Z",
      "deviceId": "add02036-6754-4cf7-8432-cc28be4468f0",
      "authMode": "ip_whitelist",
      "whitelistCount": 2
    }
  ]
}

Generates a fresh `connectionId` (4 letters + 8 digits) and 12-char password and associates it with the chosen device. Default `auth_mode` is `password` (save the plaintext password from the response). Pass `auth_mode: ip_whitelist` with `whitelist_ips` for a passwordless, IP-authenticated connection (seed IPs are added atomically). A `password` connection may also take optional `whitelist_ips` (allowed IPs, addable later). The mode is stored and returned as `authMode`.

{
  "success": true,
  "connection": {
    "connectionId": "wXyZ04827193",
    "password": "p9F7bX3cVqLt",
    "ownerUserId": "add02036-6754-4cf7-8432-cc28be4468f0",
    "name": "client-A",
    "createdAt": "2026-04-25T13:22:11Z",
    "deviceId": "add02036-6754-4cf7-8432-cc28be4468f0",
    "authMode": "password",
    "whitelistCount": 0
  }
}

Cascades on RMS, orchestrator, and the legacy mirror. Active sessions are terminated.

Replaces the connection's password (same `connectionId`). Active sessions continue on the old credential until they close.

{ "success": true, "password": "qK4LmPzWxR7a" }

Hot-swap the exit device. Owner must own both the source connection and the target device.

Connection stays alive but cannot authenticate until re-associated.

Per-connection block list (in addition to global + per-device).

{ "success": true, "domains": ["example.com", "tracker.io"] }

Adds one or more domains to the connection's blacklist. Suffix matching applies on the proxy side — blocking `example.com` also blocks `sub.example.com`.

Removes one or more domains from the connection's blacklist.

Returns the IP/CIDR patterns currently on the connection's whitelist. When a customer's source IP matches any pattern, they can open proxy streams without a password — just the `connectionId` in the SOCKS5/HTTP username field.

{
  "success": true,
  "ips": ["203.0.113.5", "10.0.0.0/8"]
}

Adds an IP or CIDR to the connection's whitelist — either mode. On a username/password connection the first whitelisted IP starts restricting password logins to the whitelisted IPs (whitelisted IPs themselves connect without credentials). Idempotent — re-posting the same pattern updates its label. Domain patterns are rejected (use blacklist for domain-level control).

Removes an IP/CIDR from the connection's whitelist. On an IP-whitelist connection removing the LAST IP is refused (409) — it must always keep at least one; delete the connection instead. A username/password connection may remove all its IPs (the password then works from any IP).

Returns the current egress transport mode for the device. Determines which network interface outbound traffic exits through.

Changes the egress transport mode. The phone picks up the change within one heartbeat interval (~30 s). `cellular` uses the carrier IP (default), `wifi` uses the WiFi router's public IP, `auto` prefers cellular with WiFi fallback. Note: `wifi` mode is partial — the downstream transport binding (cellular + WiFi tunnel for cost savings) requires additional phone-side work.

Creates a shareable trigger URL for one of your devices. Capped at 20 links per device. Save the returned `url` — it is the credential for triggering a rotation.

{
  "success": true,
  "link": {
    "id": "665f1c2ab7e4d3a9c8f01234",
    "device_id": "add02036-6754-4cf7-8432-cc28be4468f0",
    "label": "client-A",
    "created_at": "2026-04-25T13:22:11Z",
    "url": "https://xgodo.com/ip-rotate/665f1c2ab7e4d3a9c8f01234"
  }
}

Replaces the link id (and therefore its URL), keeping the label and device. Use it to revoke a leaked URL without creating a new link. Response shape is the same as create.

{
  "success": true,
  "link": {
    "id": "665f1c2ab7e4d3a9c8f01234",
    "device_id": "add02036-6754-4cf7-8432-cc28be4468f0",
    "label": "client-A",
    "created_at": "2026-04-25T13:22:11Z",
    "url": "https://xgodo.com/ip-rotate/665f1c2ab7e4d3a9c8f01234"
  }
}

Removes the link. Its URL stops working immediately.

One log entry per SOCKS5 / HTTP CONNECT attempt. Backed by ClickHouse; results are post-filtered to devices owned by the caller.

{
  "success": true,
  "total": 12345,
  "entries": [
    {
      "timestamp": "2026-04-25T13:22:11Z",
      "connectionId": "wXyZ04827193",
      "deviceId": "add02036-6754-4cf7-8432-cc28be4468f0",
      "serverNode": "server-us-aws",
      "target": "example.com:443",
      "targetType": "domain",
      "port": 443,
      "resolvedIp": "",
      "action": "allowed",
      "blockReason": null,
      "bytesIn": 184213,
      "bytesOut": 4218
    }
  ]
}

Per-(device, connection) byte counts, optionally grouped by hour or day. When `deviceId` is omitted the backend issues one query per owned device and merges.

{
  "success": true,
  "rows": [
    {
      "deviceId": "add02036-6754-4cf7-8432-cc28be4468f0",
      "connectionId": "wXyZ04827193",
      "bytesIn": 152841234,
      "bytesOut": 9183748,
      "bucket": "2026-04-25T13:00:00Z"
    }
  ]
}

Returns every proxy connection across all users, joined with the associated device's metadata and the orchestrator's bandwidth aggregates (24h + lifetime). Requires the admin API token (`X-Admin-Token`). `device` is `null` when the connection has no current association.

{
  "total": 2,
  "proxies": [
    {
      "connection_id": "wXyZ04827193",
      "name": "client-A",
      "password": "p9F7bX3cVqLt",
      "created_at": "2026-04-25T13:22:11Z",
      "bytes_last_24h": 152841234,
      "bytes_lifetime": 9183748192,
      "device": {
        "remote_device_id": "add02036-6754-4cf7-8432-cc28be4468f0",
        "user_id": "65f3a1c0d4e2f10012abcd34",
        "name": "Atomic Mammal",
        "brand": "Samsung",
        "model": "SM-G998B",
        "country": "US",
        "online": true,
        "is_rented": false,
        "is_onMarket": false
      }
    },
    {
      "connection_id": "aBcD19384756",
      "name": null,
      "password": "qK4LmPzWxR7a",
      "created_at": "2026-04-25T13:22:12Z",
      "bytes_last_24h": 0,
      "bytes_lifetime": 24576,
      "device": null
    }
  ]
}

Returns a paginated list of every bucket attached to this job, with the device display name resolved for each.

{
  "buckets": [
    {
      "_id": "65f1...",
      "job_id": "65aa...",
      "remote_device_id": "8b2f-uuid",
      "data": { "sessionToken": "abc123", "loggedIn": true },
      "updated_at": "2026-04-15T08:14:00.000Z",
      "device_name": "Pixel 5 — Lab"
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 1
}

Wipes every bucket associated with this job. Caller must have `edit` access (owner or shared-edit).

Returns the bucket for this `(job_id, device_id)` pair. 404 when none exists or the job is inaccessible.

{
  "bucket": {
    "_id": "65f1...",
    "job_id": "65aa...",
    "remote_device_id": "8b2f-uuid",
    "data": { "sessionToken": "abc123", "loggedIn": true },
    "updated_at": "2026-04-15T08:14:00.000Z"
  }
}

Replaces the bucket payload for this `(job_id, device_id)` pair (no merge — `data` becomes the new bucket). Validated against the automation's `bucket_schema` when one is defined. Caller must have `edit` access.

Removes the bucket for this `(job_id, device_id)` pair. Caller must have `edit` access.

Reads the device-scoped bucket. The `remote_device_id` is taken from the token when it carries a device context; non-agent callers must supply it in the body.

{
  "deviceBucket": {
    "accountToken": "xyz",
    "username": "user@example.com"
  }
}

Merges the supplied object into the existing device bucket. Existing keys not in the payload are preserved.

{
  "success": true,
  "deviceBucket": {
    "accountToken": "xyz",
    "username": "user@example.com"
  }
}

Returns the recording record attached to a task, or null when the task was launched without recording. Poll this while status is requested, recording or uploading; received_bytes and size_bytes give upload progress. While uploading, upload_completed_at is null until the device has sent every byte; once set, the server is saving the video to storage and status turns uploaded when that finishes. The response never includes the device upload token or the storage key.

{
  "success": true,
  "recording": {
    "recording_id": "3f2a6c1e-8b4d-4e5f-9a0b-1c2d3e4f5a6b",
    "job_task_id": "60c72b2f9b1e8c001c8e4d8a",
    "job_id": "60c72b2f9b1e8c001c8e4d00",
    "remote_device_id": "9b1e8c00-1c8e-4d8a-b2f9-60c72b2f9b1e",
    "automation_id": "60c72b2f9b1e8c001c8e4d11",
    "status": "uploaded",
    "status_reason": null,
    "quality": "medium",
    "max_duration_minutes": 0,
    "started_at": "2026-10-16T09:00:05.000Z",
    "ended_at": "2026-10-16T09:03:09.000Z",
    "duration_ms": 184000,
    "stop_reason": "automation_stopped",
    "width": 720,
    "height": 1600,
    "mime": "video/mp4",
    "size_bytes": 12582912,
    "received_bytes": 12582912,
    "upload_completed_at": "2026-10-16T09:03:12.000Z",
    "uploaded_at": "2026-10-16T09:03:20.000Z",
    "retention_days": 7,
    "expires_at": "2026-10-23T09:03:20.000Z",
    "created_at": "2026-10-16T09:00:00.000Z",
    "updated_at": "2026-10-16T09:03:20.000Z"
  }
}

Paginated list of every recording record of a job, newest first, with the device's display name. Use the status filter to find, for example, only uploaded recordings or every skipped one with its reason.

{
  "success": true,
  "recordings": [
    {
      "recording_id": "3f2a6c1e-8b4d-4e5f-9a0b-1c2d3e4f5a6b",
      "job_task_id": "60c72b2f9b1e8c001c8e4d8a",
      "status": "uploaded",
      "status_reason": null,
      "quality": "medium",
      "duration_ms": 184000,
      "size_bytes": 12582912,
      "uploaded_at": "2026-10-16T09:03:20.000Z",
      "expires_at": "2026-10-23T09:03:20.000Z",
      "device_name": "Atomic Mammal",
      "...": "same fields as the single-recording response"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Returns a time-limited playback URL for an uploaded recording, valid for one hour, suitable for a video src or a direct download. The URL is self-contained (the signature is the credential): it needs no Authorization header, supports HTTP Range requests (206 Partial Content, Accept-Ranges: bytes) and serves video/mp4. Request a fresh URL when it expires. Only recordings in uploaded status have a URL.

{
  "success": true,
  "url": "https://xgodo.com/recordings/2026/10/3f2a6c1e-8b4d-4e5f-9a0b-1c2d3e4f5a6b.mp4?md5=...&expires=1760605400",
  "expires_at": "2026-10-16T10:03:20.000Z"
}

Removes the video from storage and marks the record deleted. The record itself is kept, so the task still shows that a recording existed; a deleted recording cannot be restored. Deleting an already deleted recording succeeds. Owner only: users the job is shared with get 404.

Walks the commit log and returns one page at a time, newest-first. Use `page` + `limit` to scroll; `hasMore` is `true` while there's a next page. Server fetches up to `(page × limit) + 1` commits per call — deep pagination gets slower, which is fine for automation repos that stay small.

{
  "success": true,
  "page": 1,
  "limit": 20,
  "hasMore": true,
  "commits": [
    {
      "hash": "5c1e9a9f...",
      "message": "Handle new consent dialog\n",
      "author": "jane",
      "authorEmail": "jane@example.com",
      "parents": ["a93d41e2..."],
      "timestamp": "2026-09-28T11:30:00.000Z"
    }
  ]
}

Returns the git log entry for one commit — the same fields `git show` would print as a header (message, author, timestamp, parent and tree oids). Use this to resolve a hash from the paginated history into a full record, or to check a commit's parent chain. The hash can be a merge commit or a regular commit.

{
  "success": true,
  "commit": {
    "hash": "5c1e9a9f...",
    "message": "Handle new consent dialog\n",
    "author": "jane",
    "timestamp": "2026-09-28T11:30:00.000Z",
    "tree": "41aa...",
    "parent": ["a93d41e2..."]
  }
}

Read-only file tree of the latest commit on main (uncommitted work in the owner's editor is not visible). Owner, editors and contributors.

Returns `{ content, path, commit }`. Owner, editors and contributors.

Owner and editors see every pull request; contributors see their own. Newest activity first, max 200.

{
  "success": true,
  "role": "contributor",
  "pull_requests": [
    {
      "number": 3,
      "title": "Fix login step on Android 14",
      "status": "open",
      "author_id": "676d...",
      "author_username": "jane",
      "comment_count": 2,
      "has_conflicts": false,
      "created_at": "2026-09-28T10:00:00.000Z",
      "updated_at": "2026-09-28T11:30:00.000Z",
      "merged_at": null,
      "closed_at": null
    }
  ]
}

Contributors only. Creates the pull request and its workspace from the latest commit. A contributor can have at most 20 draft/open pull requests per automation.

{
  "success": true,
  "pull_request": { "number": 3, "status": "draft", "title": "Fix login step on Android 14" }
}

Details, commits (those not in main), comments, and the caller's permissions. For draft/open pull requests `merge_state` is `{ state: "ready" }`, `{ state: "no_changes" }` or `{ state: "behind", conflicts: [...] }` — main has moved on; with an empty `conflicts` it can be merged as is, otherwise `conflicts` lists the files the author must resolve by updating from main.

{
  "success": true,
  "pull_request": {
    "number": 3,
    "title": "Fix login step on Android 14",
    "description": "...",
    "status": "open",
    "author_username": "jane",
    "base_commit": "a93d...",
    "head_commit": "5c1e...",
    "merged_commit": null,
    "conflict_files": [],
    "merge_state": { "state": "ready" },
    "main_has_uncommitted_changes": false,
    "commits": [{ "hash": "5c1e...", "message": "Handle new consent dialog", "author": "jane", "parents": 1, "timestamp": "..." }],
    "comments": [{ "id": "...", "username": "owner", "body": "Looks good", "created_at": "..." }]
  },
  "permissions": { "role": "contributor", "is_author": true, "can_edit": true, "can_merge": false, "can_close": true, "can_comment": true }
}

Author only, while draft/open. Set `status: "open"` to request review (notifies the owner and editors) or `"draft"` to take it back.

Files the pull request changes, with full content: `{ fromHash, toHash, files: [{ path, status, original, modified }] }`. For merged pull requests, the change the merge commit introduced.

Author only. Every workspace file with its git blob hash and size — compare against local files to decide what to sync (same contract as `GET /api/v2/automation-project/:id/files`).

Author only. Returns `{ content }` (UTF-8).

Author only. Writes files into the workspace (uncommitted until you commit). Body limit 50 MB.

{
  "success": true,
  "updated": [
    { "path": "src/main.js", "hash": "9f1c...", "compiled": true },
    { "path": "src/main.ts", "hash": "41aa...", "compiled": true }
  ]
}

Author only. Deleting a `.ts` file also deletes its compiled `.js`; deleting a compiled `.js` directly is rejected.

Author only. Returns `{ hasChanges, changes: [{ path, status }], head_commit, update_in_progress, conflict_files }`.

Author only. Returns `{ commitHash, files: [{ path, status, original, modified }] }`.

Author only. Commits all workspace changes to the pull request (never to main). Completes a pending update from main. New commits on an open pull request email the automation's PR notification addresses at most every 15 minutes.

Author only. Merges main's latest commit into the pull request. The workspace must have no uncommitted changes. A clean merge is committed automatically.

Author only. With `path`, restores that file; without, discards everything (and cancels a pending update from main).

Anyone who can see the pull request, while it's draft/open. Max 500 comments per pull request.

Owner or editors, open pull requests only. **The merged code goes live on devices immediately.** The automation's own working tree must have no uncommitted changes.

Owner, editors or the author. Closes without merging and deletes the workspace; committed work stays visible in the pull request.

Owner or editors. Returns `{ pr_notifications: { email_enabled, additional_emails } }`.

Owner or editors. Pull request emails (opened, new commits, comments, merged, closed) go only to `additional_emails` — never to users' account emails — and skip whoever triggered the event. The owner, editors and author get in-app notifications.

Uploads a file to temporary storage. Files are automatically deleted after 15 minutes. Maximum file size is 50 MB. Use multipart/form-data with 'file' field name.

{
  "success": true,
  "message": "File uploaded successfully",
  "data": {
    "filename": "1234567890_example.pdf",
    "originalName": "example.pdf",
    "size": 1024000,
    "url": "https://api.example.com/temp/1234567890_example.pdf",
    "expiresAt": "2025-10-08T12:15:00.000Z"
  }
}

Retrieves a previously uploaded temporary file. Files expire after 15 minutes from upload time.