### Initial Authentication Setup

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Perform the initial setup for authentication by creating the first user. This requires a username and password. This endpoint should only be called once.

```bash
curl -X POST "http://localhost:4999/api/auth/setup" \
  -H "Content-Type: application/json" \
  -d '{ \
    "username": "admin", \
    "password": "securepassword123" \
  }'
```

--------------------------------

### Manage Docker Service Lifecycle

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Commands for starting, monitoring, and restarting the Portracker container.

```bash
# Start the service
docker-compose up -d

# View logs
docker-compose logs -f portracker

# Restart after configuration changes
docker-compose restart portracker
```

--------------------------------

### Deploy Portracker with Docker Run

Source: https://github.com/mostafa-wahied/portracker/blob/main/README.md

Alternative deployment method using CLI commands to start the proxy and the application container.

```sh
# Start the Docker proxy
docker run -d \
  --name portracker-docker-proxy \
  --restart unless-stopped \
  -p 2375:2375 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e CONTAINERS=1 \
  -e IMAGES=1 \
  -e INFO=1 \
  -e NETWORKS=1 \
  -e POST=0 \
  tecnativa/docker-socket-proxy:latest

# Start portracker
docker run -d \
  --name portracker \
  --restart unless-stopped \
  --pid host \
  --cap-add SYS_PTRACE \
  --cap-add SYS_ADMIN \
  --security-opt apparmor=unconfined \
  -p 4999:4999 \
  -v ./portracker-data:/data \
  -e DOCKER_HOST=tcp://localhost:2375 \
  mostafawahied/portracker:latest
```

--------------------------------

### GET /api/version

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Retrieves version information and metadata about the Portracker instance.

```APIDOC
## GET /api/version

### Description
Get version information for the Portracker application.

### Method
GET

### Endpoint
http://localhost:4999/api/version

### Response
#### Success Response (200)
- **version** (string) - Current application version
- **name** (string) - Application name
- **description** (string) - Brief description of the application

#### Response Example
{
  "version": "1.3.7",
  "name": "portracker",
  "description": "A multi-platform port-tracking dashboard"
}
```

--------------------------------

### Get All Notes for a Server

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Retrieve all documentation notes associated with a specific server. This is useful for auditing or reviewing port documentation.

```bash
curl -X GET "http://localhost:4999/api/notes?server_id=local"
```

--------------------------------

### Docker Run Command for Portracker Deployment

Source: https://github.com/mostafa-wahied/portracker/blob/main/README.md

This Docker Run command deploys portracker with the same configurations as the Docker Compose example. It includes necessary flags for restart policy, PID mode, capabilities, security options, port mapping, and volume mounts.

```sh
docker run -d \
  --name portracker \
  --restart unless-stopped \
  --pid host \
  --cap-add SYS_PTRACE \
  --cap-add SYS_ADMIN \
  --security-opt apparmor=unconfined \
  -p 4999:4999 \
  -v ./portracker-data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  mostafawahied/portracker:latest
```

--------------------------------

### GET /api/changelog

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Retrieves the application changelog.

```APIDOC
## GET /api/changelog

### Description
Get the application changelog.

### Method
GET

### Endpoint
http://localhost:4999/api/changelog
```

--------------------------------

### Get All Ports

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Retrieves all detected listening ports on the local system, including Docker container ports and system services. Enable debug mode for troubleshooting.

```bash
# Get all ports on the local system
curl -X GET "http://localhost:4999/api/ports"
```

```json
# Response structure
{
  "cached": false,
  "ttlMs": 3000,
  "data": [
    {
      "source": "docker",
      "owner": "nginx",
      "protocol": "tcp",
      "host_ip": "0.0.0.0",
      "host_port": 80,
      "target": "abc123def456:80",
      "container_id": "abc123def456789",
      "app_id": "nginx",
      "compose_project": "webstack",
      "internal": false
    },
    {
      "source": "system",
      "owner": "sshd",
      "protocol": "tcp",
      "host_ip": "0.0.0.0",
      "host_port": 22,
      "target": null,
      "container_id": null,
      "pids": [1234]
    }
  ]
}
```

```bash
# Enable debug mode for troubleshooting
curl -X GET "http://localhost:4999/api/ports?debug=true"
```

--------------------------------

### Get All Custom Service Names for a Server

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Retrieve all custom service names configured for a given server. This is useful for verifying or managing custom labels.

```bash
curl -X GET "http://localhost:4999/api/custom-service-names?server_id=local"
```

--------------------------------

### GET /api/containers/{id}/details

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Retrieves detailed information about a specific Docker container.

```APIDOC
## GET /api/containers/{id}/details

### Description
Get detailed information about a specific Docker container including health, ports, networks, and resource usage.

### Method
GET

### Endpoint
/api/containers/{id}/details

### Parameters
#### Path Parameters
- **id** (string) - Required - The container ID

#### Query Parameters
- **size** (boolean) - Optional - Include size information
- **stats** (boolean) - Optional - Include live stats
- **raw** (boolean) - Optional - Include raw Docker API response
- **export** (boolean) - Optional - Export as JSON file
```

--------------------------------

### Get Container Details

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Retrieves detailed information about a specific Docker container, including its state, network configuration, and resource usage. Supports optional parameters for size, live stats, raw Docker API response, and export.

```bash
# Get container details
curl -X GET "http://localhost:4999/api/containers/abc123def456/details"
```

```json
# Response
{
  "id": "abc123def456",
  "name": "nginx",
  "image": "nginx:latest",
  "command": "nginx -g daemon off;",
  "created": 1704067200,
  "createdISO": "2024-01-01T00:00:00.000Z",
  "state": "running",
  "health": "healthy",
  "restartCount": 0,
  "restartPolicy": "unless-stopped",
  "networkMode": "bridge",
  "ports": [
    {"host_ip": "0.0.0.0", "host_port": 80, "container_port": 80, "protocol": "tcp"}
  ],
  "exposedUnmapped": [],
  "labels": {"com.docker.compose.project": "webstack"},
  "mounts": [{"type": "bind", "source": "/data/nginx", "destination": "/etc/nginx"}],
  "networks": [{"name": "bridge", "ip": "172.17.0.5", "gateway": "172.17.0.1"}],
  "uptimeSeconds": 86400,
  "ephemeral": false
}
```

```bash
# Include size information
curl -X GET "http://localhost:4999/api/containers/abc123def456/details?size=true"
```

```bash
# Include live stats (CPU, memory usage)
curl -X GET "http://localhost:4999/api/containers/abc123def456/details?stats=true"
```

```bash
# Include raw Docker API response
curl -X GET "http://localhost:4999/api/containers/abc123def456/details?raw=true"
```

```bash
# Export as JSON file
curl -X GET "http://localhost:4999/api/containers/abc123def456/details?export=true" -o container-details.json
```

--------------------------------

### GET /api/ping

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Tests the reachability and status of a specific port.

```APIDOC
## GET /api/ping

### Description
Test the reachability and status of a specific port, detecting HTTP/HTTPS accessibility and service type.

### Method
GET

### Endpoint
/api/ping

### Parameters
#### Query Parameters
- **host_ip** (string) - Required - The IP address to check
- **host_port** (integer) - Required - The port number to check
- **owner** (string) - Optional - Owner identifier
- **internal** (boolean) - Optional - Whether to check internal container port
- **container_id** (string) - Optional - The container ID
- **server_id** (string) - Optional - The peer server ID

### Response
#### Success Response (200)
- **reachable** (boolean) - Reachability status
- **status** (string) - Status description
- **color** (string) - Status color indicator
- **title** (string) - Service title
- **protocol** (string) - Detected protocol
- **serviceType** (string) - Type of service
- **serviceName** (string) - Name of the service
- **description** (string) - Service description
- **hasWebUI** (boolean) - Whether the service has a web UI
```

--------------------------------

### Check Authentication Status

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Query the current authentication status of the dashboard. The response indicates whether authentication is enabled, if a setup is required, and the current authenticated state.

```bash
curl -X GET "http://localhost:4999/api/auth/status"
```

--------------------------------

### GET /api/health

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Retrieves the current health status of the application, including database connectivity and resource usage.

```APIDOC
## GET /api/health

### Description
Check the application health status including database connectivity and resource usage.

### Method
GET

### Endpoint
http://localhost:4999/api/health

### Response
#### Success Response (200)
- **status** (string) - Current health status
- **timestamp** (string) - ISO timestamp of the check
- **uptimeSeconds** (number) - Application uptime in seconds
- **memory** (object) - Memory usage statistics
- **database** (string) - Database connection status

#### Response Example
{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "uptimeSeconds": 86400,
  "memory": {"rss": "125.50MB"},
  "database": "connected"
}
```

--------------------------------

### Get All Ignored Ports

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Retrieve a list of all ports that are currently marked as ignored for a specific server. This helps in managing which ports are hidden from the dashboard.

```bash
curl -X GET "http://localhost:4999/api/ignores?server_id=local"
```

--------------------------------

### Manage Settings

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Allows retrieval and update of user settings, including theme, refresh interval, and port visibility. Also provides access to default settings and API key management for local server authentication.

```bash
# Get current settings
curl -X GET "http://localhost:4999/api/settings"
```

```bash
# Update settings
curl -X PUT "http://localhost:4999/api/settings" \
  -H "Content-Type: application/json" \
  -d '{
    "theme": "dark",
    "refreshInterval": 30000,
    "showInternalPorts": true
  }'
```

```bash
# Get default settings
curl -X GET "http://localhost:4999/api/settings/defaults"
```

```bash
# Generate API key for local server (for peer authentication)
curl -X POST "http://localhost:4999/api/settings/servers/local/api-key"
```

```json
# Response
{
  "success": true,
  "apiKey": "pt_abc123def456...",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "message": "API key generated successfully. This key will only be shown once."
}
```

```bash
# Get API key info (without revealing the key)
curl -X GET "http://localhost:4999/api/settings/servers/local/api-key"
```

```bash
# Revoke API key
curl -X DELETE "http://localhost:4999/api/settings/servers/local/api-key"
```

--------------------------------

### List All Servers

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Retrieves a list of all monitored servers, including local, peer, and unreachable servers, along with their configuration details. The response includes server ID, label, URL, type, platform, and reachability status.

```bash
# List all servers
curl -X GET "http://localhost:4999/api/servers"
```

```json
# Response
[
  {
    "id": "local",
    "label": "Local Server",
    "url": "http://localhost:4999",
    "type": "local",
    "platform_type": "docker",
    "unreachable": 0,
    "hasApiKey": true
  },
  {
    "id": "truenas-main",
    "label": "TrueNAS Server",
    "url": "http://192.168.1.100:4999",
    "type": "peer",
    "platform_type": "truenas",
    "parentId": null,
    "hasApiKey": false
  }
]
```

--------------------------------

### Add New Peer Server

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Adds a new peer server to the monitored list. Requires server ID, label, URL, type, platform type, and optionally a parent ID and API key for remote authentication.

```bash
# Add a new peer server
curl -X POST "http://localhost:4999/api/servers" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "homelab-01",
    "label": "Homelab Server",
    "url": "http://192.168.1.50:4999",
    "type": "peer",
    "platform_type": "docker",
    "parentId": null,
    "apiKey": "optional-remote-api-key"
  }'
```

--------------------------------

### Add or Update a Note for a Port

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Attach or update documentation notes for a specific port. Notes are associated with server, IP, port, protocol, and optionally container ID. Ensure all required fields are provided in the JSON payload.

```bash
curl -X POST "http://localhost:4999/api/notes" \
  -H "Content-Type: application/json" \
  -d '{ \
    "server_id": "local", \
    "host_ip": "0.0.0.0", \
    "host_port": 8080, \
    "protocol": "tcp", \
    "container_id": "abc123def456", \
    "internal": false, \
    "note": "Main web application - production traffic" \
  }'
```

--------------------------------

### Autoxpose Integration

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Manages the connection and display settings for autoxpose integration, allowing Portracker to show public URLs for exposed services. Supports checking status, connecting, disconnecting, retrieving services, and setting display modes and URL styles.

```bash
# Check autoxpose connection status
curl -X GET "http://localhost:4999/api/autoxpose/status"
```

```json
# Response
{
  "connected": true,
  "baseUrl": "http://autoxpose:3000",
  "servicesCount": 5,
  "displayMode": "url",
  "urlStyle": "compact"
}
```

```bash
# Connect to autoxpose instance
curl -X POST "http://localhost:4999/api/autoxpose/connect" \
  -H "Content-Type: application/json" \
  -d '{"url": "http://autoxpose:3000"}'
```

```bash
# Disconnect from autoxpose
curl -X POST "http://localhost:4999/api/autoxpose/disconnect"
```

```bash
# Get exposed services
curl -X GET "http://localhost:4999/api/autoxpose/services"
```

```bash
# Set display mode (url or badge)
curl -X PUT "http://localhost:4999/api/autoxpose/display-mode" \
  -H "Content-Type: application/json" \
  -d '{"mode": "badge"}'
```

```bash
# Set URL style (full or compact)
curl -X PUT "http://localhost:4999/api/autoxpose/url-style" \
  -H "Content-Type: application/json" \
  -d '{"style": "full"}'
```

--------------------------------

### Update Existing Server

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Updates an existing server's configuration, including its label, URL, type, and parent ID. The server ID must match an existing entry.

```bash
# Update an existing server
curl -X POST "http://localhost:4999/api/servers" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "homelab-01",
    "label": "Updated Homelab Server",
    "url": "http://192.168.1.51:4999",
    "type": "peer",
    "parentId": "local"
  }'
```

--------------------------------

### Docker Compose for Portracker Deployment

Source: https://github.com/mostafa-wahied/portracker/blob/main/README.md

Use this Docker Compose configuration to deploy portracker. Ensure 'pid: "host"' is set for accurate port detection and include 'cap_add' and 'security_opt' for required permissions. The volume mounts are crucial for data persistence and Docker socket access.

```yaml
services:
  portracker:
    image: mostafawahied/portracker:latest
    container_name: portracker
    restart: unless-stopped
    pid: "host"  # Required for port detection
    # Required permissions for system ports service namespace access
    cap_add:
      - SYS_PTRACE     # Linux hosts: read other PIDs' /proc entries
      - SYS_ADMIN      # Docker Desktop: allow namespace access for host ports (required for MacOS)
    security_opt:
      - apparmor:unconfined # Required for system ports
    volumes:
      # Required for data persistence
      - ./portracker-data:/data
      # Required for discovering services running in Docker
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "4999:4999"
    # environment:
      # Optional: For enhanced TrueNAS features
      # - TRUENAS_API_KEY=your-api-key-here
```

--------------------------------

### Login to the Dashboard

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Authenticate with the dashboard using username and password. A cookies file is used to maintain the session. Ensure the correct credentials are provided.

```bash
curl -X POST "http://localhost:4999/api/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{ \
    "username": "admin", \
    "password": "securepassword123" \
  }'
```

--------------------------------

### Configure Docker Compose Deployment

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Deployment configuration for Portracker. Requires host PID access and specific capabilities for port detection.

```yaml
# docker-compose.yml
services:
  portracker:
    image: mostafawahied/portracker:latest
    container_name: portracker
    restart: unless-stopped
    pid: "host"  # Required for port detection
    cap_add:
      - SYS_PTRACE     # Linux: read other PIDs' /proc entries
      - SYS_ADMIN      # Docker Desktop: namespace access
    security_opt:
      - apparmor:unconfined
    volumes:
      - ./portracker-data:/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "4999:4999"
    environment:
      # Authentication (optional)
      - ENABLE_AUTH=true
      - SESSION_SECRET=your-secret-here
      # TrueNAS integration (optional)
      - TRUENAS_API_KEY=your-truenas-api-key
      # Performance tuning
      - CACHE_TIMEOUT_MS=60000
      - INCLUDE_UDP=false
      - DEBUG=false
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:4999/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
```

--------------------------------

### Settings API Endpoints

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Endpoints for managing user preferences and server API keys.

```APIDOC
## GET /api/settings
### Description
Get current settings.

## PUT /api/settings
### Description
Update settings.

## GET /api/settings/defaults
### Description
Get default settings.

## POST /api/settings/servers/local/api-key
### Description
Generate API key for local server.

## GET /api/settings/servers/local/api-key
### Description
Get API key info.

## DELETE /api/settings/servers/local/api-key
### Description
Revoke API key.
```

--------------------------------

### Enable Authentication

Source: https://github.com/mostafa-wahied/portracker/blob/main/README.md

Secure the dashboard by enabling authentication and setting a session secret in your Docker Compose file.

```yaml
services:
  portracker:
    image: mostafawahied/portracker:latest
    environment:
      - ENABLE_AUTH=true
      - SESSION_SECRET=your-random-secret-here-change-this
```

--------------------------------

### POST /api/auth/login

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Authenticates a user session.

```APIDOC
## POST /api/auth/login

### Description
Logs in a user to establish a session.

### Method
POST

### Endpoint
/api/auth/login

### Request Body
- **username** (string) - Required
- **password** (string) - Required
```

--------------------------------

### Query Health and Version API Endpoints

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Use these cURL commands to verify service health, retrieve version information, or fetch the changelog.

```bash
# Health check endpoint
curl -X GET "http://localhost:4999/api/health"

# Response
{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "uptimeSeconds": 86400,
  "memory": {"rss": "125.50MB"},
  "database": "connected"
}

# Get version information
curl -X GET "http://localhost:4999/api/version"

# Response
{
  "version": "1.3.7",
  "name": "portracker",
  "description": "A multi-platform port-tracking dashboard"
}

# Get changelog
curl -X GET "http://localhost:4999/api/changelog"
```

--------------------------------

### Autoxpose Integration API

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Endpoints to manage autoxpose integration and display settings.

```APIDOC
## GET /api/autoxpose/status
### Description
Check autoxpose connection status.

## POST /api/autoxpose/connect
### Description
Connect to autoxpose instance.

## POST /api/autoxpose/disconnect
### Description
Disconnect from autoxpose.

## GET /api/autoxpose/services
### Description
Get exposed services.

## PUT /api/autoxpose/display-mode
### Description
Set display mode (url or badge).

## PUT /api/autoxpose/url-style
### Description
Set URL style (full or compact).
```

--------------------------------

### Batch Operations for Notes

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Perform multiple note operations (set or delete) in a single request. This is efficient for managing notes in bulk.

```bash
curl -X POST "http://localhost:4999/api/notes/batch" \
  -H "Content-Type: application/json" \
  -d '{ \
    "server_id": "local", \
    "operations": [ \
      {"action": "set", "host_ip": "0.0.0.0", "host_port": 3000, "protocol": "tcp", "note": "API server"}, \
      {"action": "set", "host_ip": "0.0.0.0", "host_port": 5432, "protocol": "tcp", "note": "PostgreSQL"}, \
      {"action": "delete", "host_ip": "0.0.0.0", "host_port": 8080, "protocol": "tcp"} \
    ] \
  }'
```

--------------------------------

### Configure TrueNAS API Key

Source: https://github.com/mostafa-wahied/portracker/blob/main/README.md

Add the TrueNAS API key to your Docker Compose configuration to enable enhanced data collection.

```yaml
environment:
  - TRUENAS_API_KEY=your-api-key-here
```

--------------------------------

### Port Scanning API

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

The `/api/ports` endpoint scans the local system and returns all detected listening ports, including Docker container ports, system services, and their metadata.

```APIDOC
## GET /api/ports

### Description
Scans the local system and returns all detected listening ports, including Docker container ports, system services, and their metadata.

### Method
GET

### Endpoint
/api/ports

#### Query Parameters
- **debug** (boolean) - Optional - Enable debug mode for troubleshooting.

### Response
#### Success Response (200)
- **cached** (boolean) - Indicates if the response is from cache.
- **ttlMs** (integer) - Time-to-live in milliseconds for the cached response.
- **data** (array) - An array of detected ports.
  - **source** (string) - The source of the port (e.g., "docker", "system").
  - **owner** (string) - The owner or name of the process/service.
  - **protocol** (string) - The network protocol (e.g., "tcp").
  - **host_ip** (string) - The host IP address the port is listening on.
  - **host_port** (integer) - The host port number.
  - **target** (string) - The target identifier (e.g., container ID and port).
  - **container_id** (string) - The ID of the Docker container, if applicable.
  - **app_id** (string) - The application ID.
  - **compose_project** (string) - The Docker Compose project name.
  - **internal** (boolean) - Indicates if the port is internal to a container.
  - **pids** (array of integers) - Process IDs associated with the port (for system services).

### Request Example
```bash
curl -X GET "http://localhost:4999/api/ports"
```

### Response Example
```json
{
  "cached": false,
  "ttlMs": 3000,
  "data": [
    {
      "source": "docker",
      "owner": "nginx",
      "protocol": "tcp",
      "host_ip": "0.0.0.0",
      "host_port": 80,
      "target": "abc123def456:80",
      "container_id": "abc123def456789",
      "app_id": "nginx",
      "compose_project": "webstack",
      "internal": false
    },
    {
      "source": "system",
      "owner": "sshd",
      "protocol": "tcp",
      "host_ip": "0.0.0.0",
      "host_port": 22,
      "target": null,
      "container_id": null,
      "pids": [1234]
    }
  ]
}
```
```

--------------------------------

### Scan Local Server

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Performs a comprehensive scan of the local server, returning system information, applications, ports, and virtual machines. Options include including UDP ports and disabling cache.

```bash
# Scan the local server
curl -X GET "http://localhost:4999/api/servers/local/scan"
```

```json
# Response structure for local server
{
  "platform": "docker",
  "platformName": "Docker",
  "systemInfo": {
    "type": "system",
    "hostname": "docker-host",
    "version": "24.0.7",
    "platform": "docker",
    "docker_version": "24.0.7",
    "containers_running": 15,
    "containers_total": 20,
    "images": 45,
    "kernel_version": "6.1.0",
    "operating_system": "Ubuntu 22.04",
    "ncpu": 8,
    "memory": 34359738368
  },
  "applications": [
    {
      "type": "application",
      "id": "abc123def456",
      "name": "nginx",
      "status": "running",
      "image": "nginx:latest",
      "platform": "docker",
      "platform_data": {
        "type": "container",
        "ports": [{"host_ip": "0.0.0.0", "host_port": 80, "container_port": 80, "protocol": "tcp"}]
      }
    }
  ],
  "ports": [...],
  "vms": []
}
```

```bash
# Scan with options
curl -X GET "http://localhost:4999/api/servers/local/scan?includeUdp=true&disableCache=true"
```

```bash
# Scan a peer server (proxied through local instance)
curl -X GET "http://localhost:4999/api/servers/peer-server-id/scan"
```

--------------------------------

### POST /api/servers/local/generate-port

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Generates an unused port for the local server.

```APIDOC
## POST /api/servers/local/generate-port

### Description
Generates an unused port for the local server.

### Method
POST

### Endpoint
/api/servers/local/generate-port

### Response
#### Success Response (200)
- **port** (integer) - The generated port number
- **meta** (object) - Metadata about the generation process
```

--------------------------------

### Set a Custom Service Name

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Assign a custom name to a service running on a specific port. This overrides auto-detected service names for better identification. Include original name and container ID if applicable.

```bash
curl -X POST "http://localhost:4999/api/custom-service-names" \
  -H "Content-Type: application/json" \
  -d '{ \
    "server_id": "local", \
    "host_ip": "0.0.0.0", \
    "host_port": 3000, \
    "protocol": "tcp", \
    "custom_name": "Production API", \
    "original_name": "node", \
    "container_id": "abc123def456", \
    "internal": false \
  }'
```

--------------------------------

### Batch Operations for Custom Service Names

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Perform multiple custom service name operations (set or delete) in a single request. This allows for efficient bulk management of service labels.

```bash
curl -X POST "http://localhost:4999/api/custom-service-names/batch" \
  -H "Content-Type: application/json" \
  -d '{ \
    "server_id": "local", \
    "operations": [ \
      {"action": "set", "host_ip": "0.0.0.0", "host_port": 3000, "protocol": "tcp", "custom_name": "API Server"}, \
      {"action": "set", "host_ip": "0.0.0.0", "host_port": 5432, "protocol": "tcp", "custom_name": "Main Database"}, \
      {"action": "delete", "host_ip": "0.0.0.0", "host_port": 8080, "protocol": "tcp"} \
    ] \
  }'
```

--------------------------------

### Deploy Portracker with Docker Proxy

Source: https://github.com/mostafa-wahied/portracker/blob/main/README.md

Run Portracker securely by restricting Docker API access to read-only operations via a proxy container.

```yaml
services:
  docker-proxy:
    image: tecnativa/docker-socket-proxy:latest
    container_name: portracker-docker-proxy
    restart: unless-stopped
    environment:
      - CONTAINERS=1
      - IMAGES=1
      - INFO=1
      - NETWORKS=1
      - POST=0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "2375:2375"

  portracker:
    image: mostafawahied/portracker:latest
    container_name: portracker
    restart: unless-stopped
    pid: "host"
    cap_add:
      - SYS_PTRACE
      - SYS_ADMIN
    security_opt:
      - apparmor:unconfined
    volumes:
      - ./portracker-data:/data
    ports:
      - "4999:4999"
    environment:
      - DOCKER_HOST=tcp://docker-proxy:2375
    depends_on:
      - docker-proxy
```

--------------------------------

### Delete a Note by Setting an Empty Note

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

To delete a note, send a POST request to the notes endpoint with an empty string for the 'note' field. This effectively removes the documentation associated with the specified port.

```bash
curl -X POST "http://localhost:4999/api/notes" \
  -H "Content-Type: application/json" \
  -d '{ \
    "server_id": "local", \
    "host_ip": "0.0.0.0", \
    "host_port": 8080, \
    "protocol": "tcp", \
    "note": "" \
  }'
```

--------------------------------

### Check Port Status

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Tests the reachability and status of a specific port on a given host IP. Can detect HTTP/HTTPS accessibility and service type. Requires host IP, port, and owner.

```bash
# Check port status
curl -X GET "http://localhost:4999/api/ping?host_ip=0.0.0.0&host_port=8080&owner=nginx"
```

```json
# Response for accessible web service
{
  "reachable": true,
  "status": "accessible",
  "color": "green",
  "title": "Web Server - Web service accessible",
  "protocol": "https",
  "serviceType": "web",
  "serviceName": "Web Server",
  "description": "Web server",
  "hasWebUI": true
}
```

```bash
# Check internal container port
curl -X GET "http://localhost:4999/api/ping?host_ip=0.0.0.0&host_port=3000&internal=true&container_id=abc123def456"
```

```json
# Response for container health-based status
{
  "reachable": true,
  "status": "reachable",
  "color": "green",
  "title": "Container running",
  "protocol": null,
  "serviceType": "service",
  "hasWebUI": false
}
```

```bash
# Check port on peer server
curl -X GET "http://localhost:4999/api/ping?host_ip=192.168.1.50&host_port=80&server_id=peer-id"
```

--------------------------------

### Generate Unused Port for Local Server

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Use this endpoint to request an unused port for a local server. The response includes the allocated port and metadata about the port scanning process.

```bash
curl -X POST "http://localhost:4999/api/servers/local/generate-port"
```

--------------------------------

### POST /api/auth/logout

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Logs the current user out of the system.

```APIDOC
## POST /api/auth/logout

### Description
Logs the current user out of the system.

### Method
POST

### Endpoint
/api/auth/logout
```

--------------------------------

### Server Management API

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

The servers API allows managing monitored servers including local, peer, and unreachable servers with hierarchical parent-child relationships.

```APIDOC
## Server Management API

### Description
Manages monitored servers, including local, peer, and unreachable servers, with support for hierarchical parent-child relationships.

### Method
GET, POST, DELETE

### Endpoint
/api/servers

#### GET /api/servers

##### Description
Lists all managed servers.

##### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the server.
- **label** (string) - Human-readable label for the server.
- **url** (string) - The URL to access the Portracker instance on the server.
- **type** (string) - Type of server (e.g., "local", "peer").
- **platform_type** (string) - The platform type of the server (e.g., "docker", "truenas").
- **unreachable** (integer) - Count of unreachable status.
- **hasApiKey** (boolean) - Indicates if an API key is configured for the server.
- **parentId** (string) - The ID of the parent server in a hierarchy, if applicable.

##### Response Example
```json
[
  {
    "id": "local",
    "label": "Local Server",
    "url": "http://localhost:4999",
    "type": "local",
    "platform_type": "docker",
    "unreachable": 0,
    "hasApiKey": true
  },
  {
    "id": "truenas-main",
    "label": "TrueNAS Server",
    "url": "http://192.168.1.100:4999",
    "type": "peer",
    "platform_type": "truenas",
    "parentId": null,
    "hasApiKey": false
  }
]
```

#### POST /api/servers

##### Description
Adds a new peer server or updates an existing server.

##### Request Body
- **id** (string) - Required - Unique identifier for the server.
- **label** (string) - Required - Human-readable label for the server.
- **url** (string) - Required - The URL to access the Portracker instance on the server.
- **type** (string) - Required - Type of server (e.g., "peer").
- **platform_type** (string) - Required - The platform type of the server (e.g., "docker").
- **parentId** (string) - Optional - The ID of the parent server in a hierarchy.
- **apiKey** (string) - Optional - API key for authentication with the remote Portracker instance.

##### Request Example (Add New Server)
```bash
curl -X POST "http://localhost:4999/api/servers" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "homelab-01",
    "label": "Homelab Server",
    "url": "http://192.168.1.50:4999",
    "type": "peer",
    "platform_type": "docker",
    "parentId": null,
    "apiKey": "optional-remote-api-key"
  }'
```

##### Request Example (Update Server)
```bash
curl -X POST "http://localhost:4999/api/servers" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "homelab-01",
    "label": "Updated Homelab Server",
    "url": "http://192.168.1.51:4999",
    "type": "peer",
    "parentId": "local"
  }'
```

#### DELETE /api/servers/:id

##### Description
Deletes a server from the managed list.

##### Endpoint
/api/servers/:id

##### Path Parameters
- **id** (string) - Required - The ID of the server to delete.

##### Request Example
```bash
curl -X DELETE "http://localhost:4999/api/servers/homelab-01"
```
```

--------------------------------

### POST /api/notes

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Adds, updates, or deletes a note associated with a specific port.

```APIDOC
## POST /api/notes

### Description
Adds or updates a note for a specific port. Setting an empty note string deletes the existing note.

### Method
POST

### Endpoint
/api/notes

### Request Body
- **server_id** (string) - Required
- **host_ip** (string) - Required
- **host_port** (integer) - Required
- **protocol** (string) - Required
- **container_id** (string) - Optional
- **internal** (boolean) - Optional
- **note** (string) - Required
```

--------------------------------

### Logout User

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Logs out the currently authenticated user. Requires an active session stored in cookies.txt.

```bash
curl -X POST "http://localhost:4999/api/auth/logout" -b cookies.txt
```

--------------------------------

### Server Scan API

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

The `/api/servers/:id/scan` endpoint performs a scan of a specific server, returning system information, applications, ports, and virtual machines. For peer servers, requests are proxied to the remote instance.

```APIDOC
## GET /api/servers/:id/scan

### Description
Performs a comprehensive scan of a specific server, returning system information, applications, ports, and virtual machines. For peer servers, requests are proxied to the remote instance.

### Method
GET

### Endpoint
/api/servers/:id/scan

#### Path Parameters
- **id** (string) - Required - The ID of the server to scan (e.g., "local" for the local server).

#### Query Parameters
- **includeUdp** (boolean) - Optional - Whether to include UDP ports in the scan.
- **disableCache** (boolean) - Optional - Whether to disable caching for the scan results.

### Response
#### Success Response (200)
- **platform** (string) - The platform type of the server (e.g., "docker", "truenas").
- **platformName** (string) - The human-readable name of the platform.
- **systemInfo** (object) - Information about the server's system.
  - **type** (string) - Type of system info (e.g., "system").
  - **hostname** (string) - The hostname of the server.
  - **version** (string) - The version of the platform (e.g., Docker version).
  - **platform** (string) - The operating system platform.
  - **docker_version** (string) - The Docker engine version, if applicable.
  - **containers_running** (integer) - Number of running containers.
  - **containers_total** (integer) - Total number of containers.
  - **images** (integer) - Number of Docker images.
  - **kernel_version** (string) - The kernel version.
  - **operating_system** (string) - The operating system name and version.
  - **ncpu** (integer) - Number of CPU cores.
  - **memory** (integer) - Total system memory in bytes.
- **applications** (array) - List of detected applications.
  - **type** (string) - Type of the entry (e.g., "application").
  - **id** (string) - Unique identifier for the application.
  - **name** (string) - Name of the application.
  - **status** (string) - Current status of the application (e.g., "running").
  - **image** (string) - The Docker image used for the application.
  - **platform** (string) - The platform where the application is running.
  - **platform_data** (object) - Platform-specific data.
    - **type** (string) - Type of platform data (e.g., "container").
    - **ports** (array) - List of ports exposed by the application.
      - **host_ip** (string) - Host IP address.
      - **host_port** (integer) - Host port number.
      - **container_port** (integer) - Container port number.
      - **protocol** (string) - Network protocol.
- **ports** (array) - List of detected ports on the server.
- **vms** (array) - List of detected virtual machines.

### Request Example
```bash
# Scan the local server
curl -X GET "http://localhost:4999/api/servers/local/scan"

# Scan with options
curl -X GET "http://localhost:4999/api/servers/local/scan?includeUdp=true&disableCache=true"

# Scan a peer server (proxied through local instance)
curl -X GET "http://localhost:4999/api/servers/peer-server-id/scan"
```

### Response Example
```json
{
  "platform": "docker",
  "platformName": "Docker",
  "systemInfo": {
    "type": "system",
    "hostname": "docker-host",
    "version": "24.0.7",
    "platform": "docker",
    "docker_version": "24.0.7",
    "containers_running": 15,
    "containers_total": 20,
    "images": 45,
    "kernel_version": "6.1.0",
    "operating_system": "Ubuntu 22.04",
    "ncpu": 8,
    "memory": 34359738368
  },
  "applications": [
    {
      "type": "application",
      "id": "abc123def456",
      "name": "nginx",
      "status": "running",
      "image": "nginx:latest",
      "platform": "docker",
      "platform_data": {
        "type": "container",
        "ports": [{"host_ip": "0.0.0.0", "host_port": 80, "container_port": 80, "protocol": "tcp"}]
      }
    }
  ],
  "ports": [...],
  "vms": []
}
```
```

--------------------------------

### Generate Port for Peer Server

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

This endpoint generates an unused port specifically for a peer server, identified by its peer ID.

```bash
curl -X POST "http://localhost:4999/api/servers/peer-id/generate-port"
```

--------------------------------

### Delete Server

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Removes a server from the monitored list using its unique ID.

```bash
# Delete a server
curl -X DELETE "http://localhost:4999/api/servers/homelab-01"
```

--------------------------------

### Ignore a Port

Source: https://context7.com/mostafa-wahied/portracker/llms.txt

Mark a specific port as ignored to hide it from the dashboard view. This does not remove the port from scans. Ensure 'ignored' is set to true.

```bash
curl -X POST "http://localhost:4999/api/ignores" \
  -H "Content-Type: application/json" \
  -d '{ \
    "server_id": "local", \
    "host_ip": "0.0.0.0", \
    "host_port": 22, \
    "protocol": "tcp", \
    "ignored": true, \
    "container_id": null, \
    "internal": false \
  }'
```