Caddy

Use these endpoints to manage Caddy operations on a Crate Operator host. The reference below includes request attributes, response shapes, and executable request examples.

The Caddy object

Optional attributes

@id string

handle array<CaddyRouteHandle>

match array<CaddyRouteMatch>

terminal boolean

The Caddy object JSON

{
  "@id": "string",
  "handle": [
    {
      "handler": "string",
      "lb_policy": "string",
      "load_balancing": {},
      "routes": [
        {}
      ],
      "upstreams": [
        {}
      ]
    }
  ],
  "match": [
    {
      "host": [
        "string"
      ]
    }
  ],
  "terminal": true
}

GET /v1/caddy/routes

Get current Caddy routes

Responses

200 OK

503 Caddy unavailable

Request cURL

GET /v1/caddy/routes

curl --request GET 'http://localhost:8080/v1/caddy/routes' \
  --header 'X-API-Key: <token>'

Response JSON

[
  {
    "@id": "string",
    "handle": [
      {
        "handler": "string",
        "lb_policy": "string",
        "load_balancing": {},
        "routes": [
          {}
        ],
        "upstreams": [
          {}
        ]
      }
    ],
    "match": [
      {
        "host": [
          "string"
        ]
      }
    ],
    "terminal": true
  }
]

POST /v1/caddy/routes

Create a new Caddy route

Creates a new Caddy reverse-proxy route. The route @id is derived from the provided domain. If a route with the same @id already exists, a 409 Conflict is returned.

Request attributes

Required attributes

domain string

Hostname this route matches.

upstreams array<object>

Optional attributes

callback_url string<uri> | null

Optional callback URL to receive a route_backup event before mutation.

strategy string

Load-balancing selection policy.

firstweighted_round_robin

terminal boolean

Whether the route is terminal.

Responses

201 Created

400 Bad Request

409 Route already exists

503 Caddy unavailable

Request cURL

POST /v1/caddy/routes

curl --request POST 'http://localhost:8080/v1/caddy/routes' \
  --header 'X-API-Key: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "callback_url": null,
  "domain": "string",
  "strategy": "first",
  "terminal": true,
  "upstreams": [
    {
      "dial": "string",
      "weight": 1
    }
  ]
}'

Response JSON

{
  "route_id": "string"
}

PUT /v1/caddy/routes/{route_id}

Replace a Caddy route

Fully replaces an existing Caddy route. The previous route state is captured before mutation and used for automatic rollback if the operation fails. If callback_url is provided, the previous state is also sent to the main app for durability.

Parameters

route_id string path required

The Caddy route @id.

Request attributes

Required attributes

domain string

Hostname this route matches.

upstreams array<object>

Optional attributes

callback_url string<uri> | null

Optional callback URL to receive a route_backup event before mutation.

strategy string

Load-balancing selection policy.

firstweighted_round_robin

terminal boolean

Whether the route is terminal.

Responses

200 OK

400 Bad Request

403 Operator route is immutable

404 Route not found

503 Caddy unavailable or rollback failed

Request cURL

PUT /v1/caddy/routes/{route_id}

curl --request PUT 'http://localhost:8080/v1/caddy/routes/<route_id>' \
  --header 'X-API-Key: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "callback_url": null,
  "domain": "string",
  "strategy": "first",
  "terminal": true,
  "upstreams": [
    {
      "dial": "string",
      "weight": 1
    }
  ]
}'

Response JSON

{
  "route_id": "string"
}

DELETE /v1/caddy/routes/{route_id}

Delete a Caddy route

Deletes a Caddy route. The route state is captured before deletion and used for automatic rollback if the deletion fails. If callback_url is provided, the captured state is also sent to the main app for durability.

Parameters

route_id string path required

The Caddy route @id.

Request attributes

Optional attributes

callback_url string<uri> | null

Optional callback URL to receive a route_backup event before mutation.

Responses

204 No Content

400 Bad Request

403 Operator route is immutable

404 Route not found

503 Caddy unavailable or rollback failed

Request cURL

DELETE /v1/caddy/routes/{route_id}

curl --request DELETE 'http://localhost:8080/v1/caddy/routes/<route_id>' \
  --header 'X-API-Key: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "callback_url": null
}'

Response JSON

{
  "message": "string"
}