{
  "openapi": "3.0.3",
  "info": {
    "title": "camofox-browser",
    "version": "1.6.0",
    "description": "Anti-detection browser automation server for AI agents. Accessibility snapshots, element refs, session isolation, cookie import, proxy rotation, and structured logs.",
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "contact": {
      "name": "Jo Inc",
      "url": "https://askjo.ai",
      "email": "oss@askjo.ai"
    }
  },
  "servers": [
    {
      "url": "http://localhost:9377",
      "description": "Local development"
    }
  ],
  "tags": [
    {
      "name": "System",
      "description": "Server health, metrics, and status."
    },
    {
      "name": "Tabs",
      "description": "Create, list, inspect, and destroy browser tabs."
    },
    {
      "name": "Navigation",
      "description": "Navigate tabs to URLs or via search macros."
    },
    {
      "name": "Interaction",
      "description": "Click, type, scroll, press keys, evaluate JS."
    },
    {
      "name": "Content",
      "description": "Accessibility snapshots, screenshots, links, images, downloads."
    },
    {
      "name": "Sessions",
      "description": "Per-user session state: cookies, teardown."
    },
    {
      "name": "Browser",
      "description": "Global browser lifecycle (start/stop)."
    },
    {
      "name": "Legacy",
      "description": "OpenClaw-compatible endpoints (deprecated)."
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer token matching CAMOFOX_API_KEY."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  },
  "paths": {
    "/sessions/{userId}/cookies": {
      "post": {
        "tags": [
          "Sessions"
        ],
        "summary": "Import cookies into a user session",
        "description": "Import cookies for authenticated browsing. Requires BearerAuth in production.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Session owner identifier."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "cookies"
                ],
                "properties": {
                  "cookies": {
                    "type": "array",
                    "maxItems": 500,
                    "items": {
                      "type": "object",
                      "required": [
                        "name",
                        "value",
                        "domain"
                      ],
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "value": {
                          "type": "string"
                        },
                        "domain": {
                          "type": "string"
                        },
                        "path": {
                          "type": "string"
                        },
                        "expires": {
                          "type": "number"
                        },
                        "httpOnly": {
                          "type": "boolean"
                        },
                        "secure": {
                          "type": "boolean"
                        },
                        "sameSite": {
                          "type": "string",
                          "enum": [
                            "Strict",
                            "Lax",
                            "None"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cookies imported.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "userId": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid cookie data.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Health check",
        "description": "Detailed health with tab/session counts and failure tracking.",
        "responses": {
          "200": {
            "description": "Healthy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "engine": {
                      "type": "string"
                    },
                    "browserConnected": {
                      "type": "boolean"
                    },
                    "browserRunning": {
                      "type": "boolean"
                    },
                    "activeTabs": {
                      "type": "integer"
                    },
                    "activeSessions": {
                      "type": "integer"
                    },
                    "consecutiveFailures": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Unhealthy or recovering.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "recovering": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/metrics": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Prometheus metrics",
        "description": "Returns Prometheus text exposition format. Requires PROMETHEUS_ENABLED=1.",
        "responses": {
          "200": {
            "description": "Prometheus metrics.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Metrics disabled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs": {
      "post": {
        "tags": [
          "Tabs"
        ],
        "summary": "Create a new tab",
        "description": "Creates a tab in the given session. Optionally navigates to an initial URL.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userId",
                  "sessionKey"
                ],
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "Session owner."
                  },
                  "sessionKey": {
                    "type": "string",
                    "description": "Tab group identifier."
                  },
                  "listItemId": {
                    "type": "string",
                    "description": "Legacy alias for sessionKey."
                  },
                  "url": {
                    "type": "string",
                    "description": "Optional initial URL."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tab created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tabId": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing required fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Tab limit reached.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Tabs"
        ],
        "summary": "List open tabs",
        "description": "Returns all tabs for a given userId.",
        "parameters": [
          {
            "name": "userId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by session owner."
          }
        ],
        "responses": {
          "200": {
            "description": "Tab list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "running": {
                      "type": "boolean"
                    },
                    "tabs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tabId": {
                            "type": "string"
                          },
                          "targetId": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "listItemId": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/navigate": {
      "post": {
        "tags": [
          "Navigation"
        ],
        "summary": "Navigate a tab to a URL or macro",
        "description": "Navigate to a URL or expand a search macro. Auto-creates tab if not found.",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userId"
                ],
                "properties": {
                  "userId": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  },
                  "macro": {
                    "type": "string",
                    "description": "Search macro (e.g. @google_search)."
                  },
                  "query": {
                    "type": "string",
                    "description": "Search query for macro."
                  },
                  "sessionKey": {
                    "type": "string"
                  },
                  "listItemId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Navigation result with snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/snapshot": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "Accessibility snapshot",
        "description": "Returns accessibility tree with element refs. Supports pagination via offset.",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "text",
                "json"
              ],
              "default": "text"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Character offset for paginated retrieval."
          },
          {
            "name": "includeScreenshot",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "snapshot": {
                      "type": "string"
                    },
                    "refsCount": {
                      "type": "integer"
                    },
                    "truncated": {
                      "type": "boolean"
                    },
                    "totalChars": {
                      "type": "integer"
                    },
                    "hasMore": {
                      "type": "boolean"
                    },
                    "nextOffset": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/wait": {
      "post": {
        "tags": [
          "Interaction"
        ],
        "summary": "Wait for a selector or timeout",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userId"
                ],
                "properties": {
                  "userId": {
                    "type": "string"
                  },
                  "selector": {
                    "type": "string"
                  },
                  "timeout": {
                    "type": "integer",
                    "description": "Max wait in ms."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wait completed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/click": {
      "post": {
        "tags": [
          "Interaction"
        ],
        "summary": "Click an element",
        "description": "Click by element ref, CSS selector, or coordinates.",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userId"
                ],
                "properties": {
                  "userId": {
                    "type": "string"
                  },
                  "ref": {
                    "type": "string",
                    "description": "Element ref ID (e.g. \"e3\")."
                  },
                  "selector": {
                    "type": "string",
                    "description": "CSS selector fallback."
                  },
                  "doubleClick": {
                    "type": "boolean"
                  },
                  "coordinates": {
                    "type": "object",
                    "properties": {
                      "x": {
                        "type": "number"
                      },
                      "y": {
                        "type": "number"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Click result with optional post-action snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/type": {
      "post": {
        "tags": [
          "Interaction"
        ],
        "summary": "Type text into an element",
        "description": "Types text into a focused element or a specific ref/selector.",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userId",
                  "text"
                ],
                "properties": {
                  "userId": {
                    "type": "string"
                  },
                  "ref": {
                    "type": "string"
                  },
                  "selector": {
                    "type": "string"
                  },
                  "text": {
                    "type": "string"
                  },
                  "clear": {
                    "type": "boolean",
                    "description": "Clear field before typing."
                  },
                  "submit": {
                    "type": "boolean",
                    "description": "Press Enter after typing."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Type result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/press": {
      "post": {
        "tags": [
          "Interaction"
        ],
        "summary": "Press a keyboard key",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userId",
                  "key"
                ],
                "properties": {
                  "userId": {
                    "type": "string"
                  },
                  "key": {
                    "type": "string",
                    "description": "Key name (e.g. \"Enter\", \"Escape\", \"Tab\")."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Key pressed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/scroll": {
      "post": {
        "tags": [
          "Interaction"
        ],
        "summary": "Scroll the page",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userId"
                ],
                "properties": {
                  "userId": {
                    "type": "string"
                  },
                  "direction": {
                    "type": "string",
                    "description": "\"up\" or \"down\" (default \"down\")."
                  },
                  "amount": {
                    "type": "integer",
                    "description": "Pixels to scroll."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scroll result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/back": {
      "post": {
        "tags": [
          "Navigation"
        ],
        "summary": "Go back",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userId"
                ],
                "properties": {
                  "userId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Navigated back.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/forward": {
      "post": {
        "tags": [
          "Navigation"
        ],
        "summary": "Go forward",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userId"
                ],
                "properties": {
                  "userId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Navigated forward.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/refresh": {
      "post": {
        "tags": [
          "Navigation"
        ],
        "summary": "Refresh page",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userId"
                ],
                "properties": {
                  "userId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Page refreshed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/links": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "Extract page links",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Links extracted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "text": {
                            "type": "string"
                          },
                          "href": {
                            "type": "string"
                          },
                          "ref": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/downloads": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "List tab downloads",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Downloads list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "downloads": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "filename": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "state": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/images": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "Extract page images",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Images extracted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "images": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "src": {
                            "type": "string"
                          },
                          "alt": {
                            "type": "string"
                          },
                          "width": {
                            "type": "integer"
                          },
                          "height": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/screenshot": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "Take a screenshot",
        "description": "Returns a base64-encoded PNG screenshot.",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Screenshot.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "screenshot": {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "string"
                        },
                        "mimeType": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/stats": {
      "get": {
        "tags": [
          "Tabs"
        ],
        "summary": "Tab statistics",
        "description": "Returns tab metadata including URL, tool call count, visited URLs, download/failure counts.",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tab stats.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tabId": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "toolCalls": {
                      "type": "integer"
                    },
                    "visitedUrls": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "downloadCount": {
                      "type": "integer"
                    },
                    "consecutiveFailures": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}/evaluate": {
      "post": {
        "tags": [
          "Interaction"
        ],
        "summary": "Evaluate JavaScript in tab",
        "description": "Runs arbitrary JS in the page context and returns the result.",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userId",
                  "expression"
                ],
                "properties": {
                  "userId": {
                    "type": "string"
                  },
                  "expression": {
                    "type": "string",
                    "description": "JavaScript expression to evaluate."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Evaluation result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "result": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/{tabId}": {
      "delete": {
        "tags": [
          "Tabs"
        ],
        "summary": "Close a tab",
        "parameters": [
          {
            "name": "tabId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tab closed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tabs/group/{listItemId}": {
      "delete": {
        "tags": [
          "Tabs"
        ],
        "summary": "Close all tabs in a group",
        "parameters": [
          {
            "name": "listItemId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Group closed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "closed": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Session not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sessions/{userId}": {
      "delete": {
        "tags": [
          "Sessions"
        ],
        "summary": "Destroy a user session",
        "description": "Closes all tabs and cleans up state for the given userId.",
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Session destroyed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "closed": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Session not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Server status",
        "description": "Returns basic server liveness and browser state.",
        "responses": {
          "200": {
            "description": "Server status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "enabled": {
                      "type": "boolean"
                    },
                    "running": {
                      "type": "boolean"
                    },
                    "engine": {
                      "type": "string"
                    },
                    "browserConnected": {
                      "type": "boolean"
                    },
                    "browserRunning": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/tabs/open": {
      "post": {
        "tags": [
          "Legacy"
        ],
        "summary": "Open tab (OpenClaw format)",
        "deprecated": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userId",
                  "url"
                ],
                "properties": {
                  "userId": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  },
                  "listItemId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tab opened.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/start": {
      "post": {
        "tags": [
          "Browser"
        ],
        "summary": "Start browser",
        "description": "Ensures the browser process is running. Idempotent.",
        "responses": {
          "200": {
            "description": "Browser started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "profile": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Launch failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/stop": {
      "post": {
        "tags": [
          "Browser"
        ],
        "summary": "Stop browser",
        "description": "Stops the browser and closes all sessions. Requires x-admin-key header.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Browser stopped.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "stopped": {
                      "type": "boolean"
                    },
                    "profile": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/navigate": {
      "post": {
        "tags": [
          "Legacy"
        ],
        "summary": "Navigate (OpenClaw format)",
        "description": "Navigate with targetId in body instead of path param.",
        "deprecated": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userId",
                  "url"
                ],
                "properties": {
                  "userId": {
                    "type": "string"
                  },
                  "targetId": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Navigation result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/snapshot": {
      "get": {
        "tags": [
          "Legacy"
        ],
        "summary": "Snapshot (OpenClaw format)",
        "description": "Snapshot with targetId/userId as query params.",
        "deprecated": true,
        "parameters": [
          {
            "name": "targetId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "includeScreenshot",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/act": {
      "post": {
        "tags": [
          "Legacy"
        ],
        "summary": "Combined action (OpenClaw format)",
        "description": "Routes to click/type/scroll/press/etc based on \"kind\" parameter.",
        "deprecated": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userId",
                  "kind"
                ],
                "properties": {
                  "userId": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "description": "Action kind: click, type, scroll, press, key, select_option, drag, hover, screenshot, wait, back, forward."
                  },
                  "targetId": {
                    "type": "string"
                  },
                  "ref": {
                    "type": "string"
                  },
                  "selector": {
                    "type": "string"
                  },
                  "text": {
                    "type": "string"
                  },
                  "key": {
                    "type": "string"
                  },
                  "direction": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Action result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Tab not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  }
}