Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/fuomag9/caddy-proxy-manager/llms.txt

Use this file to discover all available pages before exploring further.

The proxy hosts API provides full programmatic control over HTTP/HTTPS reverse proxy entries. You can create, read, update, delete, and toggle hosts without touching the dashboard.

​
Endpoints

MethodPathDescription
GET/api/v1/proxy-hostsList all proxy hosts
POST/api/v1/proxy-hostsCreate a proxy host
GET/api/v1/proxy-hosts/{id}Get a proxy host by ID
PUT/api/v1/proxy-hosts/{id}Update a proxy host
DELETE/api/v1/proxy-hosts/{id}Delete a proxy host
POST/api/v1/proxy-hosts/{id}/enableEnable a proxy host
POST/api/v1/proxy-hosts/{id}/disableDisable a proxy host

​
Create a proxy host

POST /api/v1/proxy-hosts 
curl -X POST https://your-instance:3000/api/v1/proxy-hosts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "domains": ["app.example.com"],
    "upstreams": ["localhost:8080"],
    "sslForced": true,
    "hstsEnabled": true,
    "allowWebsocket": false,
    "preserveHostHeader": false,
    "enabled": true
  }'

​
Request fields

​
name
string
required
Display name for the proxy host.
​
domains
string[]
required
One or more domain names to route. Caddy obtains ACME certificates for each domain automatically.
​
upstreams
string[]
required
One or more upstream addresses. Only http:// and https:// schemes are accepted. Bare host:port is also valid.
​
certificateId
number
ID of a manually imported certificate. Omit to use automatic ACME.
​
accessListId
number
ID of an access list to apply HTTP basic auth.
​
sslForced
boolean
Redirect all HTTP requests to HTTPS.
​
hstsEnabled
boolean
Add the Strict-Transport-Security response header.
​
hstsSubdomains
boolean
Include includeSubDomains in the HSTS header.
​
allowWebsocket
boolean
Enable WebSocket proxying (Connection: Upgrade pass-through).
​
preserveHostHeader
boolean
Pass the original Host header to the upstream instead of the upstream hostname.
​
skipHttpsHostnameValidation
boolean
Skip TLS certificate validation for HTTPS upstreams. Use only with trusted internal services.
​
enabled
boolean
Whether Caddy should serve this host. Defaults to true.
​
redirects
RedirectRule[]
Array of redirect rules. Each entry requires from (path pattern), to (destination path), and status (301, 302, 307, or 308).
​
locationRules
LocationRule[]
Path-based routing rules. Each entry requires path (Caddy path pattern, e.g. /api/*) and upstreams (array of upstream addresses for that path).

​
Response object

{
  "id": 1,
  "name": "My App",
  "domains": ["app.example.com"],
  "upstreams": ["localhost:8080"],
  "certificateId": null,
  "accessListId": null,
  "sslForced": true,
  "hstsEnabled": true,
  "hstsSubdomains": false,
  "allowWebsocket": false,
  "preserveHostHeader": false,
  "skipHttpsHostnameValidation": false,
  "enabled": true,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "redirects": [],
  "locationRules": []
}

​
List proxy hosts

GET /api/v1/proxy-hosts Supports query parameters:
ParameterDescription
searchFilter hosts by name or domain (server-side)
pagePage number for pagination

​
Enable / disable a host

# Enable
curl -X POST https://your-instance:3000/api/v1/proxy-hosts/1/enable \
  -H "Authorization: Bearer YOUR_TOKEN"

# Disable
curl -X POST https://your-instance:3000/api/v1/proxy-hosts/1/disable \
  -H "Authorization: Bearer YOUR_TOKEN"
Disabling a host removes it from the Caddy configuration without deleting it from the database.

Build docs developers (and LLMs) love

Get started for freeTalk to us