Skip to main content
GET
/
api
/
connections
Get Connections
curl --request GET \
  --url https://api.example.com/api/connections
{
  "listeners": [
    {
      "pid": 123,
      "processName": "<string>",
      "serviceLabel": "<string>",
      "containerName": "<string>",
      "processIconType": "<string>",
      "address": "<string>",
      "addressDescription": "<string>",
      "port": 123,
      "cmd": "<string>"
    }
  ],
  "connections": [
    {
      "fromPid": 123,
      "fromProcessName": "<string>",
      "fromAddress": "<string>",
      "fromPort": 123,
      "toAddress": "<string>",
      "toPort": 123,
      "toLabel": "<string>"
    }
  ],
  "error": "<string>"
}

​
Endpoint

GET /api/connections
Retrieves comprehensive information about all listening ports and established network connections on the system. This endpoint uses the ss command internally to gather network statistics.

​
Request

No parameters required. This is a simple GET request. 
curl http://localhost:3000/api/connections

​
Response

Returns a JSON object containing two arrays: listeners and connections.
​
listeners
Listener[]
required
Array of all listening ports on the system
​
connections
Connection[]
required
Array of all established TCP connections

​
Example Response

{
  "listeners": [
    {
      "pid": 1234,
      "processName": "node",
      "serviceLabel": "psys",
      "address": "0.0.0.0",
      "addressDescription": "Listening on all IPv4 interfaces",
      "port": 3000,
      "processIconType": "psys",
      "cmd": "node /home/user/.next/server/app.js"
    },
    {
      "pid": 5678,
      "processName": "redis-server",
      "serviceLabel": "Redis",
      "address": "127.0.0.1",
      "addressDescription": "Localhost only (IPv4)",
      "port": 6379,
      "processIconType": "redis",
      "cmd": "redis-server *:6379"
    },
    {
      "pid": 9012,
      "processName": "docker-proxy",
      "serviceLabel": "postgres-db",
      "containerName": "postgres-db",
      "address": "0.0.0.0",
      "addressDescription": "Listening on all IPv4 interfaces",
      "port": 5432,
      "processIconType": "postgres"
    }
  ],
  "connections": [
    {
      "fromPid": 1234,
      "fromProcessName": "node",
      "fromAddress": "127.0.0.1",
      "fromPort": 45678,
      "toAddress": "127.0.0.1",
      "toPort": 6379,
      "toLabel": "Redis"
    },
    {
      "fromPid": 1234,
      "fromProcessName": "node",
      "fromAddress": "127.0.0.1",
      "fromPort": 45679,
      "toAddress": "127.0.0.1",
      "toPort": 5432,
      "toLabel": "postgres-db"
    }
  ]
}

​
Error Responses

​
error
string
Error message describing what went wrong

​
500 Internal Server Error

Returned when the system fails to retrieve connection data (e.g., ss command not available or permission issues). 
{
  "error": "Failed to get connections"
}

​
Implementation Notes

  • The endpoint is configured with dynamic = "force-dynamic" to ensure fresh data on every request
  • Uses the ss (socket statistics) command internally to gather network information
  • Automatically detects Docker containers and enriches listener data with container names
  • Provides intelligent service detection for common ports (Redis on 6379, PostgreSQL on 5432, etc.)
  • Excludes the psys application itself from appearing as a generic listener