Instance Control

Introspection & Control

The endpoints in this section let you inspect browser instance metadata, discover remote debugging endpoints, manage tabs, and shut down running instances. All endpoints address a specific instance via the browser_id query parameter (a 0-based index).

`GET /api/browser/control/metadata`

Retrieve detailed metadata for a running browser instance, including session information, browser/OS details, viewport settings, the list of open tabs, and the Chrome DevTools WebSocket URL (when remote debugging is enabled).

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 mode: 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`

curl -G https://api.hoody.icu/api/browser/control/metadata \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "browser_id=0"

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

Returned when the browser is launched with useRemoteDebuggingPort=true.

{
  "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": ":0",
  "browser_id": "0",
  "browser_host": "0.0.0.0",
  "browser_port": 35791,
  "sessionId": "s_8f3a9b2c1d4e",
  "sessionName": "Default Session",
  "timezoneId": "America/New_York",
  "locale": "en-US",
  "geolocation": {
    "latitude": 40.7128,
    "longitude": -74.006,
    "accuracy": 10
  },
  "viewport": {
    "width": 1280,
    "height": 720,
    "deviceScaleFactor": 1,
    "screenWidth": 1920,
    "screenHeight": 1080
  },
  "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",
  "operatingSystemVersion": "5.15.0-105-generic",
  "renderingEngine": "Blink",
  "renderingEngineVersion": "136.0.7103.113",
  "webSocketDebuggerUrl": "wss://abc123-def456-http-9222.containers.hoody.icu/devtools/browser/b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
  "devtoolsHttpUrl": "https://abc123-def456-http-9222.containers.hoody.icu/json/version",
  "devtoolsFrontendUrl": "https://abc123-def456-http-9222.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"
    }
  ]
}

Returned when the browser uses pipe transport (the default behavior).

{
  "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": ":0",
  "browser_id": "0",
  "browser_host": "0.0.0.0",
  "browser_port": 35791,
  "sessionId": "s_8f3a9b2c1d4e",
  "sessionName": "Default Session",
  "timezoneId": "America/New_York",
  "locale": "en-US",
  "geolocation": {
    "latitude": 40.7128,
    "longitude": -74.006,
    "accuracy": 10
  },
  "viewport": {
    "width": 1280,
    "height": 720,
    "deviceScaleFactor": 1,
    "screenWidth": 1920,
    "screenHeight": 1080
  },
  "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",
  "operatingSystemVersion": "5.15.0-105-generic",
  "renderingEngine": "Blink",
  "renderingEngineVersion": "136.0.7103.113",
  "webSocketDebuggerUrl": null,
  "devtoolsHttpUrl": null,
  "devtoolsFrontendUrl": null,
  "extensions": [],
  "useRemoteDebuggingPort": false,
  "remoteDebuggingPort": null,
  "remoteDebuggingAddress": null,
  "quicDisabled": true,
  "http3Disabled": true,
  "dnsOverHttpsEnabled": true,
  "dnsOverHttpsUrl": "https://cloudflare-dns.com/dns-query",
  "tabs": [
    {
      "id": 1,
      "url": "https://example.com"
    }
  ]
}

{
  "error": "Instance not found",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "0"
  }
}

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 /api/browser/control/devtools-url`

Return the Chrome DevTools WebSocket URL and the HTTP discovery URL (/json/version) for the specified browser instance. The HTTP endpoint can be used to resolve the WebSocket URL automatically.

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 mode: 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`

curl -G https://api.hoody.icu/api/browser/control/devtools-url \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "browser_id=0"

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

{
  "webSocketDebuggerUrl": "wss://abc123-def456-http-9222.containers.hoody.icu/devtools/browser/b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
  "devtoolsHttpUrl": "https://abc123-def456-http-9222.containers.hoody.icu/json/version",
  "devtoolsFrontendUrl": "https://abc123-def456-http-9222.containers.hoody.icu"
}

{
  "error": "Instance not found",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "0"
  }
}

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 /api/browser/control/tabs`

List all open tabs in a browser instance. Each tab includes its identifier, current URL, and whether it is the active tab.

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 mode: 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`

curl -G https://api.hoody.icu/api/browser/control/tabs \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "browser_id=0"

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

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

{
  "error": "Instance not found",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "0"
  }
}

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 /api/browser/control/tab/close`

Close a specific browser tab by its tab ID. If no tabId is provided, the active tab is closed (unless it is the last remaining tab, in which case the request fails).

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 mode: 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

curl -X POST https://api.hoody.icu/api/browser/control/tab/close \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -G --data-urlencode "browser_id=0" \
  -d '{"tabId": 2}'

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

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

{
  "error": "Cannot close the last tab or invalid tab ID",
  "code": "CANNOT_CLOSE_LAST_TAB",
  "details": {
    "tabId": 1
  }
}

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

`GET /api/browser/control/shutdown`

Shut down a specific browser instance and release its resources. The instance must be restarted before it can be used again.

Parameters

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

curl -G https://api.hoody.icu/api/browser/control/shutdown \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "browser_id=0"

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

{
  "message": "Instance shutdown successfully"
}

{
  "error": "Instance not found",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "0"
  }
}

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

Browser State

The endpoints in this section manage the cookie store for a browser context: reading, writing, and clearing cookies. Cookies are scoped to the browser context, so all tabs in an instance share the same cookie jar.

`GET /api/browser/control/cookies`

Return all cookies for the browser context. Optionally filter the result to cookies associated with a specific URL.

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 mode: 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

curl -G https://api.hoody.icu/api/browser/control/cookies \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "browser_id=0" \
  --data-urlencode "url=https://example.com"

const result = await client.browser.cookies.get({
  browser_id: "0",
  url: "https://example.com"
});

{
  "cookies": [
    {
      "name": "session_id",
      "value": "s%3Aabc123def456",
      "domain": ".example.com",
      "path": "/",
      "httpOnly": true,
      "secure": true
    },
    {
      "name": "locale",
      "value": "en-US",
      "domain": ".example.com",
      "path": "/",
      "httpOnly": false,
      "secure": true
    }
  ]
}

`POST /api/browser/control/cookies`

Add one or more cookies to the browser context. Each cookie requires a name, value, and url; the url field is used to derive the cookie’s domain and secure flag when not provided explicitly.

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 mode: 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	List of cookies to add to the browser context. Each entry requires `name`, `value`, and `url`; `domain`, `path`, `httpOnly`, and `secure` are optional.

curl -X POST https://api.hoody.icu/api/browser/control/cookies \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -G --data-urlencode "browser_id=0" \
  -d '{
    "cookies": [
      {
        "name": "session_id",
        "value": "s%3Aabc123def456",
        "url": "https://example.com",
        "domain": ".example.com",
        "path": "/",
        "httpOnly": true,
        "secure": true
      },
      {
        "name": "locale",
        "value": "en-US",
        "url": "https://example.com",
        "domain": ".example.com",
        "path": "/",
        "httpOnly": false,
        "secure": true
      }
    ]
  }'

const result = await client.browser.cookies.set({
  browser_id: "0",
  data: {
    cookies: [
      {
        name: "session_id",
        value: "s%3Aabc123def456",
        url: "https://example.com",
        domain: ".example.com",
        path: "/",
        httpOnly: true,
        secure: true
      },
      {
        name: "locale",
        value: "en-US",
        url: "https://example.com",
        domain: ".example.com",
        path: "/",
        httpOnly: false,
        secure: true
      }
    ]
  }
});

{
  "added": 2
}

`DELETE /api/browser/control/cookies`

Remove all cookies from the browser context. The cookie jar is fully emptied regardless of domain or path.

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 mode: 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`

curl -X DELETE https://api.hoody.icu/api/browser/control/cookies \
  -H "Authorization: Bearer <token>" \
  -G --data-urlencode "browser_id=0"

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

{
  "cleared": true
}