Kernel Proxies API

openapi: 3.2.0
info:
  title: Kernel API Keys Proxies 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: Proxies
  description: Create and manage proxy configurations for routing browser traffic.
paths:
  /proxies:
    post:
      operationId: postProxies
      tags:
      - Proxies
      summary: Create a proxy
      description: Create a new proxy configuration for the caller's organization.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProxyCreateRequest'
      responses:
        '201':
          description: Proxy created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proxy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '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 proxy = await client.proxies.create({ type: 'datacenter' });\n\nconsole.log(proxy.id);"
      - 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)\nproxy = client.proxies.create(\n    type=\"datacenter\",\n)\nprint(proxy.id)"
      - 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\tproxy, err := client.Proxies.New(context.TODO(), kernel.ProxyNewParams{\n\t\tType: kernel.ProxyNewParamsTypeDatacenter,\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", proxy.ID)\n}\n"
    get:
      operationId: getProxies
      tags:
      - Proxies
      summary: List proxies
      description: List proxies owned by the caller's organization.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List of proxies
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Proxy'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '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 proxies = await client.proxies.list();\n\nconsole.log(proxies);"
      - 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)\nproxies = client.proxies.list()\nprint(proxies)"
      - 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\tproxies, err := client.Proxies.List(context.TODO())\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", proxies)\n}\n"
  /proxies/{id}:
    get:
      operationId: getProxiesById
      tags:
      - Proxies
      summary: Get proxy by ID
      description: Retrieve a proxy belonging to the caller's organization by ID.
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Proxy retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proxy'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '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 proxy = await client.proxies.retrieve('id');\n\nconsole.log(proxy.id);"
      - 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)\nproxy = client.proxies.retrieve(\n    \"id\",\n)\nprint(proxy.id)"
      - 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\tproxy, err := client.Proxies.Get(context.TODO(), \"id\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", proxy.ID)\n}\n"
    delete:
      operationId: deleteProxiesById
      tags:
      - Proxies
      summary: Delete proxy by ID
      description: Soft delete a proxy. Sessions referencing it are not modified.
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Proxy deleted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '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\nawait client.proxies.delete('id');"
      - 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)\nclient.proxies.delete(\n    \"id\",\n)"
      - lang: Go
        source: "package main\n\nimport (\n\t\"context\"\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\terr := client.Proxies.Delete(context.TODO(), \"id\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
  /proxies/{id}/check:
    post:
      operationId: postProxiesByIdCheck
      tags:
      - Proxies
      summary: Check proxy health
      description: Run a health check on the proxy to verify it's working. Optionally specify a URL to test reachability against a specific target. For ISP and datacenter proxies, this reliably tests whether the target site is reachable from the proxy's stable exit IP. For residential and mobile proxies, the exit node varies between requests, so this validates proxy configuration and connectivity rather than guaranteeing site-specific reachability.
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProxyCheckRequest'
      responses:
        '200':
          description: Health check completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proxy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '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.proxies.check('id');\n\nconsole.log(response.id);"
      - 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.proxies.check(\n    id=\"id\",\n)\nprint(response.id)"
      - 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.Proxies.Check(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tkernel.ProxyCheckParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.ID)\n}\n"
components:
  schemas:
    Proxy:
      type: object
      description: Configuration for routing traffic through a proxy.
      required:
      - type
      properties:
        id:
          type: string
        name:
          type: string
          description: Readable name of the proxy.
        type:
          type: string
          description: 'Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp` > `datacenter`.

            '
          enum:
          - datacenter
          - isp
          - residential
          - mobile
          - custom
        protocol:
          type: string
          description: Protocol to use for the proxy connection.
          enum:
          - http
          - https
          default: https
        bypass_hosts:
          type: array
          description: Hostnames that should bypass the parent proxy and connect directly.
          items:
            type: string
        status:
          type: string
          description: Current health status of the proxy.
          enum:
          - available
          - unavailable
        last_checked:
          type: string
          format: date-time
          description: Timestamp of the last health check performed on this proxy.
        ip_address:
          type: string
          description: IP address that the proxy uses when making requests.
          example: 192.168.1.1
        config:
          description: Configuration specific to the selected proxy `type`.
          oneOf:
          - $ref: '#/components/schemas/DatacenterProxyConfig'
          - $ref: '#/components/schemas/IspProxyConfig'
          - $ref: '#/components/schemas/ResidentialProxyConfig'
          - $ref: '#/components/schemas/MobileProxyConfig'
          - $ref: '#/components/schemas/CustomProxyConfig'
      discriminator:
        propertyName: type
        mapping:
          datacenter: '#/components/schemas/DatacenterProxyConfig'
          isp: '#/components/schemas/IspProxyConfig'
          residential: '#/components/schemas/ResidentialProxyConfig'
          mobile: '#/components/schemas/MobileProxyConfig'
          custom: '#/components/schemas/CustomProxyConfig'
    ProxyCheckRequest:
      type: object
      description: Optional parameters for the proxy health check.
      properties:
        url:
          type: string
          description: An optional URL to test reachability against. If provided, the proxy check will test connectivity to this URL instead of the default test URLs. Only HTTP and HTTPS schemes are allowed, and the URL must resolve to a public IP address. For ISP and datacenter proxies, the exit IP is stable, so a successful check reliably indicates that subsequent browser sessions will reach the target site with the same IP. For residential and mobile proxies, the exit node changes between requests, so a successful check validates proxy configuration but does not guarantee that a subsequent browser session will use the same exit IP or reach the same site — it is useful for verifying credentials and connectivity, not for predicting site-specific behavior. When provided, the check result does not update the proxy's health status, since a failure may indicate a problem with the target site rather than the proxy itself.
    IspProxyConfig:
      type: object
      description: Configuration for an ISP proxy.
      properties:
        country:
          type: string
          description: ISO 3166 country code. Defaults to US if not provided.
          example: US
    MobileProxyConfig:
      x-hidden: true
      x-deprecated: true
      x-deprecated-reason: Mobile proxies not reliable enough from our proxy provider
      type: object
      description: Configuration for mobile proxies.
      properties:
        country:
          type: string
          description: ISO 3166 country code
          example: US
        city:
          type: string
          description: City name (no spaces, e.g. `sanfrancisco`). If provided, `country` must also be provided.
          example: sanfrancisco
        state:
          type: string
          description: Two-letter state code.
          example: CA
        zip:
          type: string
          description: US ZIP code.
          example: '94107'
        asn:
          type: string
          description: Autonomous system number. See https://bgp.potaroo.net/cidr/autnums.html
          example: AS15169
        carrier:
          type: string
          description: Mobile carrier.
          enum:
          - a1
          - aircel
          - airtel
          - att
          - celcom
          - chinamobile
          - claro
          - comcast
          - cox
          - digi
          - dt
          - docomo
          - dtac
          - etisalat
          - idea
          - kyivstar
          - meo
          - megafon
          - mtn
          - mtnza
          - mts
          - optus
          - orange
          - qwest
          - reliance_jio
          - robi
          - sprint
          - telefonica
          - telstra
          - tmobile
          - tigo
          - tim
          - verizon
          - vimpelcom
          - vodacomza
          - vodafone
          - vivo
          - zain
          - vivabo
          - telenormyanmar
          - kcelljsc
          - swisscom
          - singtel
          - asiacell
          - windit
          - cellc
          - ooredoo
          - drei
          - umobile
          - cableone
          - proximus
          - tele2
          - mobitel
          - o2
          - bouygues
          - free
          - sfr
          - digicel
    CreateCustomProxyConfig:
      type: object
      description: Configuration for a custom proxy (e.g., private proxy server).
      required:
      - host
      - port
      properties:
        host:
          type: string
          description: Proxy host address or IP.
          example: 127.0.0.1
        port:
          type: integer
          description: Proxy port.
          example: 8080
        username:
          type: string
          description: Username for proxy authentication.
          example: user123
        password:
          type: string
          description: Password for proxy authentication.
          example: secret
    ResidentialProxyConfig:
      type: object
      description: Configuration for residential proxies.
      properties:
        country:
          type: string
          description: ISO 3166 country code.
          example: US
        city:
          type: string
          description: City name (no spaces, e.g. `sanfrancisco`). If provided, `country` must also be provided.
          example: sanfrancisco
        state:
          type: string
          description: Two-letter state code.
          example: CA
        zip:
          type: string
          description: US ZIP code.
          example: '94107'
        asn:
          type: string
          description: Autonomous system number. See https://bgp.potaroo.net/cidr/autnums.html
          example: AS15169
        os:
          type: string
          description: Operating system of the residential device.
          deprecated: true
          x-deprecated-reason: os selection not supported by proxy provider
          enum:
          - windows
          - macos
          - android
    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'
    CustomProxyConfig:
      type: object
      description: Configuration for a custom proxy (e.g., private proxy server).
      required:
      - host
      - port
      properties:
        host:
          type: string
          description: Proxy host address or IP.
          example: 127.0.0.1
        port:
          type: integer
          description: Proxy port.
          example: 8080
        username:
          type: string
          description: Username for proxy authentication.
          example: user123
        has_password:
          type: boolean
          description: Whether the proxy has a password.
          example: true
    DatacenterProxyConfig:
      type: object
      description: Configuration for a datacenter proxy.
      properties:
        country:
          type: string
          description: ISO 3166 country code. Defaults to US if not provided.
          example: US
    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
    ProxyCreateRequest:
      type: object
      description: Configuration for routing traffic through a proxy.
      required:
      - type
      properties:
        name:
          type: string
          description: Readable name of the proxy.
        type:
          type: string
          description: 'Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp` > `datacenter`.

            '
          enum:
          - datacenter
          - isp
          - residential
          - mobile
          - custom
        protocol:
          type: string
          description: Protocol to use for the proxy connection.
          enum:
          - http
          - https
          default: https
        bypass_hosts:
          type: array
          description: Hostnames that should bypass the parent proxy and connect directly.
          items:
            type: string
        config:
          description: Configuration specific to the selected proxy `type`.
          oneOf:
          - $ref: '#/components/schemas/DatacenterProxyConfig'
          - $ref: '#/components/schemas/IspProxyConfig'
          - $ref: '#/components/schemas/ResidentialProxyConfig'
          - $ref: '#/components/schemas/MobileProxyConfig'
          - $ref: '#/components/schemas/CreateCustomProxyConfig'
      discriminator:
        propertyName: type
        mapping:
          datacenter: '#/components/schemas/DatacenterProxyConfig'
          isp: '#/components/schemas/IspProxyConfig'
          residential: '#/components/schemas/ResidentialProxyConfig'
          mobile: '#/components/schemas/MobileProxyConfig'
          custom: '#/components/schemas/CustomProxyConfig'
  responses:
    BadRequest:
      description: Bad Request – invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized – missing or invalid authorization token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Unprocessable Entity – request was valid but the operation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden – insufficient permissions or plan
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer