{"owner":"txn2","repo":"kubefwd","hasSpec":true,"specFile":"pkg/fwdapi/handlers/openapi.yaml","branch":"HEAD","format":"yaml","version":"3.x (YAML)","title":"kubefwd","description":"","endpoints":[],"spec":"openapi: 3.1.0\ninfo:\n  title: kubefwd API\n  description: |\n    REST API for controlling and monitoring kubefwd port forwarding.\n\n    kubefwd is a command-line utility for bulk Kubernetes port forwarding. This API provides\n    programmatic access to manage forwarded services, monitor traffic, and control namespace\n    watchers dynamically.\n\n    For full documentation, visit [kubefwd.com](https://kubefwd.com).\n\n    ## Authentication\n\n    All endpoints except `/api/health` require a Bearer token. Send it in the\n    `Authorization` header:\n\n    ```\n    Authorization: Bearer <api-key>\n    ```\n\n    Requests with a missing or invalid key receive `401 Unauthorized`.\n\n    The key is resolved at startup from the `KUBEFWD_API_KEY` environment\n    variable. If that variable is unset, kubefwd generates a random 32-character\n    hex key and prints the full value to the console (the only way to learn a\n    generated key). When you supply the key via `KUBEFWD_API_KEY`, it is not\n    echoed — the console only notes that the variable was used. To pin a known\n    key (for automation, CI, or the MCP bridge), set the variable before\n    launching:\n\n    ```\n    export KUBEFWD_API_KEY=my-known-key\n    sudo -E kubefwd --api\n    ```\n\n    The API binds to a loopback interface (127.2.27.1), so it is only reachable\n    from localhost, but the Bearer token is still required — any local process\n    could otherwise drive kubefwd against your kubeconfig.\n\n    ## URL Structure\n\n    When kubefwd runs with `--api`, it adds `kubefwd.internal` to /etc/hosts pointing to 127.2.27.1:\n\n    - `http://kubefwd.internal/` - Web interface (coming soon, redirects to /docs)\n    - `http://kubefwd.internal/docs` - This API documentation\n    - `http://kubefwd.internal/api/` - REST API endpoints\n  version: \"0.0.0\"\n  contact:\n    name: kubefwd\n    url: https://kubefwd.com\n  license:\n    name: Apache 2.0\n    url: https://www.apache.org/licenses/LICENSE-2.0\n\nexternalDocs:\n  description: kubefwd Documentation\n  url: https://kubefwd.com\n\nservers:\n  - url: http://kubefwd.internal/api\n    description: Local API server (via hostname)\n  - url: http://127.2.27.1/api\n    description: Local API server (via IP)\n\ntags:\n  - name: Health\n    description: Health and status endpoints\n  - name: Services\n    description: Forwarded service management\n  - name: Forwards\n    description: Individual port forward information\n  - name: Namespaces\n    description: Namespace watcher management (CRUD)\n  - name: Kubernetes\n    description: Kubernetes cluster discovery\n  - name: Metrics\n    description: Traffic metrics and statistics\n  - name: Diagnostics\n    description: Troubleshooting and diagnostics\n  - name: Events\n    description: Real-time event streaming (SSE)\n  - name: History\n    description: Historical events and reconnection data\n\nsecurity:\n  - bearerAuth: []\n\npaths:\n  /health:\n    get:\n      tags: [Health]\n      summary: Health check\n      description: Returns the health status of the kubefwd API server\n      operationId: getHealth\n      security: []\n      responses:\n        \"200\":\n          description: Health status\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n              example:\n                success: true\n                data:\n                  status: healthy\n                  version: \"1.22.0\"\n                  uptime: \"2h30m15s\"\n                  timestamp: \"2024-01-15T10:30:00Z\"\n\n  /info:\n    get:\n      tags: [Health]\n      summary: Runtime information\n      description: Returns detailed runtime information including version, platform, and configuration\n      operationId: getInfo\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Runtime information\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/services:\n    get:\n      tags: [Services]\n      summary: List forwarded services\n      description: Returns all currently forwarded services with their status and metrics\n      operationId: listServices\n      parameters:\n        - $ref: \"#/components/parameters/limitParam\"\n        - $ref: \"#/components/parameters/offsetParam\"\n        - $ref: \"#/components/parameters/statusParam\"\n        - $ref: \"#/components/parameters/namespaceParam\"\n        - $ref: \"#/components/parameters/contextParam\"\n        - $ref: \"#/components/parameters/searchParam\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: List of forwarded services\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n    post:\n      tags: [Services]\n      summary: Forward a specific service\n      description: Start forwarding a specific Kubernetes service\n      operationId: addService\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              $ref: \"#/components/schemas/AddServiceRequest\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Service forwarding started\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"400\":\n          description: Invalid request\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n        \"409\":\n          description: Service already forwarded\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n\n  /v1/services/{key}:\n    get:\n      tags: [Services]\n      summary: Get service details\n      description: Returns detailed information about a specific forwarded service\n      operationId: getService\n      parameters:\n        - $ref: \"#/components/parameters/serviceKeyParam\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Service details\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"404\":\n          description: Service not found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n    delete:\n      tags: [Services]\n      summary: Stop forwarding a service\n      description: Stop forwarding a specific service and clean up resources\n      operationId: removeService\n      parameters:\n        - $ref: \"#/components/parameters/serviceKeyParam\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Service forwarding stopped\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"404\":\n          description: Service not found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n\n  /v1/services/{key}/reconnect:\n    post:\n      tags: [Services]\n      summary: Reconnect a service\n      description: Trigger reconnection of all port forwards for a service\n      operationId: reconnectService\n      parameters:\n        - $ref: \"#/components/parameters/serviceKeyParam\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Reconnection triggered\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"404\":\n          description: Service not found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n\n  /v1/services/{key}/sync:\n    post:\n      tags: [Services]\n      summary: Sync service pods\n      description: Synchronize the port forwards with current pod state\n      operationId: syncService\n      parameters:\n        - $ref: \"#/components/parameters/serviceKeyParam\"\n        - name: force\n          in: query\n          description: Force sync even if recently synced\n          schema:\n            type: boolean\n            default: false\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Sync triggered\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"404\":\n          description: Service not found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n\n  /v1/services/reconnect:\n    post:\n      tags: [Services]\n      summary: Reconnect all errored services\n      description: Trigger reconnection for all services in error state\n      operationId: reconnectAllServices\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Reconnection triggered\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/services/{key}/http:\n    get:\n      tags: [Services]\n      summary: Get HTTP traffic for a service\n      description: Returns HTTP request/response logs for all forwards of a service\n      operationId: getServiceHTTPTraffic\n      parameters:\n        - $ref: \"#/components/parameters/serviceKeyParam\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: HTTP traffic logs\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"404\":\n          description: Service not found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n\n  /v1/services/{key}/history/reconnections:\n    get:\n      tags: [History]\n      summary: Get service reconnection history\n      description: Returns the reconnection history for a specific service\n      operationId: getServiceReconnections\n      parameters:\n        - $ref: \"#/components/parameters/serviceKeyParam\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Reconnection history\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/forwards:\n    get:\n      tags: [Forwards]\n      summary: List port forwards\n      description: Returns all active port forwards across all services\n      operationId: listForwards\n      parameters:\n        - $ref: \"#/components/parameters/limitParam\"\n        - $ref: \"#/components/parameters/offsetParam\"\n        - $ref: \"#/components/parameters/statusParam\"\n        - $ref: \"#/components/parameters/namespaceParam\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: List of port forwards\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/forwards/{key}:\n    get:\n      tags: [Forwards]\n      summary: Get forward details\n      description: Returns detailed information about a specific port forward\n      operationId: getForward\n      parameters:\n        - name: key\n          in: path\n          required: true\n          description: Port forward key (e.g., \"pod-name.service.namespace.context\")\n          schema:\n            type: string\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Forward details\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"404\":\n          description: Forward not found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n\n  /v1/forwards/{key}/http:\n    get:\n      tags: [Forwards]\n      summary: Get HTTP traffic for a forward\n      description: Returns HTTP request/response logs for a specific port forward\n      operationId: getForwardHTTPTraffic\n      parameters:\n        - name: key\n          in: path\n          required: true\n          description: Port forward key\n          schema:\n            type: string\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: HTTP traffic logs\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/namespaces:\n    get:\n      tags: [Namespaces]\n      summary: List watched namespaces\n      description: Returns all namespaces currently being watched for services\n      operationId: listNamespaces\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: List of watched namespaces\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n    post:\n      tags: [Namespaces]\n      summary: Start watching a namespace\n      description: Start watching a Kubernetes namespace for services to forward\n      operationId: addNamespace\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              $ref: \"#/components/schemas/AddNamespaceRequest\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Namespace watcher started\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"400\":\n          description: Invalid request\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n        \"409\":\n          description: Namespace already being watched\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n\n  /v1/namespaces/{key}:\n    get:\n      tags: [Namespaces]\n      summary: Get namespace details\n      description: Returns information about a watched namespace\n      operationId: getNamespace\n      parameters:\n        - name: key\n          in: path\n          required: true\n          description: Namespace key (e.g., \"default.minikube\")\n          schema:\n            type: string\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Namespace details\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"404\":\n          description: Namespace not found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n    delete:\n      tags: [Namespaces]\n      summary: Stop watching a namespace\n      description: Stop watching a namespace and remove all its forwarded services\n      operationId: removeNamespace\n      parameters:\n        - name: key\n          in: path\n          required: true\n          description: Namespace key (e.g., \"default.minikube\")\n          schema:\n            type: string\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Namespace watcher stopped\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"404\":\n          description: Namespace not found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n\n  /v1/kubernetes/namespaces:\n    get:\n      tags: [Kubernetes]\n      summary: List available Kubernetes namespaces\n      description: Returns all namespaces available in the Kubernetes cluster\n      operationId: listK8sNamespaces\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: List of K8s namespaces\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/kubernetes/services:\n    get:\n      tags: [Kubernetes]\n      summary: List available Kubernetes services\n      description: Returns services available for forwarding in a namespace\n      operationId: listK8sServices\n      parameters:\n        - name: namespace\n          in: query\n          description: Filter by namespace\n          schema:\n            type: string\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: List of K8s services\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/kubernetes/services/{namespace}/{name}:\n    get:\n      tags: [Kubernetes]\n      summary: Get Kubernetes service details\n      description: Returns detailed information about a specific Kubernetes service\n      operationId: getK8sService\n      parameters:\n        - name: namespace\n          in: path\n          required: true\n          description: Kubernetes namespace\n          schema:\n            type: string\n        - name: name\n          in: path\n          required: true\n          description: Service name\n          schema:\n            type: string\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: K8s service details\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"404\":\n          description: Service not found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n\n  /v1/kubernetes/contexts:\n    get:\n      tags: [Kubernetes]\n      summary: List available Kubernetes contexts\n      description: Returns all available Kubernetes contexts from kubeconfig\n      operationId: listK8sContexts\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: List of K8s contexts\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/kubernetes/pods/{namespace}:\n    get:\n      tags: [Kubernetes]\n      summary: List pods in a namespace\n      description: Returns pods with status, ready state, restarts, and age. Filter by label selector or service name.\n      operationId: listK8sPods\n      parameters:\n        - name: namespace\n          in: path\n          required: true\n          description: Kubernetes namespace\n          schema:\n            type: string\n        - name: context\n          in: query\n          description: Kubernetes context (uses current if omitted)\n          schema:\n            type: string\n        - name: labelSelector\n          in: query\n          description: Label selector to filter pods (e.g., \"app=nginx,version=v1\")\n          schema:\n            type: string\n        - name: serviceName\n          in: query\n          description: Filter to pods backing this service\n          schema:\n            type: string\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: List of pods\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"404\":\n          description: Namespace not found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n\n  /v1/kubernetes/pods/{namespace}/{podName}:\n    get:\n      tags: [Kubernetes]\n      summary: Get pod details\n      description: Returns detailed pod information including containers, status, conditions, resources, and recent events\n      operationId: getK8sPod\n      parameters:\n        - name: namespace\n          in: path\n          required: true\n          description: Kubernetes namespace\n          schema:\n            type: string\n        - name: podName\n          in: path\n          required: true\n          description: Pod name\n          schema:\n            type: string\n        - name: context\n          in: query\n          description: Kubernetes context (uses current if omitted)\n          schema:\n            type: string\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Pod details\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"404\":\n          description: Pod not found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n\n  /v1/kubernetes/pods/{namespace}/{podName}/logs:\n    get:\n      tags: [Kubernetes]\n      summary: Get pod logs\n      description: Returns log output from a pod's container. Useful for debugging services.\n      operationId: getK8sPodLogs\n      parameters:\n        - name: namespace\n          in: path\n          required: true\n          description: Kubernetes namespace\n          schema:\n            type: string\n        - name: podName\n          in: path\n          required: true\n          description: Pod name\n          schema:\n            type: string\n        - name: context\n          in: query\n          description: Kubernetes context (uses current if omitted)\n          schema:\n            type: string\n        - name: container\n          in: query\n          description: Container name (defaults to first container)\n          schema:\n            type: string\n        - name: tailLines\n          in: query\n          description: Number of lines from end (default 100, max 1000)\n          schema:\n            type: integer\n            default: 100\n            maximum: 1000\n        - name: sinceTime\n          in: query\n          description: RFC3339 timestamp to start from (e.g., 2024-01-15T10:30:00Z)\n          schema:\n            type: string\n            format: date-time\n        - name: previous\n          in: query\n          description: Get logs from previous container instance\n          schema:\n            type: boolean\n            default: false\n        - name: timestamps\n          in: query\n          description: Include timestamps in log output\n          schema:\n            type: boolean\n            default: false\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Pod logs\n          content:\n            application/json:\n              schema:\n                allOf:\n                  - $ref: \"#/components/schemas/Response\"\n                  - type: object\n                    properties:\n                      data:\n                        type: object\n                        properties:\n                          podName:\n                            type: string\n                          namespace:\n                            type: string\n                          containerName:\n                            type: string\n                          logs:\n                            type: string\n                          lineCount:\n                            type: integer\n                          truncated:\n                            type: boolean\n        \"404\":\n          description: Pod not found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n\n  /v1/kubernetes/events/{namespace}:\n    get:\n      tags: [Kubernetes]\n      summary: Get Kubernetes events\n      description: Returns Kubernetes events for debugging. Shows scheduling, pulling, starting, killing events. Critical for diagnosing startup failures.\n      operationId: getK8sEvents\n      parameters:\n        - name: namespace\n          in: path\n          required: true\n          description: Kubernetes namespace\n          schema:\n            type: string\n        - name: context\n          in: query\n          description: Kubernetes context (uses current if omitted)\n          schema:\n            type: string\n        - name: resourceKind\n          in: query\n          description: Filter by resource kind (Pod, Service, Deployment, etc.)\n          schema:\n            type: string\n        - name: resourceName\n          in: query\n          description: Filter by resource name\n          schema:\n            type: string\n        - name: limit\n          in: query\n          description: Max events to return (default 50)\n          schema:\n            type: integer\n            default: 50\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Kubernetes events\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/kubernetes/endpoints/{namespace}/{serviceName}:\n    get:\n      tags: [Kubernetes]\n      summary: Get service endpoints\n      description: Returns endpoints for a Kubernetes service. Shows which pods are backing the service and their ready state. Useful for debugging service-to-pod routing.\n      operationId: getK8sEndpoints\n      parameters:\n        - name: namespace\n          in: path\n          required: true\n          description: Kubernetes namespace\n          schema:\n            type: string\n        - name: serviceName\n          in: path\n          required: true\n          description: Service name\n          schema:\n            type: string\n        - name: context\n          in: query\n          description: Kubernetes context (uses current if omitted)\n          schema:\n            type: string\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Service endpoints\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"404\":\n          description: Service or endpoints not found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n\n  /v1/metrics:\n    get:\n      tags: [Metrics]\n      summary: Get metrics summary\n      description: Returns overall traffic and health metrics\n      operationId: getMetricsSummary\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Metrics summary\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/metrics/services:\n    get:\n      tags: [Metrics]\n      summary: Get metrics by service\n      description: Returns traffic metrics grouped by service\n      operationId: getMetricsByService\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Service metrics\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/metrics/services/{key}:\n    get:\n      tags: [Metrics]\n      summary: Get service metrics detail\n      description: Returns detailed metrics for a specific service\n      operationId: getServiceMetrics\n      parameters:\n        - $ref: \"#/components/parameters/serviceKeyParam\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Service metrics\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n        \"404\":\n          description: Service not found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ErrorResponse\"\n\n  /v1/metrics/services/{key}/history:\n    get:\n      tags: [Metrics]\n      summary: Get service metrics history\n      description: Returns historical traffic data for a service\n      operationId: getServiceMetricsHistory\n      parameters:\n        - $ref: \"#/components/parameters/serviceKeyParam\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Metrics history\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/logs:\n    get:\n      tags: [Events]\n      summary: Get recent logs\n      description: Returns recent log entries\n      operationId: getRecentLogs\n      parameters:\n        - $ref: \"#/components/parameters/limitParam\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Log entries\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/logs/stream:\n    get:\n      tags: [Events]\n      summary: Stream logs (SSE)\n      description: Server-Sent Events stream of log entries\n      operationId: streamLogs\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: SSE log stream\n          content:\n            text/event-stream:\n              schema:\n                type: string\n\n  /v1/logs/system:\n    get:\n      tags: [Events]\n      summary: Get system logs\n      description: |\n        Returns kubefwd system logs from the internal ring buffer.\n        Captures all logrus output for debugging and monitoring.\n      operationId: getSystemLogs\n      parameters:\n        - name: count\n          in: query\n          description: Number of log entries to return (default 100, max 1000)\n          schema:\n            type: integer\n            default: 100\n            maximum: 1000\n        - name: level\n          in: query\n          description: Filter by log level\n          schema:\n            type: string\n            enum: [debug, info, warn, error, fatal, panic]\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: System log entries\n          content:\n            application/json:\n              schema:\n                allOf:\n                  - $ref: \"#/components/schemas/Response\"\n                  - type: object\n                    properties:\n                      data:\n                        type: object\n                        properties:\n                          logs:\n                            type: array\n                            items:\n                              $ref: \"#/components/schemas/LogEntry\"\n                          totalCount:\n                            type: integer\n                            description: Total entries in the buffer\n    delete:\n      tags: [Events]\n      summary: Clear system logs\n      description: Clears the system log ring buffer\n      operationId: clearSystemLogs\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Log buffer cleared\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/events:\n    get:\n      tags: [Events]\n      summary: Stream events (SSE)\n      description: Server-Sent Events stream of kubefwd events (service added, pod changed, etc.)\n      operationId: streamEvents\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: SSE event stream\n          content:\n            text/event-stream:\n              schema:\n                type: string\n\n  /v1/diagnostics:\n    get:\n      tags: [Diagnostics]\n      summary: Get diagnostics summary\n      description: Returns overall diagnostic information\n      operationId: getDiagnostics\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Diagnostics summary\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/diagnostics/services/{key}:\n    get:\n      tags: [Diagnostics]\n      summary: Get service diagnostics\n      description: Returns diagnostic information for a specific service\n      operationId: getServiceDiagnostics\n      parameters:\n        - $ref: \"#/components/parameters/serviceKeyParam\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Service diagnostics\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/diagnostics/forwards/{key}:\n    get:\n      tags: [Diagnostics]\n      summary: Get forward diagnostics\n      description: Returns diagnostic information for a specific port forward\n      operationId: getForwardDiagnostics\n      parameters:\n        - name: key\n          in: path\n          required: true\n          description: Port forward key\n          schema:\n            type: string\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Forward diagnostics\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/diagnostics/network:\n    get:\n      tags: [Diagnostics]\n      summary: Get network diagnostics\n      description: Returns network interface and IP allocation diagnostics\n      operationId: getNetworkDiagnostics\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Network diagnostics\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/diagnostics/errors:\n    get:\n      tags: [Diagnostics]\n      summary: Get error diagnostics\n      description: Returns information about services and forwards in error state\n      operationId: getErrorDiagnostics\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Error diagnostics\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/status:\n    get:\n      tags: [Diagnostics]\n      summary: Get AI-optimized status\n      description: Returns a compact status summary optimized for AI/MCP consumption\n      operationId: getStatus\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Compact status\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/analyze:\n    get:\n      tags: [Diagnostics]\n      summary: Get AI-optimized analysis\n      description: Returns detailed analysis optimized for AI/MCP consumption\n      operationId: getAnalysis\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Analysis results\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/history/events:\n    get:\n      tags: [History]\n      summary: Get event history\n      description: Returns historical events (service added, removed, etc.)\n      operationId: getEventHistory\n      parameters:\n        - $ref: \"#/components/parameters/limitParam\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Event history\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/history/errors:\n    get:\n      tags: [History]\n      summary: Get error history\n      description: Returns historical error events\n      operationId: getErrorHistory\n      parameters:\n        - $ref: \"#/components/parameters/limitParam\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Error history\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/history/reconnections:\n    get:\n      tags: [History]\n      summary: Get all reconnection history\n      description: Returns reconnection history across all services\n      operationId: getAllReconnections\n      parameters:\n        - $ref: \"#/components/parameters/limitParam\"\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: Reconnection history\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\n  /v1/history/stats:\n    get:\n      tags: [History]\n      summary: Get history statistics\n      description: Returns aggregate statistics from historical data\n      operationId: getHistoryStats\n      responses:\n        \"401\":\n          $ref: \"#/components/responses/Unauthorized\"\n        \"200\":\n          description: History statistics\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Response\"\n\ncomponents:\n  securitySchemes:\n    bearerAuth:\n      type: http\n      scheme: bearer\n      description: |\n        Bearer token resolved from the `KUBEFWD_API_KEY` environment variable,\n        or a random key generated and printed to the console at startup.\n\n  responses:\n    Unauthorized:\n      description: Missing or invalid API key\n      content:\n        application/json:\n          schema:\n            $ref: \"#/components/schemas/ErrorResponse\"\n          example:\n            success: false\n            error:\n              code: UNAUTHORIZED\n              message: \"API key required. Pass via Authorization: Bearer <key>\"\n\n  parameters:\n    serviceKeyParam:\n      name: key\n      in: path\n      required: true\n      description: Service key in format \"servicename.namespace.context\"\n      schema:\n        type: string\n      example: \"postgres.default.minikube\"\n\n    limitParam:\n      name: limit\n      in: query\n      description: Maximum number of items to return\n      schema:\n        type: integer\n        default: 100\n        maximum: 1000\n\n    offsetParam:\n      name: offset\n      in: query\n      description: Number of items to skip for pagination\n      schema:\n        type: integer\n        default: 0\n\n    statusParam:\n      name: status\n      in: query\n      description: Filter by status\n      schema:\n        type: string\n        enum: [active, error, partial, pending]\n\n    namespaceParam:\n      name: namespace\n      in: query\n      description: Filter by namespace\n      schema:\n        type: string\n\n    contextParam:\n      name: context\n      in: query\n      description: Filter by Kubernetes context\n      schema:\n        type: string\n\n    searchParam:\n      name: search\n      in: query\n      description: Search in service/pod names\n      schema:\n        type: string\n\n  schemas:\n    Response:\n      type: object\n      properties:\n        success:\n          type: boolean\n        data:\n          type: object\n        error:\n          $ref: \"#/components/schemas/ErrorInfo\"\n        meta:\n          $ref: \"#/components/schemas/MetaInfo\"\n\n    ErrorResponse:\n      type: object\n      properties:\n        success:\n          type: boolean\n          example: false\n        error:\n          $ref: \"#/components/schemas/ErrorInfo\"\n\n    ErrorInfo:\n      type: object\n      properties:\n        code:\n          type: string\n          example: NOT_FOUND\n        message:\n          type: string\n          example: Service not found\n\n    MetaInfo:\n      type: object\n      properties:\n        count:\n          type: integer\n        timestamp:\n          type: string\n          format: date-time\n\n    AddNamespaceRequest:\n      type: object\n      required:\n        - namespace\n      properties:\n        namespace:\n          type: string\n          description: Kubernetes namespace to watch\n          example: staging\n        context:\n          type: string\n          description: Kubernetes context (defaults to current context)\n          example: minikube\n        selector:\n          type: string\n          description: Label selector to filter services\n          example: \"app=myapp\"\n\n    AddServiceRequest:\n      type: object\n      required:\n        - namespace\n        - serviceName\n      properties:\n        namespace:\n          type: string\n          description: Kubernetes namespace\n          example: default\n        serviceName:\n          type: string\n          description: Name of the service to forward\n          example: postgres\n        context:\n          type: string\n          description: Kubernetes context (defaults to current context)\n          example: minikube\n        ports:\n          type: array\n          items:\n            type: string\n          description: Specific ports to forward (optional, forwards all if omitted)\n          example: [\"5432\"]\n        localIP:\n          type: string\n          description: Reserve a specific local IP address (optional)\n          example: \"127.1.2.100\"\n\n    ServiceResponse:\n      type: object\n      properties:\n        key:\n          type: string\n          example: \"postgres.default.minikube\"\n        serviceName:\n          type: string\n          example: postgres\n        namespace:\n          type: string\n          example: default\n        context:\n          type: string\n          example: minikube\n        headless:\n          type: boolean\n        status:\n          type: string\n          enum: [active, error, partial, pending]\n        activeCount:\n          type: integer\n        errorCount:\n          type: integer\n        totalBytesIn:\n          type: integer\n        totalBytesOut:\n          type: integer\n        rateIn:\n          type: number\n        rateOut:\n          type: number\n\n    ForwardResponse:\n      type: object\n      properties:\n        key:\n          type: string\n        serviceKey:\n          type: string\n        serviceName:\n          type: string\n        namespace:\n          type: string\n        context:\n          type: string\n        podName:\n          type: string\n        localIP:\n          type: string\n          example: \"127.1.2.3\"\n        localPort:\n          type: string\n          example: \"5432\"\n        podPort:\n          type: string\n          example: \"5432\"\n        hostnames:\n          type: array\n          items:\n            type: string\n          example: [\"postgres\", \"postgres.default\", \"postgres.default.svc.cluster.local\"]\n        status:\n          type: string\n          enum: [active, error, reconnecting]\n        error:\n          type: string\n        startedAt:\n          type: string\n          format: date-time\n        bytesIn:\n          type: integer\n        bytesOut:\n          type: integer\n\n    NamespaceInfoResponse:\n      type: object\n      properties:\n        key:\n          type: string\n          example: \"default.minikube\"\n        namespace:\n          type: string\n          example: default\n        context:\n          type: string\n          example: minikube\n        serviceCount:\n          type: integer\n        activeCount:\n          type: integer\n        errorCount:\n          type: integer\n        running:\n          type: boolean\n        labelSelector:\n          type: string\n        fieldSelector:\n          type: string\n\n    K8sNamespace:\n      type: object\n      properties:\n        name:\n          type: string\n        status:\n          type: string\n          enum: [Active, Terminating]\n        forwarded:\n          type: boolean\n          description: True if this namespace is currently being watched\n\n    K8sService:\n      type: object\n      properties:\n        name:\n          type: string\n        namespace:\n          type: string\n        type:\n          type: string\n          enum: [ClusterIP, NodePort, LoadBalancer, ExternalName]\n        clusterIP:\n          type: string\n        ports:\n          type: array\n          items:\n            $ref: \"#/components/schemas/K8sServicePort\"\n        selector:\n          type: object\n          additionalProperties:\n            type: string\n        forwarded:\n          type: boolean\n          description: True if this service is currently being forwarded\n        forwardKey:\n          type: string\n          description: Key in the registry if forwarded\n\n    K8sServicePort:\n      type: object\n      properties:\n        name:\n          type: string\n        port:\n          type: integer\n        targetPort:\n          type: string\n        protocol:\n          type: string\n          enum: [TCP, UDP]\n\n    K8sContext:\n      type: object\n      properties:\n        name:\n          type: string\n        cluster:\n          type: string\n        user:\n          type: string\n        namespace:\n          type: string\n          description: Default namespace for this context\n        active:\n          type: boolean\n          description: True if this is the current context\n\n    HealthResponse:\n      type: object\n      properties:\n        status:\n          type: string\n          enum: [healthy, degraded, unhealthy]\n        version:\n          type: string\n        uptime:\n          type: string\n        timestamp:\n          type: string\n          format: date-time\n\n    LogEntry:\n      type: object\n      properties:\n        timestamp:\n          type: string\n          format: date-time\n        level:\n          type: string\n          enum: [debug, info, warn, error, fatal, panic]\n        message:\n          type: string\n"}