Kernel Proxies API
Create and manage proxy configurations for routing browser traffic.
OpenAPI Specification
openapi: 3.1.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:
responses:
InternalError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Forbidden – insufficient permissions or plan
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
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'
BadRequest:
description: Bad Request – invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
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
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
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
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
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
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'
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.
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
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'
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
securitySchemes:
bearerAuth:
type: http
scheme: bearer