Instance Control

Introspection, tab management, viewport control, and cookie management for running browser instances. These endpoints operate on a specific browser instance within a container and require the browser_id (0-based index) or browser_host/browser_port pair to identify the target.

Introspection

`GET /metadata`

Returns detailed metadata for a browser instance, including session info, browser/OS details, viewport, geolocation, network policy, open tabs, and DevTools endpoints.

cURL
SDK

curl -X GET "https://myproj-abc123def4-browser-1.us-east-1.containers.hoody.icu/metadata?browser_id=0"

const result = await client.browser.introspection.getMetadata({ browser_id: "0" });

Parameters

Name	In	Type	Required	Description
`browser_id`	query	string	Yes	Unique identifier for the browser instance (0-based index)
`start`	query	boolean	No	Controls instance creation behavior. Default: instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally: set to `true` to create an instance. Default: `true`

Response

{
  "engine": "playwright",
  "stealth": false,
  "headless": true,
  "chromiumBuildId": "136.0.7103.113",
  "chromiumExecutablePath": "/hoody/storage/hoody-browser/chrome/chrome/linux-136.0.7103.113/chrome-linux64/chrome",
  "browserExecutablePath": "/hoody/storage/hoody-browser/chrome/chrome/linux-136.0.7103.113/chrome-linux64/chrome",
  "fingerprintId": "default",
  "display": ":99",
  "iframe_url": null,
  "browser_id": "0",
  "browser_host": "127.0.0.1",
  "browser_port": 35791,
  "sessionId": "sess-abc123def4",
  "sessionName": "default",
  "timezoneId": "America/New_York",
  "locale": "en-US",
  "geolocation": {
    "latitude": 40.7128,
    "longitude": -74.006,
    "accuracy": 50
  },
  "viewport": {
    "width": 1280,
    "height": 800,
    "deviceScaleFactor": 1,
    "screenWidth": 1280,
    "screenHeight": 800
  },
  "viewportSource": "creation",
  "userAgentString": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
  "browserName": "chromium",
  "browserFullVersion": "136.0.7103.113",
  "operatingSystemName": "Linux",
  "operatingSystemPlatform": "Linux x86_64",
  "operatingSystemVersion": "5.15.0",
  "renderingEngine": "Blink",
  "renderingEngineVersion": "136.0.7103.113",
  "webSocketDebuggerUrl": "wss://myproj-abc123def4-cdp-1.us-east-1.containers.hoody.icu/devtools/browser/b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
  "devtoolsHttpUrl": "https://myproj-abc123def4-cdp-1.us-east-1.containers.hoody.icu/json/version",
  "devtoolsFrontendUrl": "https://myproj-abc123def4-cdp-1.us-east-1.containers.hoody.icu",
  "extensions": [],
  "useRemoteDebuggingPort": true,
  "remoteDebuggingPort": 9222,
  "remoteDebuggingAddress": "0.0.0.0",
  "quicDisabled": true,
  "http3Disabled": true,
  "dnsOverHttpsEnabled": true,
  "dnsOverHttpsUrl": "https://cloudflare-dns.com/dns-query",
  "tabs": [
    { "id": 1, "url": "https://example.com" }
  ]
}

{
  "engine": "playwright",
  "stealth": false,
  "headless": true,
  "chromiumBuildId": "136.0.7103.113",
  "chromiumExecutablePath": "/hoody/storage/hoody-browser/chrome/chrome/linux-136.0.7103.113/chrome-linux64/chrome",
  "browserExecutablePath": "/hoody/storage/hoody-browser/chrome/chrome/linux-136.0.7103.113/chrome-linux64/chrome",
  "fingerprintId": "default",
  "display": ":99",
  "iframe_url": null,
  "browser_id": "0",
  "browser_host": "127.0.0.1",
  "browser_port": 35791,
  "sessionId": "sess-abc123def4",
  "sessionName": "default",
  "timezoneId": "America/New_York",
  "locale": "en-US",
  "geolocation": {
    "latitude": 40.7128,
    "longitude": -74.006,
    "accuracy": 50
  },
  "viewport": {
    "width": 1280,
    "height": 800,
    "deviceScaleFactor": 1,
    "screenWidth": 1280,
    "screenHeight": 800
  },
  "viewportSource": "creation",
  "userAgentString": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
  "browserName": "chromium",
  "browserFullVersion": "136.0.7103.113",
  "operatingSystemName": "Linux",
  "operatingSystemPlatform": "Linux x86_64",
  "operatingSystemVersion": "5.15.0",
  "renderingEngine": "Blink",
  "renderingEngineVersion": "136.0.7103.113",
  "webSocketDebuggerUrl": null,
  "devtoolsHttpUrl": null,
  "devtoolsFrontendUrl": null,
  "extensions": [],
  "useRemoteDebuggingPort": false,
  "remoteDebuggingPort": null,
  "remoteDebuggingAddress": "0.0.0.0",
  "quicDisabled": true,
  "http3Disabled": true,
  "dnsOverHttpsEnabled": true,
  "dnsOverHttpsUrl": "https://cloudflare-dns.com/dns-query",
  "tabs": [
    { "id": 1, "url": "https://example.com" }
  ]
}

{
  "error": "No browser instance for browser_id 5",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "5"
  }
}

Error Code	Title	Description	Resolution
`INSTANCE_NOT_FOUND`	Instance Not Found	No browser instance exists for the specified browser_id	Verify the browser_id value, or create a new instance using /start

`GET /devtools-url`

Returns the Chrome DevTools WebSocket URL, HTTP discovery URL, and frontend URL for the specified browser instance. URLs are populated when the instance was launched with useRemoteDebuggingPort=true and browser=chromium; otherwise they are null.

cURL
SDK

curl -X GET "https://myproj-abc123def4-browser-1.us-east-1.containers.hoody.icu/devtools-url?browser_id=0"

const result = await client.browser.introspection.getDevtoolsUrl({ browser_id: "0" });

Parameters

Name	In	Type	Required	Description
`browser_id`	query	string	Yes	Unique identifier for the browser instance (0-based index)
`start`	query	boolean	No	Controls instance creation behavior. Default: instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally: set to `true` to create an instance. Default: `true`

Response

{
  "webSocketDebuggerUrl": "wss://myproj-abc123def4-cdp-1.us-east-1.containers.hoody.icu/devtools/browser/b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
  "devtoolsHttpUrl": "https://myproj-abc123def4-cdp-1.us-east-1.containers.hoody.icu/json/version",
  "devtoolsFrontendUrl": "https://myproj-abc123def4-cdp-1.us-east-1.containers.hoody.icu"
}

{
  "error": "No browser instance for browser_id 5",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "5"
  }
}

Error Code	Title	Description	Resolution
`INSTANCE_NOT_FOUND`	Instance Not Found	No browser instance exists for the specified browser_id	Verify the browser_id value, or create a new instance using /start

Lifecycle

`GET /shutdown`

Shuts down a specific browser instance.

cURL
SDK

curl -X GET "https://myproj-abc123def4-browser-1.us-east-1.containers.hoody.icu/shutdown?browser_id=0"

const result = await client.browser.introspection.shutdown({ browser_id: "0" });

Parameters

Name	In	Type	Required	Description
`browser_id`	query	string	Yes	Unique identifier for the browser instance (0-based index)

Response

{
  "message": "Instance shutdown successfully"
}

{
  "error": "No browser instance for browser_id 5",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "5"
  }
}

Error Code	Title	Description	Resolution
`INSTANCE_NOT_FOUND`	Instance Not Found	No browser instance exists for the specified browser_id	Verify the browser_id value, or create a new instance using /start

Tab Management

`GET /tabs`

Lists all open tabs in a browser instance.

cURL
SDK

curl -X GET "https://myproj-abc123def4-browser-1.us-east-1.containers.hoody.icu/tabs?browser_id=0"

const result = await client.browser.introspection.listTabs({ browser_id: "0" });

Parameters

Name	In	Type	Required	Description
`browser_id`	query	string	Yes	Unique identifier for the browser instance (0-based index)
`start`	query	boolean	No	Controls instance creation behavior. Default: instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally: set to `true` to create an instance. Default: `true`

Response

[
  { "id": 1, "url": "https://example.com", "isActive": true },
  { "id": 2, "url": "https://docs.example.com", "isActive": false }
]

{
  "error": "No browser instance for browser_id 5",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "5"
  }
}

Error Code	Title	Description	Resolution
`INSTANCE_NOT_FOUND`	Instance Not Found	No browser instance exists for the specified browser_id	Verify the browser_id value, or create a new instance using /start

`POST /tab/close`

Closes a specific tab by its tab ID. If no tabId is provided, closes the active tab (unless it is the last remaining tab).

cURL
SDK

curl -X POST "https://myproj-abc123def4-browser-1.us-east-1.containers.hoody.icu/tab/close?browser_id=0" \
  -H "Content-Type: application/json" \
  -d '{"tabId": 2}'

const result = await client.browser.introspection.closeTab(
  { tabId: 2 },
  { browser_id: "0" }
);

Parameters

Name	In	Type	Required	Description
`browser_id`	query	string	Yes	Unique identifier for the browser instance (0-based index)
`start`	query	boolean	No	Controls instance creation behavior. Default: instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally: set to `true` to create an instance. Default: `true`

Request Body

Name	Type	Required	Description
`tabId`	integer	No	The ID of the tab to close

Response

{
  "closed": 2,
  "remaining": 1
}

{
  "error": "Cannot close the last remaining tab",
  "code": "LAST_TAB",
  "details": {
    "reason": "last_tab"
  }
}

{
  "error": "Tab not found",
  "code": "TAB_NOT_FOUND",
  "details": {
    "tabId": 99
  }
}

Viewport Control

The viewport endpoints never auto-create an instance. If browser_host/browser_port are both omitted and exactly one instance is running, it is selected automatically. With zero instances the request returns 404; with more than one it returns 400.

`GET /viewport`

Returns the instance’s current viewport policy without mutating anything. viewport: null means fixed-viewport emulation is disabled (responsive — the page follows the real window size). source is creation until the first successful POST /viewport, then runtime. converged reports whether every live page currently reflects the policy.

cURL
SDK

curl -X GET "https://myproj-abc123def4-browser-1.us-east-1.containers.hoody.icu/viewport"

const result = await client.browser.introspection.getViewport();

Parameters

Name	In	Type	Required	Description
`browser_host`	query	string	No	Instance host. Optional — must be paired with `browser_port`; when both are omitted the single running instance is selected (`400 AMBIGUOUS_INSTANCE` with more than one).
`browser_port`	query	integer	No	Instance port. Optional — must be paired with `browser_host`.

Response

{
  "viewport": {
    "width": 1280,
    "height": 800
  },
  "source": "creation",
  "tabs": 2,
  "converged": true
}

{
  "error": "Multiple browser instances running; specify browser_host and browser_port",
  "code": "AMBIGUOUS_INSTANCE",
  "details": {
    "reason": "ambiguous_instance"
  }
}

{
  "error": "No browser instance running",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "reason": "no_instance"
  }
}

{
  "error": "Browser instance control process did not respond",
  "code": "PARENT_PROXY_FAILURE",
  "details": {
    "browser_host": "127.0.0.1",
    "browser_port": 35791
  }
}

`POST /viewport`

Mutates the running instance’s viewport policy. The body must contain only viewport (no other keys).

Fixed size: {"viewport": {"width": 1280, "height": 800}} — integers 1..8192, no other keys.
Responsive: {"viewport": null} — the page follows the real window size.

Applies to every currently-open tab; tabs opened later inherit the policy.

curl -X POST "https://myproj-abc123def4-browser-1.us-east-1.containers.hoody.icu/viewport" \
  -H "Content-Type: application/json" \
  -d '{"viewport": {"width": 1280, "height": 800}}'

curl -X POST "https://myproj-abc123def4-browser-1.us-east-1.containers.hoody.icu/viewport" \
  -H "Content-Type: application/json" \
  -d '{"viewport": null}'

const result = await client.browser.introspection.setViewport({
  viewport: { width: 1280, height: 800 }
});

Parameters

Name	In	Type	Required	Description
`browser_host`	query	string	No	Instance host. Optional — must be paired with `browser_port`; when both are omitted the single running instance is selected (`400 AMBIGUOUS_INSTANCE` with more than one).
`browser_port`	query	integer	No	Instance port. Optional — must be paired with `browser_host`.

Request Body

Name	Type	Required	Description
`viewport`	object	Yes	Fixed size `{width, height}` (integers 1..8192, no other keys), or `null` for responsive.

When viewport is an object, it must contain exactly:

Name	Type	Required	Description
`width`	integer	Yes	Viewport width in pixels (1..8192).
`height`	integer	Yes	Viewport height in pixels (1..8192).

Response

{
  "viewport": {
    "width": 1280,
    "height": 800
  },
  "source": "runtime",
  "tabs": 2,
  "converged": true
}

{
  "error": "Invalid viewport: width must be between 1 and 8192",
  "code": "INVALID_VIEWPORT",
  "details": {
    "field": "viewport.width",
    "value": 0
  }
}

{
  "error": "No browser instance running",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "reason": "no_instance"
  }
}

{
  "error": "Instance was created with a fixed viewport; responsive requires recreating it",
  "code": "REQUIRES_RESTART",
  "details": {
    "browser_id": "0",
    "reason": "responsive_requires_restart"
  }
}

{
  "error": "Responsive viewport at runtime is not supported for this browser engine",
  "code": "NOT_SUPPORTED",
  "details": {
    "engine": "firefox"
  }
}

{
  "error": "Viewport policy applied to some tabs; others failed",
  "code": "VIEWPORT_APPLY_INCOMPLETE",
  "details": {
    "failedTabs": [3]
  }
}

Cookies

`GET /cookies`

Returns all cookies for the browser context, optionally filtered by URL.

cURL
SDK

curl -X GET "https://myproj-abc123def4-browser-1.us-east-1.containers.hoody.icu/cookies?browser_id=0"

const result = await client.browser.cookies.get({ browser_id: "0" });

Parameters

Name	In	Type	Required	Description
`browser_id`	query	string	Yes	Unique identifier for the browser instance (0-based index)
`start`	query	boolean	No	Controls instance creation behavior. Default: instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally: set to `true` to create an instance. Default: `true`
`url`	query	string	No	Filter cookies by URL

Response

{
  "cookies": [
    {
      "name": "session_id",
      "value": "s%3Aabc123def4ghi567.SIGNATURE",
      "domain": ".example.com",
      "path": "/",
      "httpOnly": true,
      "secure": true
    },
    {
      "name": "preferences",
      "value": "theme%3Ddark",
      "domain": "example.com",
      "path": "/",
      "httpOnly": false,
      "secure": true
    }
  ]
}

`POST /cookies`

Adds cookies to the browser context. Each cookie requires name, value, and url; domain, path, httpOnly, and secure are optional.

cURL
SDK

curl -X POST "https://myproj-abc123def4-browser-1.us-east-1.containers.hoody.icu/cookies?browser_id=0" \
  -H "Content-Type: application/json" \
  -d '{
    "cookies": [
      {
        "name": "session_id",
        "value": "s%3Aabc123def4ghi567.SIGNATURE",
        "url": "https://example.com",
        "httpOnly": true,
        "secure": true
      }
    ]
  }'

const result = await client.browser.cookies.set(
  {
    cookies: [
      {
        name: "session_id",
        value: "s%3Aabc123def4ghi567.SIGNATURE",
        url: "https://example.com",
        httpOnly: true,
        secure: true
      }
    ]
  },
  { browser_id: "0" }
);

Parameters

Name	In	Type	Required	Description
`browser_id`	query	string	Yes	Unique identifier for the browser instance (0-based index)
`start`	query	boolean	No	Controls instance creation behavior. Default: instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally: set to `true` to create an instance. Default: `true`

Request Body

Name	Type	Required	Description
`cookies`	array	Yes	Cookies to add. Each entry must include `name`, `value`, and `url`; `domain`, `path`, `httpOnly`, and `secure` are optional.

Response

{
  "added": 1
}

`DELETE /cookies`

Removes all cookies from the browser context.

cURL
SDK

curl -X DELETE "https://myproj-abc123def4-browser-1.us-east-1.containers.hoody.icu/cookies?browser_id=0"

const result = await client.browser.cookies.clear({ browser_id: "0" });

Parameters

Name	In	Type	Required	Description
`browser_id`	query	string	Yes	Unique identifier for the browser instance (0-based index)
`start`	query	boolean	No	Controls instance creation behavior. Default: instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally: set to `true` to create an instance. Default: `true`

Response

{
  "cleared": true
}