---
title: "Create a proxy"
method: POST
path: "/proxies"
tags: ["Proxies"]
---

# Create a proxy

`POST /proxies`

Create a new proxy configuration in the resolved project.

## Request body

- ProxyCreateRequest — Configuration for routing traffic through a proxy.
  - `name` string — Readable name of the proxy.
  - `type` 'datacenter' | 'isp' | 'residential' | 'mobile' | 'custom', required — Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp` > `datacenter`.
  - `protocol` 'http' | 'https' — Protocol to use for the proxy connection.
  - `bypass_hosts` string[] — Hostnames that should bypass the parent proxy and connect directly.
  - `config` union — Configuration specific to the selected proxy `type`.
    - DatacenterProxyConfig — Configuration for a datacenter proxy.
      - `country` string — ISO 3166 country code. Defaults to US if not provided.
    - IspProxyConfig — Configuration for an ISP proxy.
      - `country` string — ISO 3166 country code. Defaults to US if not provided.
    - ResidentialProxyConfig — Configuration for residential proxies.
      - `country` string — ISO 3166 country code.
      - `city` string — City name (no spaces, e.g. `sanfrancisco`). If provided, `country` must also be provided.
      - `state` string — Two-letter state code.
      - `zip` string — US ZIP code.
      - `asn` string — Autonomous system number. See https://bgp.potaroo.net/cidr/autnums.html
      - `os` 'windows' | 'macos' | 'android' — Operating system of the residential device.
    - MobileProxyConfig — Configuration for mobile proxies.
      - `country` string — ISO 3166 country code
      - `city` string — Provider city alias. Mobile carrier routing can make observed geo vary.
      - `state` string — US-only state code. Mobile carrier routing can make observed geo vary.
    - CreateCustomProxyConfig — Configuration for a custom proxy (e.g., private proxy server).
      - `host` string, required — Proxy host address or IP.
      - `port` integer, required — Proxy port.
      - `username` string — Username for proxy authentication.
      - `password` string — Password for proxy authentication.
      - `ca_bundle` string — 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.

## Response `201`

Proxy created successfully

- Proxy — Configuration for routing traffic through a proxy.
  - `id` string
  - `name` string — Readable name of the proxy.
  - `type` 'datacenter' | 'isp' | 'residential' | 'mobile' | 'custom', required — Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp` > `datacenter`.
  - `protocol` 'http' | 'https' — Protocol to use for the proxy connection.
  - `bypass_hosts` string[] — Hostnames that should bypass the parent proxy and connect directly.
  - `status` 'available' | 'unavailable' — Current health status of the proxy.
  - `last_checked` string, date-time — Timestamp of the last health check performed on this proxy.
  - `ip_address` string — IP address that the proxy uses when making requests.
  - `config` union — Configuration specific to the selected proxy `type`.
    - DatacenterProxyConfig — Configuration for a datacenter proxy.
      - `country` string — ISO 3166 country code. Defaults to US if not provided.
    - IspProxyConfig — Configuration for an ISP proxy.
      - `country` string — ISO 3166 country code. Defaults to US if not provided.
    - ResidentialProxyConfig — Configuration for residential proxies.
      - `country` string — ISO 3166 country code.
      - `city` string — City name (no spaces, e.g. `sanfrancisco`). If provided, `country` must also be provided.
      - `state` string — Two-letter state code.
      - `zip` string — US ZIP code.
      - `asn` string — Autonomous system number. See https://bgp.potaroo.net/cidr/autnums.html
      - `os` 'windows' | 'macos' | 'android' — Operating system of the residential device.
    - MobileProxyConfig — Configuration for mobile proxies.
      - `country` string — ISO 3166 country code
      - `city` string — Provider city alias. Mobile carrier routing can make observed geo vary.
      - `state` string — US-only state code. Mobile carrier routing can make observed geo vary.
    - CustomProxyConfig — Configuration for a custom proxy (e.g., private proxy server).
      - `host` string, required — Proxy host address or IP.
      - `port` integer, required — Proxy port.
      - `username` string — Username for proxy authentication.
      - `has_password` boolean — Whether the proxy has a password.
      - `has_ca_bundle` boolean — Whether the proxy has a custom CA bundle configured.

## Other responses

- `400` — Bad Request – invalid input
- `401` — Unauthorized – missing or invalid authorization token
- `403` — Forbidden – insufficient permissions or plan
- `500` — Internal Server Error

## Changes

- **2026-08-03** `9e8ce9fcf5e1` — 1 warning
  - the `config/oneOf[subschema #5: Custom]/password` request property's maxLength was set to `4096`
- **2026-07-28** `6cfc6a03c923` — 2 info
  - added the new optional request property `config/oneOf[subschema #5: Custom]/ca_bundle`
  - added the optional property `config/oneOf[subschema #5: Custom]/has_ca_bundle` to the response with the `201` status
- **2026-05-27** `372e4a194eaa` — 6 warning
  - removed the request property `config/oneOf[#/components/schemas/MobileProxyConfig]/asn`
  - removed the request property `config/oneOf[#/components/schemas/MobileProxyConfig]/carrier`
  - removed the request property `config/oneOf[#/components/schemas/MobileProxyConfig]/zip`
  - removed the optional property `config/oneOf[#/components/schemas/MobileProxyConfig]/asn` from the response with the `201` status
  - …2 more

[Change history](https://skmtc.dev/kernel/apis/kernel-api/changes/proxies/post.md)

---

[API](https://skmtc.dev/kernel/apis/kernel-api.md) · [All operations](https://skmtc.dev/kernel/apis/kernel-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kernel/kernel-api/revisions/9e8ce9fcf5e1/schema)