Instance Control

Cookies

Manage cookies in the browser context. Use these endpoints to read existing cookies, inject new ones, or clear the entire cookie store.

`GET /cookies`

Returns all cookies for the browser context, optionally filtered by 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.
`url`	query	string	No	Filter cookies by URL

curl -G "https://api.hoody.com/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%3A1a2b3c4d5e6f7g8h9i",
      "domain": ".example.com",
      "path": "/",
      "httpOnly": true,
      "secure": true
    },
    {
      "name": "preferences",
      "value": "theme=dark;lang=en-US",
      "domain": "example.com",
      "path": "/",
      "httpOnly": false,
      "secure": true
    }
  ]
}

`POST /cookies`

Adds cookies to the browser context.

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.

Request Body

Field	Type	Required	Description
`cookies`	array	Yes	List of cookies to add. Each cookie requires `name`, `value`, and `url`. Optional fields: `domain`, `path`, `httpOnly`, `secure`.

curl -X POST "https://api.hoody.com/api/browser/control/cookies?browser_id=0" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cookies": [
      {
        "name": "auth_token",
        "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "url": "https://app.example.com",
        "httpOnly": true,
        "secure": true
      },
      {
        "name": "tracking_id",
        "value": "usr-9f8e7d6c5b4a",
        "url": "https://analytics.example.com"
      }
    ]
  }'

const result = await client.browser.cookies.set({
  browser_id: "0",
  data: {
    cookies: [
      {
        name: "auth_token",
        value: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        url: "https://app.example.com",
        httpOnly: true,
        secure: true
      }
    ]
  }
});

{
  "added": 2
}

`DELETE /cookies`

Removes all cookies from the browser context.

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.

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

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

{
  "cleared": true
}

Instance Introspection

Retrieve runtime metadata and DevTools connection details for an existing browser instance.

`GET /metadata`

Retrieves detailed metadata for an existing browser instance, including session information, browser details, operating system information, viewport and geolocation settings, open tabs list, and the Chrome DevTools WebSocket URL when available.

The webSocketDebuggerUrl field provides the WebSocket endpoint for remote debugging. Use this URL to connect Chrome DevTools, Puppeteer, or Playwright to the browser instance.

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.

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

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

{
  "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": "b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
  "sessionName": "scrape-runner-7",
  "timezoneId": "America/New_York",
  "locale": "en-US",
  "geolocation": { "latitude": 40.7128, "longitude": -74.006, "accuracy": 50 },
  "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": "6.1.0-13-amd64",
  "renderingEngine": "Blink",
  "renderingEngineVersion": "136.0.7103.113",
  "webSocketDebuggerUrl": "wss://abc123-def456-http-9222.containers.hoody.com/devtools/browser/b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
  "devtoolsHttpUrl": "https://abc123-def456-http-9222.containers.hoody.com/json/version",
  "devtoolsFrontendUrl": "https://abc123-def456-http-9222.containers.hoody.com",
  "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://app.example.com/dashboard" },
    { "id": 2, "url": "https://docs.example.com/api" }
  ]
}

{
  "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": 0,
  "sessionId": "c7f8a9b0-2d3e-4f5a-6b7c-8d9e0f1a2b3c",
  "sessionName": "scrape-runner-7",
  "timezoneId": "America/New_York",
  "locale": "en-US",
  "geolocation": { "latitude": 40.7128, "longitude": -74.006, "accuracy": 50 },
  "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": "6.1.0-13-amd64",
  "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://app.example.com/dashboard" }
  ]
}

{
  "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 /devtools-url`

Returns the Chrome DevTools WebSocket URL and HTTP discovery URL for the specified browser instance. The HTTP URL (/json/version) can be used to resolve the WebSocket endpoint 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.

curl -G "https://api.hoody.com/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.com/devtools/browser/b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
  "devtoolsHttpUrl": "https://abc123-def456-http-9222.containers.hoody.com/json/version",
  "devtoolsFrontendUrl": "https://abc123-def456-http-9222.containers.hoody.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 /tabs`

Lists all open tabs in a browser instance.

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.

curl -G "https://api.hoody.com/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://app.example.com/dashboard", "isActive": true },
  { "id": 2, "url": "https://docs.example.com/api", "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

Instance Lifecycle

Shut down a browser instance or close individual tabs within it.

`GET /shutdown`

Shuts down a specific browser instance.

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.com/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

`POST /tab/close`

Closes a specific browser tab by its tab ID. If no tabId is provided, closes the active tab (unless it is the last remaining 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.

Request Body

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

curl -X POST "https://api.hoody.com/api/browser/control/tab/close?browser_id=0" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -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": "LAST_TAB_OR_INVALID_ID",
  "details": {
    "tabId": 1,
    "remainingTabs": 1
  }
}

{
  "error": "Tab or instance not found",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "0",
    "tabId": 99
  }
}