Using the Caddy Admin API
Caddy has two configuration surfaces. The Caddyfile is the human surface: a small, forgiving text format that the server adapts into JSON before it runs anything. The admin API is the machine surface: a REST interface over that very same JSON, published by the running server on a local HTTP endpoint. Most people meet it for the first time when a deployment script needs to add a site without restarting the server. By the end of this page you will be able to read the configuration a running server is actually using, replace it atomically, change one small part of it without touching the rest, and coordinate several writers so that they cannot silently overwrite each other.
Every Caddy process starts a small HTTP server that exists only to administer that process. It listens on localhost:2019 by default, is bound to the loopback interface, and is not reachable from the network unless you deliberately change that.
The endpoint speaks plain HTTP with JSON bodies. It is not a separate daemon, not a plugin, and not optional in the usual sense: it is part of the server process, so it starts and stops with it. Because the API is how caddy reload pushes a new configuration into an already-running server, disabling the endpoint also disables reload.
The default address can be changed with the CADDY_ADMIN environment variable. A value in the configuration file always wins over the environment variable, and the environment variable always wins over the compiled-in default.
The admin global option controls the endpoint. The default is equivalent to admin localhost:2019.
{
admin localhost:2019
}
The endpoint carries the authority to replace the entire configuration of the process, so exposing it is a decision that deserves scrutiny. There are three shapes worth knowing.
Loopback, the default. Only processes on the same machine can reach it. This is the right choice for almost every deployment, because a deployment script can always run on the host.
A unix socket. Access is then controlled by file permissions rather than by the network, which removes the network entirely from the trust question.
{
admin unix//run/caddy-admin.sock
}
The double slash is intentional: it is the way to say “this is a path, not a host and port”. The process user must be able to bind that path, so it belongs in a directory the service account owns, for example a RuntimeDirectory created by the systemd unit. Creating an empty file at the path is not enough, because Caddy has to bind the socket itself.
A routable address. This is possible and dangerous.
{
admin :2020
}
A wildcard interface means the Host header is not validated, and anyone who can reach the port can take over the server. If you must do this, constrain it with origins and turn on enforce_origin.
{
admin :2020 {
origins https://ops.example.com
enforce_origin
}
}
origins lists the origins permitted to connect. enforce_origin forces the Origin request header to be checked against that list and enables the CORS preflight that goes with it. The default is chosen sensibly: for a loopback address the allowed origins are localhost, ::1 and 127.0.0.1 joined with the listen port, and for any other address the origin is the listen address itself.
Turning the endpoint off entirely is possible and has a real cost.
{
admin off
}
With the endpoint off, the only way to change configuration is to stop the server and start it again, which means downtime. caddy reload fails, because reload is implemented as an API call.
The simplest read is the whole configuration.
curl -s http://localhost:2019/config/ | jq
The response is the native JSON that Caddy is running right now, including everything implied by the Caddyfile: the routes the adapter generated, the TLS policies, the log definitions. Reading this is the fastest way to answer the question “what is the server actually doing”, because it shows the result of the adapter rather than your intention.
Any subpath of the configuration can be read the same way, and the path is the same one you would use to write to it.
# The listener addresses of one HTTP server
curl -s http://localhost:2019/config/apps/http/servers/srv0/listen | jq
# The upstreams of one reverse proxy handler
curl -s http://localhost:2019/config/apps/http/servers/srv0/routes/0/handle/0/upstreams | jq
Two other reads are worth knowing. GET /id returns the identifier of the running server, which is useful in logs and in scripts that need to confirm they are talking to the instance they think they are. GET /reverse_proxy/upstreams returns the live state of the proxy pool as a JSON array.
curl -s http://localhost:2019/reverse_proxy/upstreams | jq
[
{ "address": "10.0.1.1:80", "num_requests": 4, "fails": 2 },
{ "address": "10.0.1.2:80", "num_requests": 5, "fails": 4 },
{ "address": "10.0.1.3:80", "num_requests": 3, "fails": 3 }
]
num_requests counts the requests currently being handled by that upstream, and fails counts the failures remembered by the passive health checker. Together with the max_fails and unhealthy_request_count settings of the handler, they tell you whether a backend is healthy. Reading this endpoint is a cheap health probe for the proxy layer specifically.
POST /load sets the active configuration. The request body is the new configuration, and the Content-Type header tells Caddy how to interpret it.
curl "http://localhost:2019/load" \
-H "Content-Type: application/json" \
--data-binary @caddy.json
To send a Caddyfile instead, use the matching content type, and use --data-binary rather than -d, because curl -d collapses the newlines that the Caddyfile parser depends on.
curl "http://localhost:2019/load" \
-H "Content-Type: text/caddyfile" \
--data-binary @Caddyfile
The request blocks until the reload has finished or failed. Three properties make this safe to use in production.
It is atomic. The new configuration is provisioned and started before the old one is retired. If anything fails, the old configuration is rolled back into place and the server keeps serving. There is no window in which neither configuration is live.
It has no downtime. In-flight requests finish on the old configuration while new requests arrive on the new one.
It is idempotent. If the new configuration is identical to the current one, nothing happens. To force a reload anyway, which is useful when you have replaced a certificate file on disk, add the header Cache-Control: must-revalidate.
curl "http://localhost:2019/load" \
-H "Content-Type: text/caddyfile" \
-H "Cache-Control: must-revalidate" \
--data-binary @Caddyfile
A successful response has an empty body. If the adapter produced warnings, the body instead contains a warnings array. If the configuration could not be adapted or loaded, the status is 400 and the body explains what went wrong.
{
"error": "loading config: ...",
"warnings": [
{ "file": "Caddyfile", "line": 2, "message": "..." }
]
}
Warnings deserve attention even on a 200. Caddy starts the configuration anyway, but a warning usually means the adapter had to guess.
Loading the entire configuration is wasteful when the goal is to add a single listener, and dangerous when other people are editing the same server. The /config/ paths let you write to one location.
| Method | Behaviour on an array | Behaviour on an object |
|---|---|---|
POST | Appends the payload to the array | Creates or replaces the value |
PUT | Inserts the payload at the given index | Strictly creates a new value |
PATCH | Replaces the element at the given index | Strictly replaces an existing value |
DELETE | Removes the value at the path | Removes the value at the path |
Adding a listener address to an existing server is a POST.
curl "http://localhost:2019/config/apps/http/servers/srv0/listen" \
-H "Content-Type: application/json" \
-d '":8080"'
The path may end in /..., in which case an array payload is expanded and every element is appended individually.
curl "http://localhost:2019/config/apps/http/servers/srv0/listen/..." \
-H "Content-Type: application/json" \
-d '[":8080", ":5133"]'
Removing one HTTP server while leaving the rest of the process alone is a DELETE.
curl -X DELETE "http://localhost:2019/config/apps/http/servers/srv0"
Deleting the entire configuration with DELETE /config/ unloads everything but keeps the process alive. That is the difference between “take this server out of service” and “shut the machine down”, and POST /stop is the second one.
curl -X DELETE "http://localhost:2019/config/"
curl -X POST "http://localhost:2019/stop"
Raw config paths are long and fragile. If you add a route in the middle of a server, every index-based path below it shifts. The API lets you name a part of the configuration so that you can address it directly.
Add an @id field to any object in the JSON.
{
"@id": "my_proxy",
"handler": "reverse_proxy"
}
Then reach it through /id/ instead of walking down from the root.
curl -s "http://localhost:2019/id/my_proxy/upstreams" | jq
The path /config/apps/http/servers/myserver/routes/1/handle/0/upstreams becomes /id/my_proxy/upstreams, which is short enough to type by hand and stable against unrelated edits. Any object can carry an @id, and the name must be unique within the configuration.
POST /adapt runs the config adapter and returns the JSON without applying it. This is the API counterpart of caddy adapt, and it is the right way to check what a Caddyfile becomes before you commit to it.
curl "http://localhost:2019/adapt" \
-H "Content-Type: text/caddyfile" \
--data-binary @Caddyfile | jq
The content type selects the adapter in exactly the same way as /load. Because the file is never loaded, this is safe to run against a production server and is a good way to answer the question “what does this directive expand into”.
Caddy can run its own certificate authority. Two endpoints expose it. GET /pki/ca/local returns information about the CA, including the root and intermediate certificates, and provisions the CA if it has not been provisioned yet.
curl -s http://localhost:2019/pki/ca/local | jq
GET /pki/ca/local/certificates returns the certificate chain, which is what the caddy trust command installs into a local trust store. The local identifier is the default CA; any other identifier must have been provisioned before it will answer.
Each individual request to the config API is atomic, but the API has no transactions spanning multiple requests, and HTTP has no locking. If two clients read the same part of the configuration, edit it, and write it back at the same time, one of them will overwrite the other or leave the configuration in a state neither of them intended.
Caddy solves this with optimistic concurrency control. Every response to a config read carries an ETag header that encodes the path and a hash of the content in that scope. Send that value back as If-Match on the write, and Caddy rejects the write if the scope has changed underneath you.
# 1. Read the scope and remember its tag.
etag=$(curl -sD - -o scope.json \
"http://localhost:2019/config/apps/http/servers/srv0" \
| awk '/^ETag:/ {print $2}' | tr -d '\r')
# 2. Edit scope.json however you like.
# 3. Write it back, but only if nothing changed in the meantime.
curl -X PATCH "http://localhost:2019/config/apps/http/servers/srv0" \
-H "Content-Type: application/json" \
-H "If-Match: $etag" \
--data-binary @scope.json
If the scope changed, the response is 412 Precondition Failed. At that point you read it again, reapply your change, and try once more. Two writers touching different scopes never conflict, so the retry only matters when the same part of the configuration is being changed by both.
Unless you disable it, the current configuration is written to disk after every change made through the API. That means a process that was started empty can come back after a reboot with the configuration it was running.
caddy run --resume
--resume starts Caddy with the last saved configuration instead of a file on disk. This is the natural pairing for an API-driven deployment: the API owns the configuration, and the process keeps running across reboots without a separate configuration file to keep in sync.
| Mistake | What happens | Correction |
|---|---|---|
| Exposing the admin endpoint on a public address | Anyone who can reach it controls the server | Keep the loopback default, or use a unix socket |
Using curl -d with a Caddyfile | Newlines are stripped and the parse fails | Use --data-binary |
Expecting a POST /load to always reload | Identical configuration is a no-op | Send Cache-Control: must-revalidate |
| Writing to a long numeric config path | The path shifts when a route is inserted | Put an @id on the object and address it through /id/ |
| Two scripts editing the same scope | The second write silently discards the first | Use ETag and If-Match |
| Turning the endpoint off and then trying to reload | Reload is impossible without it | Keep the endpoint enabled, or accept restarts with downtime |
Approach:
The goal is to add a new site to a server that is already serving traffic, without restarting it and without disturbing the sites that are already there. The naive way, reloading a complete configuration file, works but is coarse: it rewrites everything, it needs the whole file to be correct on the machine doing the deploy, and it is unsafe if anything else is editing the same server. The API offers a better path, but only if the change is scoped, addressed by a stable name, and guarded against concurrent writers.
Steps:
- Confirm the endpoint is reachable and that you know which process you are talking to.
GET /idreturns the server identifier, andGET /config/returns the configuration currently in force. If the endpoint listens somewhere other thanlocalhost:2019, pass--addressto the CLI commands or setCADDY_ADMIN. - Read the existing configuration with
GET /config/and keep the response. This is the source of truth, not the Caddyfile on disk, because it shows what the adapter actually produced. - Decide the smallest useful change. Adding a site means adding a route, which in practice means adding to the routes array of an existing HTTP server, or adding a new HTTP server entirely.
- Give the new object a stable name. Put an
@idfield such as"@id": "new_site"on the object you are creating, so that later updates do not depend on array positions. - Capture the
ETagof the scope you are about to modify from the response headers of the read in step 2. - Write the change with
POSTon the config path, usingContent-Type: application/jsonand the--data-binaryform ofcurlso the JSON is sent byte for byte. An array payload appended to an array is expanded when the path ends in/.... - Send the
ETagfrom step 5 asIf-Match. A200means the change was applied; a412means someone else changed the same scope in the meantime, so read the scope again and retry. - Verify with
GET /id/new_sitethat the new object is in place, then make a real request to the new hostname to confirm the route serves traffic.
Answer:
The site is added with three API calls and no restart. The first is a read that establishes both the current state and the concurrency token.
curl -sD headers.txt -o config.json "http://localhost:2019/config/"The second is the write, scoped to the routes array of the server that should handle the new hostname, with the token from the read attached.
etag=$(awk '/^ETag:/ {print $2}' headers.txt | tr -d '\r')
curl -X POST "http://localhost:2019/config/apps/http/servers/srv0/routes/..." \
-H "Content-Type: application/json" \
-H "If-Match: $etag" \
--data-binary @route.jsonwhere route.json is a single route object carrying a stable name.
{
"@id": "new_site",
"match": [{ "host": ["new.example.com"] }],
"handle": [{ "handler": "static_response", "body": "hello" }]
}The third is the verification.
curl -s "http://localhost:2019/id/new_site" | jq
curl -I https://new.example.comThe result is that the new hostname is served, the existing sites keep running on the old configuration until their own requests drain, the change was rejected rather than silently merged if another writer touched the same scope, and the server was never restarted, so there was no downtime and no effect on certificate issuance for the other sites.
