openapi: 3.1.0
info:
  title: Kernel API Keys Browser Playwright API
  description: Developer tools and cloud infrastructure for AI agents to use web browsers
  version: 0.1.0
servers:
- url: https://api.onkernel.com
  description: API Server
security:
- bearerAuth: []
tags:
- name: Browser Playwright
  description: Execute Playwright code against the browser instance.
paths:
  /browsers/{id}/playwright/execute:
    post:
      summary: Execute Playwright/TypeScript code against the browser
      description: 'Execute arbitrary Playwright code in a fresh execution context against the browser.

        The code runs in the same VM as the browser, minimizing latency and maximizing throughput.

        It has access to ''page'', ''context'', and ''browser'' variables.

        It can `return` a value, and this value is returned in the response.

        '
      operationId: executePlaywrightCode
      tags:
      - Browser Playwright
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Browser session ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecutePlaywrightRequest'
      responses:
        '200':
          description: Code executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutePlaywrightResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
      - lang: JavaScript
        source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n  apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.browsers.playwright.execute('id', { code: 'code' });\n\nconsole.log(response.success);"
      - lang: Python
        source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n    api_key=os.environ.get(\"KERNEL_API_KEY\"),  # This is the default and can be omitted\n)\nresponse = client.browsers.playwright.execute(\n    id=\"id\",\n    code=\"code\",\n)\nprint(response.success)"
      - lang: Go
        source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Browsers.Playwright.Execute(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tkernel.BrowserPlaywrightExecuteParams{\n\t\t\tCode: \"code\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Success)\n}\n"
components:
  responses:
    InternalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad Request – invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ErrorDetail:
      type: object
      properties:
        code:
          type: string
          description: Lower-level error code providing more specific detail
          example: invalid_input
        message:
          type: string
          description: Further detail about the error
          example: Provided version string is not semver compliant
    ExecutePlaywrightRequest:
      type: object
      description: Request to execute Playwright code
      required:
      - code
      properties:
        code:
          type: string
          description: 'TypeScript/JavaScript code to execute. The code has access to ''page'', ''context'', and ''browser'' variables.

            It runs within a function, so you can use a return statement at the end to return a value.

            This value is returned as the `result` property in the response.

            Example: "await page.goto(''https://example.com''); return await page.title();"

            '
        timeout_sec:
          type: integer
          description: Maximum execution time in seconds. Default is 60.
          default: 60
          minimum: 1
          maximum: 300
      additionalProperties: false
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Application-specific error code (machine-readable)
          example: bad_request
        message:
          type: string
          description: Human-readable error description for debugging
          example: 'Missing required field: app_name'
        details:
          type: array
          description: Additional error details (for multiple errors)
          items:
            $ref: '#/components/schemas/ErrorDetail'
        inner_error:
          $ref: '#/components/schemas/ErrorDetail'
    ExecutePlaywrightResult:
      type: object
      description: Result of Playwright code execution
      required:
      - success
      properties:
        success:
          type: boolean
          description: Whether the code executed successfully
        result:
          description: The value returned by the code (if any)
        error:
          type: string
          description: Error message if execution failed
        stdout:
          type: string
          description: Standard output from the execution
        stderr:
          type: string
          description: Standard error from the execution
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer