openapi: 3.1.0
info:
  title: Caddy Admin API
  version: "1.0"
  description: >-
    Minimal OpenAPI 3.1 description of the Caddy web server admin API. By
    default the admin endpoint is bound to localhost:2019 and is used to
    inspect and dynamically modify the running configuration without restarts.
  x-generated-from: https://caddyserver.com/docs/api
  x-generated-by: claude-crawl-2026-05-08
servers:
  - url: http://localhost:2019
    description: Default admin endpoint
tags:
  - name: Lifecycle
  - name: Configuration
  - name: Adapt
  - name: PKI
  - name: Reverse Proxy
paths:
  /load:
    post:
      tags: [Lifecycle]
      summary: Set or replace the active configuration
      operationId: loadConfig
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Config' }
      responses:
        '200':
          description: Loaded
        '400':
          description: Invalid configuration
  /stop:
    post:
      tags: [Lifecycle]
      summary: Gracefully shut down the server
      operationId: stopServer
      responses:
        '200':
          description: Stopped
  /config/{path}:
    parameters:
      - $ref: '#/components/parameters/PathParam'
    get:
      tags: [Configuration]
      summary: Export current configuration at a named path
      operationId: getConfigPath
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Config' }
    post:
      tags: [Configuration]
      summary: Create or append to configuration at a named path
      operationId: postConfigPath
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Config' }
      responses:
        '200':
          description: OK
    put:
      tags: [Configuration]
      summary: Create new objects or insert into arrays at a named path
      operationId: putConfigPath
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Config' }
      responses:
        '200':
          description: OK
    patch:
      tags: [Configuration]
      summary: Replace existing configuration values at a named path
      operationId: patchConfigPath
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Config' }
      responses:
        '200':
          description: OK
    delete:
      tags: [Configuration]
      summary: Remove configuration at a named path
      operationId: deleteConfigPath
      responses:
        '200':
          description: OK
  /adapt:
    post:
      tags: [Adapt]
      summary: Convert a Caddyfile or other config format to JSON without loading
      operationId: adaptConfig
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Config' }
  /pki/ca/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    get:
      tags: [PKI]
      summary: Returns PKI CA information
      operationId: getPkiCa
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Config' }
  /pki/ca/{id}/certificates:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    get:
      tags: [PKI]
      summary: Returns the CA certificate chain
      operationId: getPkiCaCertificates
      responses:
        '200':
          description: OK
          content:
            application/x-pem-file:
              schema:
                type: string
  /reverse_proxy/upstreams:
    get:
      tags: [Reverse Proxy]
      summary: Show reverse proxy upstream status
      operationId: getReverseProxyUpstreams
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Config'
components:
  parameters:
    PathParam:
      name: path
      in: path
      required: true
      description: Configuration path traversal expression.
      schema:
        type: string
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: string
  schemas:
    Config:
      type: object
      additionalProperties: true