This page is about Caddy 2, which is currently in beta. Click here for the old Caddy 1 site. Thank you for your patience as we transition!
Documentation
Caddy 2 is beta software. It is ready for production, but some things will change between releases; check the release notes before upgrading.

API quick-start

Prerequisites:

  • Basic terminal / command line skills
  • caddy and curl in your PATH

First start Caddy:

caddy start

Caddy is currently running idle (with a blank configuration). Give it a simple config with curl:

curl localhost:2019/load \
	-X POST \
    -H "Content-Type: application/json" \
    -d @- << EOF
	{
		"apps": {
			"http": {
				"servers": {
					"hello": {
						"listen": [":2015"],
						"routes": [
							{
								"handle": [{
									"handler": "static_response",
									"body": "Hello, world!"
								}]
							}
						]
					}
				}
			}
		}
	}
EOF

Giving a POST body with Heredoc can be tedious, so if you prefer to use files, save the JSON to a file called caddy.json and then use this command instead:

curl localhost:2019/load \
  -X POST \
  -H "Content-Type: application/json" \
  -d @caddy.json

Now load localhost:2015 in your browser or use curl:

curl localhost:2015
Hello, world!

We can also define multiple sites on different interfaces with this JSON:

{
	"apps": {
		"http": {
			"servers": {
				"hello": {
					"listen": [":2015"],
					"routes": [
						{
							"handle": [{
								"handler": "static_response",
								"body": "Hello, world!"
							}]
						}
					]
				},
				"bye": {
					"listen": [":2016"],
					"routes": [
						{
							"handle": [{
								"handler": "static_response",
								"body": "Goodbye, world!"
							}]
						}
					]
				}
			}
		}
	}
}

Update your JSON then perform the API request again.

Try out your new "goodbye" endpoint in your browser or with curl to make sure it works:

curl localhost:2016
Goodbye, world!

When you are done with Caddy, make sure to stop it:

caddy stop

There's a lot more you can do with the API, including exporting configuration and making fine-grained changes to the config (as opposed to updating the whole thing). Be sure to read the full API tutorial to learn how!

Further reading