API Reference

The tlsproxy REST API lets you inspect and control a running tlsproxy instance programmatically. Use these endpoints to query proxy status, manage backend targets, reload configuration, and retrieve connection metrics — all without restarting the process. This reference covers every available endpoint, its accepted parameters, and the responses you can expect.

Most endpoints accept parameters either as URL path segments or as a JSON request body. The table below lists parameters that appear across multiple endpoints; endpoint-specific parameters are documented in the relevant example sections.

All successful responses use HTTP 2xx status codes and return a JSON object. The exact shape depends on the endpoint:

• GET endpoints return a JSON object or array representing the requested resource(s). A 200 OK indicates the resource was found and returned.
• POST endpoints (create operations) return 201 Created with a JSON object representing the newly created resource, including its system-assigned id.
• PUT / PATCH endpoints (update operations) return 200 OK with the full updated resource object.
• DELETE endpoints return 204 No Content with an empty body on success.
• POST /api/v1/reload returns 200 OK with a confirmation message.

All JSON responses include a top-level status field set to "ok" on success. Resource collections are wrapped in a data array. Timestamps are returned in ISO 8601 format (UTC).

tlsproxy's API uses standard HTTP status codes to signal errors. Every error response body is a JSON object with status: "error" and a human-readable message field.

The following examples use curl. Replace https://localhost:8443 with the address and port where your tlsproxy management API is listening, and replace YOUR_API_TOKEN with your configured token.

Check proxy health

Confirm that tlsproxy is running and the API is reachable.

curl -s \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://localhost:8443/api/v1/health

Expected response (200 OK):

{
  "status": "ok",
  "uptime_seconds": 3821,
  "version": "tlsproxy"
}

List all registered backends

Retrieve every backend target currently known to the proxy.

curl -s \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://localhost:8443/api/v1/backends

Expected response (200 OK):

{
  "status": "ok",
  "data": [
    {
      "id": "backend-01",
      "address": "127.0.0.1:8080",
      "listen_port": 443,
      "enabled": true,
      "created_at": "2024-03-15T10:22:00Z"
    }
  ]
}

Register a new backend

Add a plaintext backend service that tlsproxy should forward decrypted traffic to.

curl -s -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "127.0.0.1:9090",
    "listen_port": 8443,
    "timeout": 30
  }' \
  https://localhost:8443/api/v1/backends

Expected response (201 Created):

{
  "status": "ok",
  "data": {
    "id": "backend-02",
    "address": "127.0.0.1:9090",
    "listen_port": 8443,
    "enabled": true,
    "timeout": 30,
    "created_at": "2024-03-15T11:05:42Z"
  }
}

Update a backend

Change an existing backend's target address without removing and re-adding it.

curl -s -X PUT \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"address": "127.0.0.1:9091", "enabled": true}' \
  https://localhost:8443/api/v1/backends/backend-02

Expected response (200 OK):

{
  "status": "ok",
  "data": {
    "id": "backend-02",
    "address": "127.0.0.1:9091",
    "listen_port": 8443,
    "enabled": true,
    "timeout": 30,
    "updated_at": "2024-03-15T11:20:10Z"
  }
}

Disable a backend without deleting it

Take a backend offline temporarily by setting enabled to false.

curl -s -X PATCH \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}' \
  https://localhost:8443/api/v1/backends/backend-02

Expected response (200 OK):

{
  "status": "ok",
  "data": {
    "id": "backend-02",
    "enabled": false,
    "updated_at": "2024-03-15T11:25:00Z"
  }
}

Delete a backend

Permanently remove a backend target.

curl -s -X DELETE \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://localhost:8443/api/v1/backends/backend-02

Expected response: 204 No Content with an empty body.

Reload configuration

Instruct tlsproxy to reload its configuration file from disk without a full process restart. In-flight connections are not interrupted.

curl -s -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://localhost:8443/api/v1/reload

Expected response (200 OK):

{
  "status": "ok",
  "message": "Configuration reloaded successfully."
}

Retrieve connection metrics

Fetch runtime counters such as active connections and total bytes proxied.

curl -s \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://localhost:8443/api/v1/metrics

Expected response (200 OK):

{
  "status": "ok",
  "data": {
    "active_connections": 14,
    "total_connections": 10482,
    "bytes_received": 5368709120,
    "bytes_sent": 4831838208,
    "uptime_seconds": 3821
  }
}

• API versioning: All endpoints are prefixed with /api/v1/. Future breaking changes will be introduced under a new version prefix, leaving v1 behaviour intact.
• Authentication: Every request must include an Authorization: Bearer <token> header. The token is configured at proxy startup; the API does not provide a token-issuance endpoint. Storing your token in an environment variable (e.g., TLSPROXY_TOKEN) and referencing it in scripts is recommended over hard-coding.
• TLS on the management API itself: The management API is served over TLS. You must either provide a trusted certificate or pass -k / --insecure to curl in development environments. Do not use --insecure in production.
• Configuration file vs. API state: Changes made via the API take effect immediately in memory but are not automatically written back to the configuration file on disk. If you restart tlsproxy without saving your changes, the proxy reverts to the last configuration file state. Use POST /api/v1/reload after editing the file to synchronise, or maintain your source of truth in the file.
• Reload behaviour: POST /api/v1/reload parses and validates the configuration before applying it. If validation fails, the old configuration remains active and the endpoint returns 422 Unprocessable Entity with a description of the validation error. Existing connections are never dropped during a successful reload.
• Concurrent modifications: The API does not implement optimistic locking. If multiple clients modify the same backend concurrently, the last write wins. Coordinate changes through your deployment tooling to avoid race conditions.
• Metrics precision: Values in /api/v1/metrics are in-memory counters and reset to zero when the tlsproxy process restarts. For durable metrics storage, consider scraping this endpoint with a metrics collector such as Prometheus and persisting the data externally.