Proxies API

Manage proxies used to route image rendering traffic through your own provider. For setup and rendering examples, see the HTTP proxies guide. Check plans and feature availability if your plan does not include proxies.

Operations

Read operations share 100 requests/minute; write operations share 20 requests/minute, per organization across REST and MCP. Authentication, rate limits, and plan eligibility apply. See the interactive API reference for schemas.

Create a proxy

curl 'https://hcti.io/v1/proxies' \
  --user "$HCTI_API_ID:$HCTI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Screenshot proxy",
    "url": "https://proxy.example.com",
    "port": 8443,
    "disabled": false,
    "authentication": {
      "username": "your-proxy-username",
      "password": "your-proxy-password"
    },
    "bypass_hosts": ["fonts.googleapis.com", "fonts.gstatic.com"]
  }'

Replace the example connection with your provider’s details. A successful request returns 200 OK with the proxy configuration, including its username but never its password.

Authentication fields

These fields belong inside authentication:

Username and password whitespace is preserved exactly. Do not combine retain_password: true with a supplied password, including an empty string; that returns 400.

Response fields

Create, get, and update responses return the following fields. Each entry in a list response has the same shape:

Passwords and the request-only retain_password flag are never returned. The response has a top-level username; it does not have an authentication object.

List and retrieve proxies

curl 'https://hcti.io/v1/proxies?count=10' \
  --user "$HCTI_API_ID:$HCTI_API_KEY"

curl "https://hcti.io/v1/proxies/$PROXY_ID" \
  --user "$HCTI_API_ID:$HCTI_API_KEY"

Lists include disabled proxies and exclude deleted proxies, newest first. Set count from 1 to 100 (default 10) and follow pagination.next_page_start using page_start. See pagination.

Update a proxy

Use POST /v1/proxies/{id} with the same complete request shape as creation. This replaces the proxy configuration. Resend the port, bypass hosts, authentication, and disabled state you want to retain.

For example, to update an authenticated proxy without resending its password, use its existing username and set retain_password: true:

curl "https://hcti.io/v1/proxies/$PROXY_ID" \
  --user "$HCTI_API_ID:$HCTI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Screenshot proxy",
    "url": "https://proxy.example.com",
    "port": 8443,
    "disabled": false,
    "authentication": {
      "username": "your-proxy-username",
      "retain_password": true
    },
    "bypass_hosts": ["fonts.googleapis.com", "fonts.gstatic.com"]
  }'

• Keep the password: Supply the exact existing username with retain_password: true and omit password or set it to null.
• Replace the password or username: Supply both username and password; omit retain_password or set it to false. Retention cannot be used when changing the username.
• Remove authentication: Omit authentication or set it to null.

These rules also apply when disabling a proxy. Omitting just the password does not retain it automatically.

A GET response is not a complete update body. If its username is null, use authentication: null. Otherwise, put the username inside authentication and choose whether to retain or replace the password. Set disabled to the opposite of the response’s enabled value, and send the request fields listed above.

Delete a proxy

curl --request DELETE "https://hcti.io/v1/proxies/$PROXY_ID" \
  --user "$HCTI_API_ID:$HCTI_API_KEY"

Success returns 204 No Content. The proxy can no longer be used for rendering. Repeating deletion of the same proxy succeeds. To temporarily stop new use, update the complete configuration with disabled: true instead.

Use the proxy

Pass the returned id as proxy_id when creating an image. That image operation needs images:create; editing proxy configuration requires the separate management permission above.

MCP

Create tools accept the request object under content; update tools accept id and content. Get/delete take id; list takes count and page_start. For example, these are arguments for create_proxy for a proxy that needs no authentication:

{
  "content": {
    "name": "Screenshot proxy",
    "url": "https://proxy.example.com",
    "port": 8443,
    "disabled": false
  }
}

Approve the appropriate MCP permissions first. The tools reference covers result handling. Avoid putting proxy credentials into chat; use the dashboard or your application’s secret handling when configuring authenticated proxies.

Need help?

Talk to a human. Please email us support@htmlcsstoimage.com with any questions and we’ll gladly help you get started.