# Instance Control

**Page:** api/browser/control

[Download Raw Markdown](./api/browser/control.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## 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` |



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


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


Returned when the browser is launched with `useRemoteDebuggingPort=true`.

```json
{
  "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).

```json
{
  "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"
    }
  ]
}
```


```json
{
  "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 |




The `webSocketDebuggerUrl` field is only populated when the browser is launched with `useRemoteDebuggingPort=true` and `browser=chromium`. Otherwise the field is `null`. Use this URL to connect Chrome DevTools, Puppeteer, or Playwright to the instance.


### `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` |



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


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


```json
{
  "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"
}
```


```json
{
  "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 |




These URLs are populated only when the instance is launched with `useRemoteDebuggingPort=true` and `browser=chromium`. In all other configurations the response fields are `null`. The DevTools URL grants full control over the browser; only expose it to trusted clients in secure environments.


### `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` |



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


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


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


```json
{
  "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 |



```bash
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}'
```


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


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


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


```json
{
  "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) |



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


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


```json
{
  "message": "Instance shutdown successfully"
}
```


```json
{
  "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 |



```bash
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"
```


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


```json
{
  "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. |



```bash
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
      }
    ]
  }'
```


```javascript
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
      }
    ]
  }
});
```


```json
{
  "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` |



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


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


```json
{
  "cleared": true
}
```