# Computers

## List

**get** `/computers`

List all active computers for the user's organization. Use type=persistent to list persistent sessions instead.

### Query Parameters

- `type: optional "live" or "persistent"`

  Session type filter

  - `"live"`

  - `"persistent"`

### Returns

- `id: optional string`

- `auto_kill: optional boolean`

- `created_at: optional string`

- `endpoints: optional map[string]`

- `expires_at: optional string`

- `idle_expires_at: optional string`

- `inactivity_timeout_seconds: optional number`

- `kind: optional string`

- `last_activity_at: optional string`

- `max_lifetime_seconds: optional number`

- `status: optional string`

### Example

```http
curl https://api.tzafon.ai/computers \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```

## Create

**post** `/computers`

Create a new automation session. Set kind to "browser" for web automation or "desktop" for OS-level automation. Defaults to "browser" if not specified. timeout_seconds controls max lifetime, inactivity_timeout_seconds controls idle timeout, and auto_kill disables only the idle timeout (max lifetime still applies).

### Body Parameters

- `auto_kill: optional boolean`

  If true (default), kill session after inactivity

- `context_id: optional string`

- `display: optional object { height, scale, width }`

  - `height: optional number`

  - `scale: optional number`

  - `width: optional number`

- `environment_id: optional string`

- `inactivity_timeout_seconds: optional number`

  Idle timeout before auto-kill

- `kind: optional string`

  "browser" (default) or "desktop"

- `persistent: optional boolean`

  Persist cookies/storage state to DB on session teardown only if true

- `stealth: optional unknown`

- `timeout_seconds: optional number`

- `use_advanced_proxy: optional boolean`

  If true (browser sessions), use ADVANCED_PROXY_URL on session start

### Returns

- `ComputerResponse = object { id, auto_kill, created_at, 8 more }`

  - `id: optional string`

  - `auto_kill: optional boolean`

  - `created_at: optional string`

  - `endpoints: optional map[string]`

  - `expires_at: optional string`

  - `idle_expires_at: optional string`

  - `inactivity_timeout_seconds: optional number`

  - `kind: optional string`

  - `last_activity_at: optional string`

  - `max_lifetime_seconds: optional number`

  - `status: optional string`

### Example

```http
curl https://api.tzafon.ai/computers \
    -X POST \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```

## Retrieve

**get** `/computers/{id}`

Get the current status and metadata of a computer instance

### Path Parameters

- `id: string`

### Returns

- `ComputerResponse = object { id, auto_kill, created_at, 8 more }`

  - `id: optional string`

  - `auto_kill: optional boolean`

  - `created_at: optional string`

  - `endpoints: optional map[string]`

  - `expires_at: optional string`

  - `idle_expires_at: optional string`

  - `inactivity_timeout_seconds: optional number`

  - `kind: optional string`

  - `last_activity_at: optional string`

  - `max_lifetime_seconds: optional number`

  - `status: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```

## Delete

**delete** `/computers/{id}`

Terminate and clean up a computer instance, stopping the session and recording metrics

### Path Parameters

- `id: string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID \
    -X DELETE \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```

## Batch

**post** `/computers/{id}/batch`

Execute a batch of actions in sequence, stopping on first error

### Path Parameters

- `id: string`

### Body Parameters

- `actions: optional array of ComputerAction`

  - `auto_detect_encoding: optional boolean`

    For get_html_content

  - `base64: optional boolean`

    For screenshot

  - `button: optional string`

  - `debug: optional object { command, cwd, env, 4 more }`

    - `command: optional string`

    - `cwd: optional string`

    - `env: optional map[string]`

    - `max_output_length: optional number`

    - `request_id: optional string`

    - `stream: optional boolean`

    - `timeout_seconds: optional number`

  - `dx: optional number`

    For scrolling

  - `dy: optional number`

  - `height: optional number`

  - `include_context: optional boolean`

    Include page context in response

  - `key: optional string`

    For key_down/key_up

  - `keys: optional array of string`

  - `ms: optional number`

  - `proxy_url: optional string`

  - `request_id: optional string`

    RequestId is used for correlating streaming output to the originating request.
    Set on ActionRequest, not individual action types.

  - `scale_factor: optional number`

  - `tab_id: optional string`

    For tab management (browser sessions only)

  - `text: optional string`

  - `type: optional string`

    click|double_click|right_click|drag|type|keypress|scroll|wait|screenshot|go_to_url|debug|get_html_content|set_viewport|list_tabs|new_tab|switch_tab|close_tab|key_down|key_up|mouse_down|mouse_up

  - `url: optional string`

  - `width: optional number`

    For set_viewport

  - `x: optional number`

  - `x1: optional number`

    For dragging/scrolling

  - `x2: optional number`

    For dragging

  - `y: optional number`

  - `y1: optional number`

  - `y2: optional number`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/batch \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Change Proxy

**post** `/computers/{id}/change-proxy`

Change the proxy settings for the browser session

### Path Parameters

- `id: string`

### Body Parameters

- `proxy_url: optional string`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/change-proxy \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Click

**post** `/computers/{id}/click`

Perform a left mouse click at the specified x,y coordinates. Coordinates are screenshot pixel positions - send exactly what you see in the screenshot/screencast image. If target is at pixel (500, 300) in the image, send x=500, y=300. Optionally specify tab_id (browser sessions only)

### Path Parameters

- `id: string`

### Body Parameters

- `tab_id: optional string`

- `x: optional number`

- `y: optional number`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/click \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Debug

**post** `/computers/{id}/debug`

Execute a shell command with optional timeout and output length limits. Optionally specify tab_id (browser sessions only). Deprecated: use /exec or /exec/sync instead.

### Path Parameters

- `id: string`

### Body Parameters

- `command: optional string`

- `max_output_length: optional number`

- `tab_id: optional string`

- `timeout_seconds: optional number`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/debug \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Double Click

**post** `/computers/{id}/double-click`

Perform a double mouse click at the specified x,y coordinates. Coordinates are screenshot pixel positions. Optionally specify tab_id (browser sessions only)

### Path Parameters

- `id: string`

### Body Parameters

- `tab_id: optional string`

- `x: optional number`

- `y: optional number`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/double-click \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Drag

**post** `/computers/{id}/drag`

Perform a click-and-drag action from (x1,y1) to (x2,y2). Coordinates are screenshot pixel positions. Optionally specify tab_id (browser sessions only)

### Path Parameters

- `id: string`

### Body Parameters

- `tab_id: optional string`

- `x1: optional number`

- `x2: optional number`

- `y1: optional number`

- `y2: optional number`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/drag \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Retrieve Events

**get** `/computers/{id}/events`

Stream real-time events using Server-Sent Events (SSE)

### Path Parameters

- `id: string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/events \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```

## Execute

**post** `/computers/{id}/execute`

Execute a single action such as screenshot, click, type, navigate, scroll, debug, set_viewport, get_html_content or other computer use actions

### Path Parameters

- `id: string`

### Body Parameters

- `action: optional ComputerAction`

  - `auto_detect_encoding: optional boolean`

    For get_html_content

  - `base64: optional boolean`

    For screenshot

  - `button: optional string`

  - `debug: optional object { command, cwd, env, 4 more }`

    - `command: optional string`

    - `cwd: optional string`

    - `env: optional map[string]`

    - `max_output_length: optional number`

    - `request_id: optional string`

    - `stream: optional boolean`

    - `timeout_seconds: optional number`

  - `dx: optional number`

    For scrolling

  - `dy: optional number`

  - `height: optional number`

  - `include_context: optional boolean`

    Include page context in response

  - `key: optional string`

    For key_down/key_up

  - `keys: optional array of string`

  - `ms: optional number`

  - `proxy_url: optional string`

  - `request_id: optional string`

    RequestId is used for correlating streaming output to the originating request.
    Set on ActionRequest, not individual action types.

  - `scale_factor: optional number`

  - `tab_id: optional string`

    For tab management (browser sessions only)

  - `text: optional string`

  - `type: optional string`

    click|double_click|right_click|drag|type|keypress|scroll|wait|screenshot|go_to_url|debug|get_html_content|set_viewport|list_tabs|new_tab|switch_tab|close_tab|key_down|key_up|mouse_down|mouse_up

  - `url: optional string`

  - `width: optional number`

    For set_viewport

  - `x: optional number`

  - `x1: optional number`

    For dragging/scrolling

  - `x2: optional number`

    For dragging

  - `y: optional number`

  - `y1: optional number`

  - `y2: optional number`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/execute \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Hotkey

**post** `/computers/{id}/hotkey`

Press a combination of keys (e.g., ["Control", "c"] for copy). Optionally specify tab_id (browser sessions only)

### Path Parameters

- `id: string`

### Body Parameters

- `keys: optional array of string`

- `tab_id: optional string`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/hotkey \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## HTML

**post** `/computers/{id}/html`

Get the HTML content of the current browser page. Optionally specify tab_id (browser sessions only)

### Path Parameters

- `id: string`

### Body Parameters

- `auto_detect_encoding: optional boolean`

- `tab_id: optional string`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/html \
    -X POST \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```

## Keepalive

**post** `/computers/{id}/keepalive`

Extend the timeout for a computer session and verify it is still running

### Path Parameters

- `id: string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/keepalive \
    -X POST \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```

## Key Down

**post** `/computers/{id}/key-down`

Press and hold a keyboard key. Use with key_up to release. Supports modifier keys (shift, ctrl, alt, meta) for complex interactions like Shift+Click.

**Supported keys:** Modifier keys (shift, ctrl, alt, meta), special keys (enter, escape, tab, backspace, delete, space), arrow keys (arrowup, arrowdown, arrowleft, arrowright), navigation (home, end, pageup, pagedown), function keys (f1-f24), and any single character (a-z, 0-9).

**Key names are case-insensitive:** "shift", "Shift", and "SHIFT" all work.

**Example Shift+Click:** 1) key_down "shift", 2) click at coordinates, 3) key_up "shift"

### Path Parameters

- `id: string`

### Body Parameters

- `key: optional string`

  Key name to press. Case-insensitive. Examples: "shift", "ctrl", "a", "Enter"

- `tab_id: optional string`

  Optional tab ID for browser sessions (ignored for desktop sessions)

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/key-down \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{
          "key": "shift"
        }'
```

## Key Up

**post** `/computers/{id}/key-up`

Release a keyboard key that was previously pressed with key_down. The key name should match the corresponding key_down call.

**Key names are case-insensitive:** "shift", "Shift", and "SHIFT" all work.

**Important:** Always release modifier keys after use to prevent them from affecting subsequent actions.

### Path Parameters

- `id: string`

### Body Parameters

- `key: optional string`

  Key name to release. Case-insensitive. Examples: "shift", "ctrl", "a", "Enter"

- `tab_id: optional string`

  Optional tab ID for browser sessions (ignored for desktop sessions)

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/key-up \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{
          "key": "shift"
        }'
```

## Mouse Down

**post** `/computers/{id}/mouse-down`

Press and hold the left mouse button at the specified x,y coordinates. Coordinates are screenshot pixel positions. Optionally specify tab_id (browser sessions only)

### Path Parameters

- `id: string`

### Body Parameters

- `tab_id: optional string`

- `x: optional number`

- `y: optional number`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/mouse-down \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Mouse Up

**post** `/computers/{id}/mouse-up`

Release the left mouse button at the specified x,y coordinates. Coordinates are screenshot pixel positions. Optionally specify tab_id (browser sessions only)

### Path Parameters

- `id: string`

### Body Parameters

- `tab_id: optional string`

- `x: optional number`

- `y: optional number`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/mouse-up \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Navigate

**post** `/computers/{id}/navigate`

Navigate the browser to a specified URL. Optionally specify tab_id to navigate a specific tab (browser sessions only)

### Path Parameters

- `id: string`

### Body Parameters

- `tab_id: optional string`

- `url: optional string`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/navigate \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Right Click

**post** `/computers/{id}/right-click`

Perform a right mouse click at the specified x,y coordinates. Coordinates are screenshot pixel positions. Optionally specify tab_id (browser sessions only)

### Path Parameters

- `id: string`

### Body Parameters

- `tab_id: optional string`

- `x: optional number`

- `y: optional number`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/right-click \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Retrieve Screencast

**get** `/computers/{id}/screencast`

Stream only screencast frames (base64 JPEG images) using Server-Sent Events (SSE) for live browser viewing

### Path Parameters

- `id: string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/screencast \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```

## Screenshot

**post** `/computers/{id}/screenshot`

Take a screenshot of the current browser viewport, optionally as base64. Optionally specify tab_id (browser sessions only)

### Path Parameters

- `id: string`

### Body Parameters

- `base64: optional boolean`

- `tab_id: optional string`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/screenshot \
    -X POST \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```

## Scroll

**post** `/computers/{id}/scroll`

Scroll at the specified x,y position by delta dx,dy. Coordinates are screenshot pixel positions. Optionally specify tab_id (browser sessions only)

### Path Parameters

- `id: string`

### Body Parameters

- `dx: optional number`

- `dy: optional number`

- `tab_id: optional string`

- `x: optional number`

- `y: optional number`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/scroll \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Retrieve Status

**get** `/computers/{id}/status`

Get current TTLs and last activity metadata for a computer session

### Path Parameters

- `id: string`

### Returns

- `id: optional string`

- `auto_kill: optional boolean`

- `created_at: optional string`

- `expires_at: optional string`

- `idle_expires_at: optional string`

- `inactivity_timeout_seconds: optional number`

- `last_activity_at: optional string`

- `max_lifetime_seconds: optional number`

- `status: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/status \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```

## Type

**post** `/computers/{id}/type`

Type text into the currently focused element in the browser. Optionally specify tab_id (browser sessions only)

### Path Parameters

- `id: string`

### Body Parameters

- `tab_id: optional string`

- `text: optional string`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/type \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Viewport

**post** `/computers/{id}/viewport`

Change the browser viewport dimensions and scale factor. Optionally specify tab_id (browser sessions only)

### Path Parameters

- `id: string`

### Body Parameters

- `height: optional number`

- `scale_factor: optional number`

- `tab_id: optional string`

- `width: optional number`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/viewport \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Retrieve Ws

**get** `/computers/{id}/ws`

Establish WebSocket for real-time bidirectional communication

### Path Parameters

- `id: string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/ws \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```

## Domain Types

### Action Result

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Computer Action

- `ComputerAction = object { auto_detect_encoding, base64, button, 22 more }`

  - `auto_detect_encoding: optional boolean`

    For get_html_content

  - `base64: optional boolean`

    For screenshot

  - `button: optional string`

  - `debug: optional object { command, cwd, env, 4 more }`

    - `command: optional string`

    - `cwd: optional string`

    - `env: optional map[string]`

    - `max_output_length: optional number`

    - `request_id: optional string`

    - `stream: optional boolean`

    - `timeout_seconds: optional number`

  - `dx: optional number`

    For scrolling

  - `dy: optional number`

  - `height: optional number`

  - `include_context: optional boolean`

    Include page context in response

  - `key: optional string`

    For key_down/key_up

  - `keys: optional array of string`

  - `ms: optional number`

  - `proxy_url: optional string`

  - `request_id: optional string`

    RequestId is used for correlating streaming output to the originating request.
    Set on ActionRequest, not individual action types.

  - `scale_factor: optional number`

  - `tab_id: optional string`

    For tab management (browser sessions only)

  - `text: optional string`

  - `type: optional string`

    click|double_click|right_click|drag|type|keypress|scroll|wait|screenshot|go_to_url|debug|get_html_content|set_viewport|list_tabs|new_tab|switch_tab|close_tab|key_down|key_up|mouse_down|mouse_up

  - `url: optional string`

  - `width: optional number`

    For set_viewport

  - `x: optional number`

  - `x1: optional number`

    For dragging/scrolling

  - `x2: optional number`

    For dragging

  - `y: optional number`

  - `y1: optional number`

  - `y2: optional number`

### Computer Response

- `ComputerResponse = object { id, auto_kill, created_at, 8 more }`

  - `id: optional string`

  - `auto_kill: optional boolean`

  - `created_at: optional string`

  - `endpoints: optional map[string]`

  - `expires_at: optional string`

  - `idle_expires_at: optional string`

  - `inactivity_timeout_seconds: optional number`

  - `kind: optional string`

  - `last_activity_at: optional string`

  - `max_lifetime_seconds: optional number`

  - `status: optional string`

### V2 Go Backend Internal Types Page Context

- `V2GoBackendInternalTypesPageContext = object { device_scale_factor, is_main_tab, page_height, 8 more }`

  - `device_scale_factor: optional number`

  - `is_main_tab: optional boolean`

  - `page_height: optional number`

  - `page_width: optional number`

  - `scroll_x: optional number`

  - `scroll_y: optional number`

  - `tab_id: optional string`

  - `title: optional string`

  - `url: optional string`

  - `viewport_height: optional number`

  - `viewport_width: optional number`

# Exec

## Create

**post** `/computers/{id}/exec`

Execute a shell command with real-time streaming output as NDJSON. Each line is a JSON object with type (stdout/stderr/exit/error).

### Path Parameters

- `id: string`

### Body Parameters

- `command: optional string`

- `cwd: optional string`

- `env: optional map[string]`

- `timeout_seconds: optional number`

### Returns

- `code: optional number`

  for exit

- `data: optional string`

  for stdout/stderr

- `message: optional string`

  for error

- `type: optional string`

  "stdout", "stderr", "exit", "error"

### Example

```http
curl https://api.tzafon.ai/computers/$ID/exec \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

## Sync

**post** `/computers/{id}/exec/sync`

Execute a shell command and wait for completion, returning buffered stdout/stderr.

### Path Parameters

- `id: string`

### Body Parameters

- `command: optional string`

- `cwd: optional string`

- `env: optional map[string]`

- `timeout_seconds: optional number`

### Returns

- `exit_code: optional number`

- `stderr: optional string`

- `stdout: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/exec/sync \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{}'
```

# Tabs

## List

**get** `/computers/{id}/tabs`

Get a list of open tabs with IDs, URLs, titles, and main tab status (browser sessions only). Includes external CDP pages (e.g., Playwright). Excludes devtools:// and chrome:// tabs. Results may be eventually consistent for newly created tabs.

### Path Parameters

- `id: string`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/tabs \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```

## Create

**post** `/computers/{id}/tabs`

Create a new tab, optionally navigating to a URL. The new tab becomes the main tab (browser sessions only).

### Path Parameters

- `id: string`

### Body Parameters

- `url: optional string`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/tabs \
    -X POST \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```

## Delete

**delete** `/computers/{id}/tabs/{tab_id}`

Close a specific tab by ID. Cannot close the last remaining tab (browser sessions only). Tab IDs come from ListTabs.

### Path Parameters

- `id: string`

- `tab_id: string`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/tabs/$TAB_ID \
    -X DELETE \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```

## Switch

**post** `/computers/{id}/tabs/{tab_id}/switch`

Switch the main/active tab to a different tab by ID (browser sessions only). Tab IDs come from ListTabs.

### Path Parameters

- `id: string`

- `tab_id: string`

### Returns

- `ActionResult = object { error_message, executed_tab_id, page_context, 4 more }`

  - `error_message: optional string`

  - `executed_tab_id: optional string`

  - `page_context: optional V2GoBackendInternalTypesPageContext`

    - `device_scale_factor: optional number`

    - `is_main_tab: optional boolean`

    - `page_height: optional number`

    - `page_width: optional number`

    - `scroll_x: optional number`

    - `scroll_y: optional number`

    - `tab_id: optional string`

    - `title: optional string`

    - `url: optional string`

    - `viewport_height: optional number`

    - `viewport_width: optional number`

  - `request_id: optional string`

  - `result: optional map[unknown]`

  - `status: optional string`

  - `timestamp: optional string`

### Example

```http
curl https://api.tzafon.ai/computers/$ID/tabs/$TAB_ID/switch \
    -X POST \
    -H "Authorization: Bearer $TZAFON_API_KEY"
```