REST API¶

kubefwd's REST API enables programmatic control over port forwarding. Build custom tooling, integrate with CI/CD pipelines, or create dashboards that dynamically manage which services are forwarded. Add and remove namespaces or individual services on the fly, query real-time metrics, stream events via SSE, and diagnose connection issues without restarting kubefwd.

Quick Start¶

# Idle mode - API enabled by default, add namespaces dynamically
sudo -E kubefwd

# Or forward a namespace with API enabled
sudo -E kubefwd svc -n default --api

# Test the API
curl http://kubefwd.internal/api/health

The API is available at http://kubefwd.internal/api.

Interactive documentation is at http://kubefwd.internal/docs.

API Documentation

Overview¶

Property	Value
Base URL	`http://kubefwd.internal/api`
Authentication	None (loopback only)
Response Format	JSON
OpenAPI Spec	`/openapi.yaml`

All responses use this wrapper format:

{
  "success": true,
  "data": { ... },
  "error": null
}

Error responses:

{
  "success": false,
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Service not found"
  }
}

Health & Info¶

GET /api/health¶

Health check endpoint.

curl http://kubefwd.internal/api/health

{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00Z"
}

GET /api/info¶

Server information and version.

curl http://kubefwd.internal/api/info

{
  "version": "1.26.0",
  "uptime": "2h15m30s",
  "startedAt": "2025-01-15T08:15:00Z"
}

Services¶

GET /api/v1/services¶

List all forwarded services.

Query Parameters:

Parameter	Type	Description
namespace	string	Filter by namespace
context	string	Filter by context
status	string	Filter by status (active, error)

# List all services
curl http://kubefwd.internal/api/v1/services

# Filter by namespace
curl http://kubefwd.internal/api/v1/services?namespace=default

GET /api/v1/services/:key¶

Get a specific service. Key format: service-name.namespace.context

curl http://kubefwd.internal/api/v1/services/api-gateway.default.minikube

POST /api/v1/services¶

Add a new service to forward.

curl -X POST http://kubefwd.internal/api/v1/services \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "default",
    "service_name": "my-service",
    "context": "minikube"
  }'

DELETE /api/v1/services/:key¶

Stop forwarding a service.

curl -X DELETE http://kubefwd.internal/api/v1/services/my-service.default.minikube

POST /api/v1/services/:key/reconnect¶

Reconnect a specific service.

curl -X POST http://kubefwd.internal/api/v1/services/api-gateway.default.minikube/reconnect

POST /api/v1/services/:key/sync¶

Sync service with Kubernetes (refresh pods).

curl -X POST http://kubefwd.internal/api/v1/services/api-gateway.default.minikube/sync

POST /api/v1/services/reconnect¶

Reconnect all services (or all errored services).

# Reconnect all errored services
curl -X POST http://kubefwd.internal/api/v1/services/reconnect

# Force reconnect all services
curl -X POST "http://kubefwd.internal/api/v1/services/reconnect?force=true"

Forwards¶

Individual port forwards (a service may have multiple forwards for different pods/ports).

GET /api/v1/forwards¶

List all active port forwards.

Query Parameters:

Parameter	Type	Description
namespace	string	Filter by namespace
service	string	Filter by service name
status	string	Filter by status

curl http://kubefwd.internal/api/v1/forwards

GET /api/v1/forwards/:key¶

Get details for a specific forward.

curl http://kubefwd.internal/api/v1/forwards/api-gateway-pod-abc.default.minikube

GET /api/v1/forwards/:key/http¶

Get HTTP traffic captured for a forward.

Query Parameters:

Parameter	Type	Description
count	integer	Number of entries (default: 50)

curl http://kubefwd.internal/api/v1/forwards/api-gateway.default.minikube/http?count=10

Namespaces¶

Manage namespace watchers dynamically.

GET /api/v1/namespaces¶

List active namespace watchers.

curl http://kubefwd.internal/api/v1/namespaces

GET /api/v1/namespaces/:key¶

Get details for a namespace watcher. Key format: namespace.context

curl http://kubefwd.internal/api/v1/namespaces/default.minikube

POST /api/v1/namespaces¶

Add a namespace watcher (start forwarding all services in namespace).

curl -X POST http://kubefwd.internal/api/v1/namespaces \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "staging",
    "context": "minikube"
  }'

DELETE /api/v1/namespaces/:key¶

Remove a namespace watcher (stop forwarding all services in namespace).

curl -X DELETE http://kubefwd.internal/api/v1/namespaces/staging.minikube

Kubernetes Discovery¶

Query the Kubernetes cluster for available resources.

GET /api/v1/kubernetes/contexts¶

List available kubeconfig contexts.

curl http://kubefwd.internal/api/v1/kubernetes/contexts

GET /api/v1/kubernetes/namespaces¶

List namespaces in a context.

Query Parameters:

Parameter	Type	Description
context	string	Kubernetes context (uses current if omitted)

curl http://kubefwd.internal/api/v1/kubernetes/namespaces?context=minikube

GET /api/v1/kubernetes/services¶

List services in a namespace.

Query Parameters:

Parameter	Type	Description
namespace	string	Namespace (required)
context	string	Kubernetes context

curl "http://kubefwd.internal/api/v1/kubernetes/services?namespace=default&context=minikube"

GET /api/v1/kubernetes/services/:namespace/:name¶

Get details for a specific Kubernetes service.

curl http://kubefwd.internal/api/v1/kubernetes/services/default/api-gateway

Metrics¶

Traffic and performance metrics.

GET /api/v1/metrics¶

Summary metrics for all forwards.

curl http://kubefwd.internal/api/v1/metrics

{
  "totalServices": 15,
  "activeForwards": 23,
  "totalBytesIn": 1048576,
  "totalBytesOut": 524288,
  "uptime": "2h15m"
}

GET /api/v1/metrics/services¶

Metrics grouped by service.

curl http://kubefwd.internal/api/v1/metrics/services

GET /api/v1/metrics/services/:key¶

Detailed metrics for a specific service.

curl http://kubefwd.internal/api/v1/metrics/services/api-gateway.default.minikube

GET /api/v1/metrics/services/:key/history¶

Historical metrics for a service (time series data).

Query Parameters:

Parameter	Type	Description
duration	string	Time window (e.g., "1h", "30m")
interval	string	Bucket interval (e.g., "1m", "5m")

curl "http://kubefwd.internal/api/v1/metrics/services/api-gateway.default.minikube/history?duration=1h"

Diagnostics¶

Error analysis and troubleshooting.

GET /api/v1/diagnostics¶

Diagnostics summary.

curl http://kubefwd.internal/api/v1/diagnostics

GET /api/v1/diagnostics/errors¶

List current errors.

curl http://kubefwd.internal/api/v1/diagnostics/errors

GET /api/v1/diagnostics/services/:key¶

Diagnostics for a specific service.

curl http://kubefwd.internal/api/v1/diagnostics/services/api-gateway.default.minikube

GET /api/v1/diagnostics/forwards/:key¶

Diagnostics for a specific forward.

curl http://kubefwd.internal/api/v1/diagnostics/forwards/api-gateway.default.minikube

GET /api/v1/diagnostics/network¶

Network interface diagnostics.

curl http://kubefwd.internal/api/v1/diagnostics/network

Analysis¶

AI-friendly status and analysis endpoints.

GET /api/v1/status¶

Quick status overview optimized for AI tools.

curl http://kubefwd.internal/api/v1/status

{
  "status": "healthy",
  "message": "All services forwarding normally",
  "totalServices": 15,
  "activeServices": 15,
  "errorCount": 0
}

GET /api/v1/analyze¶

Detailed analysis with recommendations.

curl http://kubefwd.internal/api/v1/analyze

History¶

Event and error history.

GET /api/v1/history/events¶

Recent events.

Query Parameters:

Parameter	Type	Description
count	integer	Number of events (default: 50)

curl http://kubefwd.internal/api/v1/history/events?count=20

GET /api/v1/history/errors¶

Error history.

curl http://kubefwd.internal/api/v1/history/errors?count=20

GET /api/v1/history/reconnections¶

All reconnection events.

curl http://kubefwd.internal/api/v1/history/reconnections

GET /api/v1/services/:key/history/reconnections¶

Reconnection history for a specific service.

curl http://kubefwd.internal/api/v1/services/api-gateway.default.minikube/history/reconnections

GET /api/v1/history/stats¶

Aggregated history statistics.

curl http://kubefwd.internal/api/v1/history/stats

Logs¶

Application logs.

GET /api/v1/logs¶

Recent log entries.

Query Parameters:

Parameter	Type	Description
count	integer	Number of entries (default: 100)
level	string	Filter by level (debug, info, warn, error)
service	string	Filter by service

curl "http://kubefwd.internal/api/v1/logs?count=50&level=error"

GET /api/v1/logs/stream¶

Server-Sent Events (SSE) stream of logs.

curl http://kubefwd.internal/api/v1/logs/stream

GET /api/v1/logs/system¶

System-level logs.

curl http://kubefwd.internal/api/v1/logs/system

DELETE /api/v1/logs/system¶

Clear system logs.

curl -X DELETE http://kubefwd.internal/api/v1/logs/system

Events (SSE)¶

GET /api/v1/events¶

Server-Sent Events stream for real-time updates.

curl http://kubefwd.internal/api/v1/events

Event types:

service.added - New service started forwarding
service.removed - Service stopped forwarding
service.error - Service encountered an error
forward.connected - Port forward established
forward.disconnected - Port forward lost
pod.added - Pod added to service
pod.removed - Pod removed from service

Example event:

event: service.added
data: {"key":"api-gateway.default.minikube","namespace":"default","service":"api-gateway"}

HTTP Traffic¶

HTTP request/response capture for debugging.

GET /api/v1/services/:key/http¶

HTTP traffic for a service.

Query Parameters:

Parameter	Type	Description
count	integer	Number of entries (default: 50)

curl http://kubefwd.internal/api/v1/services/api-gateway.default.minikube/http?count=10

Error Codes¶

Code	Description
`NOT_FOUND`	Resource not found
`BAD_REQUEST`	Invalid request parameters
`INTERNAL_ERROR`	Server error
`ALREADY_EXISTS`	Resource already exists
`CONFLICT`	Operation conflicts with current state

REST API¶

Quick Start¶

Overview¶

Health & Info¶

GET /api/health¶

GET /api/info¶

Services¶

GET /api/v1/services¶

GET /api/v1/services/:key¶

POST /api/v1/services¶

DELETE /api/v1/services/:key¶

POST /api/v1/services/:key/reconnect¶

POST /api/v1/services/:key/sync¶

POST /api/v1/services/reconnect¶

Forwards¶

GET /api/v1/forwards¶

GET /api/v1/forwards/:key¶

GET /api/v1/forwards/:key/http¶

Namespaces¶

GET /api/v1/namespaces¶

GET /api/v1/namespaces/:key¶

POST /api/v1/namespaces¶

DELETE /api/v1/namespaces/:key¶

Kubernetes Discovery¶

GET /api/v1/kubernetes/contexts¶

GET /api/v1/kubernetes/namespaces¶

GET /api/v1/kubernetes/services¶

GET /api/v1/kubernetes/services/:namespace/:name¶

Metrics¶

GET /api/v1/metrics¶

GET /api/v1/metrics/services¶

GET /api/v1/metrics/services/:key¶

GET /api/v1/metrics/services/:key/history¶

Diagnostics¶

GET /api/v1/diagnostics¶

GET /api/v1/diagnostics/errors¶

GET /api/v1/diagnostics/services/:key¶

GET /api/v1/diagnostics/forwards/:key¶

GET /api/v1/diagnostics/network¶

Analysis¶

GET /api/v1/status¶

GET /api/v1/analyze¶

History¶

GET /api/v1/history/events¶

GET /api/v1/history/errors¶

GET /api/v1/history/reconnections¶

GET /api/v1/services/:key/history/reconnections¶

GET /api/v1/history/stats¶

Logs¶

GET /api/v1/logs¶

GET /api/v1/logs/stream¶

GET /api/v1/logs/system¶

DELETE /api/v1/logs/system¶

Events (SSE)¶

GET /api/v1/events¶

HTTP Traffic¶

GET /api/v1/services/:key/http¶

Error Codes¶

See Also¶