---
title: "Update a proxy"
method: POST
path: "/v1/proxies/{id}"
tags: ["Proxies"]
---

# Update a proxy

`POST /v1/proxies/{id}`

## Request

- Base URL: `https://hcti.io`
- URL: `https://hcti.io/v1/proxies/{id}`
- Auth: HTTP basic

Replaces the complete proxy configuration. Omitted optional settings are cleared or reset. Within authentication, an omitted password requires retain_password: true and an unchanged username. Omitted or null authentication removes credentials.

**Rate limit:** 20 requests per minute per organization, shared across all operations in the `proxy:write` group and all API keys belonging to that organization.

## Path parameters

- `id` string, required

## Request body

- CreateOrUpdateProxyRequest: Complete configuration for creating or updating an organization proxy. Updates replace the configuration; omitted optional settings are cleared or reset, except a password retained through authentication.retain_password.
  - `name` string, required: Display name for the proxy, between 3 and 500 characters. Leading and trailing whitespace is removed; the resulting name must contain at least 3 characters.
  - `url` string, uri, required: Absolute HTTP or HTTPS proxy server URL, up to 512 characters, for example https://proxy.example.com. Supply the port and credentials in their separate fields. Paths other than /, query strings, and fragments are not allowed.
  - `port` union: Proxy server port, from 1 to 65535. Omitted or null uses the URL scheme's default port: 80 for HTTP or 443 for HTTPS.
    - integer
    - string, uint16
  - `disabled` boolean: Whether the proxy is disabled. Defaults to false.
  - `authentication` ProxyAuthentication: Proxy credentials. Username is required. Supply a password or retain the existing password on update. Empty strings and whitespace are preserved exactly.
    - `username` string, required: Proxy username, up to 512 characters. May be empty. Whitespace is preserved.
    - `password` string, nullable: Proxy password, up to 484 UTF-8 bytes. Required on create. On update, omitted or null is allowed only with retain_password: true. An empty string is a replacement password. Whitespace is preserved.
    - `retain_password` boolean, nullable: Retain the existing password. Only true retains the password. Omitted, null, or false requires a supplied password, including on updates. Explicit true requires an existing password and unchanged username, and cannot be combined with a supplied password. False requires a password; use an empty string for an empty password, or authentication: null to remove authentication.
  - `bypass_hosts` string[], nullable: Up to 100 hosts that should bypass the proxy. Entries may be hostnames, IP addresses, or absolute URLs; URLs are reduced to their hostnames. Hosts are normalized to lowercase and duplicates removed. Replaces the complete list; omitted, null, or [] clears it.

## Response `200`

OK

- Proxy
  - `id` string, required
  - `name` string, required
  - `url` string, required
  - `port` union
    - integer
    - string, uint16
  - `bypass_hosts` string[], required
  - `username` string, nullable: Configured proxy username, or null when authentication is not configured. An empty string is a valid username. Passwords are never returned.
  - `enabled` boolean: Whether the proxy is enabled.
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `429`: Too Many Requests

## Changes

- **2026-09-14** `d5730c2a58f6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/htmlcsstoimage/apis/html-css-to-image-api/changes/v1/proxies/:id/post.md)

---

[API](https://skmtc.dev/htmlcsstoimage/apis/html-css-to-image-api.md) - [All operations](https://skmtc.dev/htmlcsstoimage/apis/html-css-to-image-api/llms.txt) - [OpenAPI document](https://skmtc.dev/htmlcsstoimage/apis/html-css-to-image-api/revisions/100550373ae1?raw)