Kernel Proxies API

openapi: 3.2.0
info:
  description: Developer tools and cloud infrastructure for AI agents to use web browsers
  title: Kernel Proxies API
  version: 0.1.0
servers:
- description: API Server
  url: https://api.onkernel.com
security:
- bearerAuth: []
tags:
- description: Create and manage proxy configurations for routing browser traffic.
  name: Proxies
paths:
  /proxies:
    get:
      description: List proxies in the resolved project.
      operationId: getProxies
      parameters:
      - description: Limit the number of proxies to return.
        in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
      - description: Offset the number of proxies to return.
        in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          type: integer
      - description: Case-insensitive substring match against proxy name, host, or IP address. IDs match by exact value.
        in: query
        name: query
        required: false
        schema:
          type: string
      - description: Exact-match filter on proxy name using the database collation. In production, matching is case- and accent-insensitive. Names are not required to be unique, so multiple proxies may match.
        in: query
        name: name
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Proxy'
                type: array
          description: List of proxies
          headers:
            X-Has-More:
              description: Whether there are more proxies to fetch.
              schema:
                default: false
                type: boolean
            X-Limit:
              description: Limit the number of proxies to return.
              schema:
                default: 20
                maximum: 100
                minimum: 1
                type: integer
            X-Next-Offset:
              description: The offset where the next page starts. 0 when there are no more results.
              schema:
                nullable: true
                type: integer
            X-Offset:
              description: The offset of proxies to return.
              schema:
                default: 0
                minimum: 0
                type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: List proxies
      tags:
      - Proxies
    post:
      description: Create a new proxy configuration in the resolved project.
      operationId: postProxies
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProxyCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proxy'
          description: Proxy created successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Create a proxy
      tags:
      - Proxies
  /proxies/{id_or_name}:
    delete:
      description: Soft delete a proxy. Session records referencing it are not modified. If egress binding polling is enabled, existing tunnels for active sessions using the proxy are terminated within one polling interval; subsequent connections through the deleted proxy are rejected.
      operationId: deleteProxiesById
      parameters:
      - description: Proxy ID. Name-based addressing is supported only for retrieval.
        in: path
        name: id_or_name
        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'
      security:
      - bearerAuth: []
      summary: Delete proxy by ID
      tags:
      - Proxies
    get:
      description: Retrieve a proxy in the resolved project by ID or exact name using the database collation. IDs take precedence when a value matches both an ID and a name. Proxy names are not unique; an ambiguous name returns a 400 response with code ambiguous_proxy_name.
      operationId: getProxiesByIdOrName
      parameters:
      - in: path
        name: id_or_name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proxy'
          description: Proxy retrieved
        '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'
      security:
      - bearerAuth: []
      summary: Get proxy by ID or name
      tags:
      - Proxies
    patch:
      description: Update a proxy's name. Proxy names are not unique and duplicate names are allowed.
      operationId: patchProxiesById
      parameters:
      - description: Proxy ID. Name-based addressing is supported only for retrieval.
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProxyUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proxy'
          description: Proxy updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Rename proxy by ID
      tags:
      - Proxies
  /proxies/{id_or_name}/check:
    post:
      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 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.
      operationId: postProxiesByIdCheck
      parameters:
      - description: Proxy ID. Name-based addressing is supported only for retrieval.
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProxyCheckRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proxy'
          description: Health check completed
        '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'
      security:
      - bearerAuth: []
      summary: Check proxy health
      tags:
      - Proxies
components:
  schemas:
    ResidentialProxyConfig:
      description: Configuration for residential proxies.
      properties:
        asn:
          description: Autonomous system number. See https://bgp.potaroo.net/cidr/autnums.html
          example: AS15169
          type: string
        city:
          description: City name (no spaces, e.g. `sanfrancisco`). If provided, `country` must also be provided.
          example: sanfrancisco
          type: string
        country:
          description: ISO 3166 country code. If omitted, the proxy uses the global pool without country targeting.
          example: US
          type: string
        os:
          deprecated: true
          description: Operating system of the residential device.
          enum:
          - windows
          - macos
          - android
          type: string
          x-deprecated-reason: os selection not supported by proxy provider
        state:
          description: Two-letter state code.
          example: CA
          type: string
        zip:
          description: US ZIP code.
          example: '94107'
          type: string
      title: Residential
      type: object
    IspProxyConfig:
      description: Configuration for an ISP proxy.
      properties:
        country:
          description: ISO 3166 country code. Supported countries are US, GB, FR, DE, SG, and KR. Defaults to US if not provided.
          example: US
          type: string
      title: ISP
      type: object
    Proxy:
      description: Configuration for routing traffic through a proxy.
      discriminator:
        mapping:
          custom: '#/components/schemas/CustomProxyConfig'
          datacenter: '#/components/schemas/DatacenterProxyConfig'
          isp: '#/components/schemas/IspProxyConfig'
          mobile: '#/components/schemas/MobileProxyConfig'
          residential: '#/components/schemas/ResidentialProxyConfig'
        propertyName: type
      properties:
        bypass_hosts:
          description: Hostnames that should bypass the parent proxy and connect directly.
          items:
            type: string
          type: array
        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'
          x-stainless-override-schema:
            oneOf:
            - $ref: '#/components/schemas/IspProxyConfig'
            - $ref: '#/components/schemas/ResidentialProxyConfig'
            - $ref: '#/components/schemas/MobileProxyConfig'
            - $ref: '#/components/schemas/CustomProxyConfig'
        id:
          type: string
        ip_address:
          description: IP address that the proxy uses when making requests.
          example: 192.168.1.1
          type: string
        last_checked:
          description: Timestamp of the last health check performed on this proxy.
          format: date-time
          type: string
        name:
          description: Readable name of the proxy.
          type: string
        protocol:
          default: https
          description: Protocol to use for the proxy connection.
          enum:
          - http
          - https
          type: string
        status:
          description: Current health status of the proxy.
          enum:
          - available
          - unavailable
          type: string
        type:
          description: 'Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp`. `datacenter` is deprecated; use `isp` instead. Existing datacenter proxies remain supported.

            '
          enum:
          - datacenter
          - isp
          - residential
          - mobile
          - custom
          type: string
          x-stainless-override-schema:
            enum:
            - isp
            - residential
            - mobile
            - custom
            type: string
      required:
      - type
      type: object
    ProxyUpdateRequest:
      properties:
        name:
          description: New proxy name. Proxy names are trimmed and length-checked only; duplicates are allowed because proxies are updated by ID, not by name.
          example: my-renamed-proxy
          maxLength: 255
          minLength: 1
          type: string
      required:
      - name
      type: object
    CreateCustomProxyConfig:
      description: Configuration for a custom proxy (e.g., private proxy server).
      properties:
        ca_bundle:
          description: PEM-encoded CA certificate bundle the proxy re-signs upstream TLS with. Provide when the proxy terminates TLS (MITM) so the browser trusts its certificates. May contain multiple concatenated certificates.
          example: '-----BEGIN CERTIFICATE-----

            MIIB...

            -----END CERTIFICATE-----

            '
          maxLength: 65536
          type: string
        host:
          description: Proxy host address or IP.
          example: 127.0.0.1
          type: string
        password:
          description: Password for proxy authentication.
          example: secret
          maxLength: 4096
          type: string
        port:
          description: Proxy port.
          example: 8080
          type: integer
        username:
          description: Username for proxy authentication.
          example: user123
          type: string
      required:
      - host
      - port
      title: Custom
      type: object
    MobileProxyConfig:
      description: Configuration for mobile proxies.
      properties:
        city:
          description: Provider city alias. Mobile carrier routing can make observed geo vary.
          example: brooklyn
          type: string
        country:
          description: ISO 3166 country code. If omitted, the proxy uses the global pool without country targeting.
          example: US
          type: string
        state:
          description: US-only state code. Mobile carrier routing can make observed geo vary.
          example: NY
          type: string
      title: Mobile
      type: object
    ErrorDetail:
      properties:
        code:
          description: Lower-level error code providing more specific detail
          example: invalid_input
          type: string
        message:
          description: Further detail about the error
          example: Provided version string is not semver compliant
          type: string
      type: object
    ProxyCreateRequest:
      description: Configuration for routing traffic through a proxy.
      discriminator:
        mapping:
          custom: '#/components/schemas/CustomProxyConfig'
          datacenter: '#/components/schemas/DatacenterProxyConfig'
          isp: '#/components/schemas/IspProxyConfig'
          mobile: '#/components/schemas/MobileProxyConfig'
          residential: '#/components/schemas/ResidentialProxyConfig'
        propertyName: type
      properties:
        bypass_hosts:
          description: Hostnames that should bypass the parent proxy and connect directly.
          items:
            type: string
          type: array
        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'
          x-stainless-override-schema:
            oneOf:
            - $ref: '#/components/schemas/IspProxyConfig'
            - $ref: '#/components/schemas/ResidentialProxyConfig'
            - $ref: '#/components/schemas/MobileProxyConfig'
            - $ref: '#/components/schemas/CreateCustomProxyConfig'
        name:
          description: Readable name of the proxy.
          type: string
        protocol:
          default: https
          description: Protocol to use for the proxy connection.
          enum:
          - http
          - https
          type: string
        type:
          description: 'Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp`. `datacenter` is deprecated; use `isp` instead. Datacenter proxy creation remains supported for backward compatibility.

            '
          enum:
          - datacenter
          - isp
          - residential
          - mobile
          - custom
          type: string
          x-stainless-override-schema:
            enum:
            - isp
            - residential
            - mobile
            - custom
            type: string
      required:
      - type
      type: object
    Error:
      properties:
        code:
          description: Application-specific error code (machine-readable)
          example: bad_request
          type: string
        details:
          description: Additional error details (for multiple errors)
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
        inner_error:
          $ref: '#/components/schemas/ErrorDetail'
        message:
          description: Human-readable error description for debugging
          example: 'Missing required field: app_name'
          type: string
      required:
      - code
      - message
      type: object
    CustomProxyConfig:
      description: Configuration for a custom proxy (e.g., private proxy server).
      properties:
        has_ca_bundle:
          description: Whether the proxy has a custom CA bundle configured.
          example: true
          type: boolean
        has_password:
          description: Whether the proxy has a password.
          example: true
          type: boolean
        host:
          description: Proxy host address or IP.
          example: 127.0.0.1
          type: string
        port:
          description: Proxy port.
          example: 8080
          type: integer
        username:
          description: Username for proxy authentication.
          example: user123
          type: string
      required:
      - host
      - port
      title: Custom
      type: object
    DatacenterProxyConfig:
      deprecated: true
      description: Configuration for a deprecated datacenter proxy. Use an ISP proxy instead.
      properties:
        country:
          description: ISO 3166 country code. Defaults to US if not provided.
          example: US
          type: string
      title: Datacenter
      type: object
      x-deprecated-reason: Use an ISP proxy instead.
    ProxyCheckRequest:
      description: Optional parameters for the proxy health check.
      properties:
        url:
          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 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.
          example: https://example.com
          type: string
      type: object
  responses:
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Resource not found
    UnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Unprocessable Entity – request was valid but the operation failed
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Bad Request – invalid input
    InternalError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Internal Server Error
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Forbidden – insufficient permissions or plan
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Unauthorized – missing or invalid authorization token
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
x-service-info:
  categories:
  - browsers
  docs:
    apiReference: https://www.kernel.sh/docs
    homepage: https://www.kernel.sh
    llms: https://api.onkernel.com/llms.txt
x-provenance:
  method: harvested
  publisher: Kernel
  source: https://api.onkernel.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)