kumomta/docs/reference/proxy-server.openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "proxy-server",
    "description": "",
    "license": {
      "name": "Apache-2.0"
    },
    "version": "2026.02.04-4f636a0f"
  },
  "paths": {
    "/api/admin/bump-config-epoch": {
      "post": {
        "tags": [
          "config"
        ],
        "summary": "Allows the system operator to trigger a configuration epoch bump,\nwhich causes various configs that are using the Epoch strategy to\nbe re-evaluated by triggering the appropriate callbacks.",
        "operationId": "bump_config_epoch",
        "responses": {
          "200": {
            "description": "bump successful"
          }
        }
      }
    },
    "/api/admin/memory/stats": {
      "get": {
        "tags": [
          "memory"
        ],
        "summary": "Returns information about the system memory usage in an unstructured\nhuman readable format.  The output is not machine parseable and may\nchange without notice between versions of kumomta.",
        "operationId": "memory_stats",
        "responses": {
          "200": {
            "description": "stats were returned"
          }
        }
      }
    },
    "/api/admin/set_diagnostic_log_filter/v1": {
      "post": {
        "tags": [
          "logging",
          "kcli:set-log-filter"
        ],
        "summary": "Changes the diagnostic log filter dynamically.\nSee <https://docs.kumomta.com/reference/kumo/set_diagnostic_log_filter/>\nfor more information on diagnostic log filters.",
        "operationId": "set_diagnostic_log_filter_v1",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetDiagnosticFilterRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Diagnostic level set successfully"
          }
        }
      }
    },
    "/metrics": {
      "get": {
        "tags": [],
        "summary": "Returns the current set of metrics in\n[Prometheus Text Exposition Format](https://prometheus.io/docs/instrumenting/exposition_formats/).",
        "description": "!!! note\n    Metrics generally represent data at the current point in time,\n    to be consumed by an external system (such as Prometheus) which\n    then in turn can build time series data around those metrics.\n\n    In addition, in order to avoid unbounded RAM usage for systems\n    with many queues, a number of queue- or service-specific metrics\n    will be automatically pruned away when the corresponding queue\n    idles out for a period of time.\n\nIn the default configuration, access to this endpoint requires *Trusted IP*\nauthentication.  See the [Authorization](../../access_control.md) documentation\nfor more information on adjusting ACLs.\n\nSee also [metrics.json](metrics.json_get.md).\n\n## Metric Documentation\n\n* [Metrics exported by kumod](../../metrics/kumod/index.md)\n\n## Example Data\n\nHere's an example of the shape of the data.  The precise set of\ncounters will vary as we continue to enhance KumoMTA.\n\nYou can see the current list by querying the endpoint with no arguments:\n\n```console\n$ curl http://localhost:8000/metrics\n```\n\n```txt\n{% include \"reference/http/sample-metrics.txt\" %}\n```",
        "operationId": "report_metrics",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "text/plain": {}
            }
          }
        }
      }
    },
    "/metrics.json": {
      "get": {
        "tags": [],
        "summary": "Returns the current set of metrics in a json representation.\nThis is easier to consume than the Prometheus Exposition format, but\nis more resource intensive to produce and parse when the number of\nmetrics is large, such as for a busy server.",
        "description": "!!! note\n    Metrics generally represent data at the current point in time,\n    to be consumed by an external system (such as Prometheus) which\n    then in turn can build time series data around those metrics.\n\n    In addition, in order to avoid unbounded RAM usage for systems\n    with many queues, a number of queue- or service-specific metrics\n    will be automatically pruned away when the corresponding queue\n    idles out for a period of time.\n\nIn the default configuration, access to this endpoint requires *Trusted IP*\nauthentication.  See the [Authorization](../../access_control.md) documentation\nfor more information on adjusting ACLs.\n\nSee also [metrics](metrics_get.md).\n\n## Metric Documentation\n\n* [Metrics exported by kumod](../../metrics/kumod/index.md)\n\n## Example Data\n\nHere's an example of the shape of the data.  The precise set of\ncounters will vary as we continue to enhance KumoMTA:\n\n```json\n{% include \"reference/http/sample-metrics.json\" %}\n```",
        "operationId": "report_metrics_json",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/proxy/status": {
      "get": {
        "tags": [
          "status"
        ],
        "summary": "Simple health check endpoint for the proxy.\nReturns basic status information.",
        "operationId": "proxy_status",
        "responses": {
          "200": {
            "description": "Proxy is healthy",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SetDiagnosticFilterRequest": {
        "type": "object",
        "required": [
          "filter"
        ],
        "properties": {
          "filter": {
            "type": "string",
            "description": "The diagnostic filter spec to use",
            "example": "kumod=trace"
          }
        }
      }
    },
    "securitySchemes": {
      "basic_auth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": [
    {
      "basic_auth": [
        ""
      ]
    }
  ]
}