Documentation > API Reference > Package Management

Package Management API

Cross-platform package management for installing, updating, and removing software packages across your infrastructure.

Overview

The Package Management API provides unified access to various package managers across different operating systems including apt (Debian/Ubuntu), yum/dnf (RHEL/CentOS/Fedora), pkg (FreeBSD), pkg_add (OpenBSD), pkgin (NetBSD), and Homebrew (macOS).

Package Discovery

GET /api/v1/packages/summary

Get package summary statistics across all managed hosts.

🔒 Authentication Required

Response (200 OK)

[
  {
    "os_name": "Ubuntu",
    "os_version": "22.04",
    "host_count": 25,
    "total_packages": 46250,
    "unique_packages": 1847,
    "package_managers": ["apt"]
  },
  {
    "os_name": "CentOS",
    "os_version": "8",
    "host_count": 15,
    "total_packages": 22500,
    "unique_packages": 1203,
    "package_managers": ["yum", "dnf"]
  }
]
GET /api/v1/packages/managers

Get list of supported package managers.

🔒 Authentication Required

Response (200 OK)

[
  "apt",
  "yum",
  "dnf",
  "pkg",
  "pkg_add",
  "brew",
  "snap",
  "flatpak"
]
GET /api/v1/packages/os-versions

Get supported operating system versions for package management.

🔒 Authentication Required

Response (200 OK)

[
  {
    "os_name": "Ubuntu",
    "versions": ["20.04", "22.04", "24.04"],
    "default_manager": "apt"
  },
  {
    "os_name": "FreeBSD",
    "versions": ["13.0", "13.1", "14.0"],
    "default_manager": "pkg"
  }
]

Package Search

GET /api/v1/packages/search

Search for packages across your infrastructure.

🔒 Authentication Required

Query Parameters

  • q (string) - Search query (package name or description)
  • os (string, optional) - Filter by operating system
  • version (string, optional) - Filter by OS version
  • manager (string, optional) - Filter by package manager
  • limit (integer, optional) - Maximum results (default: 50)
  • offset (integer, optional) - Results offset (default: 0)

Response (200 OK)

[
  {
    "name": "nginx",
    "version": "1.18.0-6ubuntu14.4",
    "description": "high performance web server",
    "architecture": "amd64",
    "manager": "apt",
    "os_name": "Ubuntu",
    "os_version": "22.04",
    "installed_on_hosts": 15,
    "available_on_hosts": 32
  }
]

Example

curl -X GET "https://your-server.example.com/api/v1/packages/search?q=nginx&os=Ubuntu" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"
GET /api/v1/packages/search/count

Get count of packages matching search criteria.

🔒 Authentication Required

Query Parameters

  • q (string) - Search query
  • os (string, optional) - Filter by operating system
  • version (string, optional) - Filter by OS version

Response (200 OK)

{
  "total_matches": 127,
  "by_os": {
    "Ubuntu": 85,
    "CentOS": 42
  },
  "by_manager": {
    "apt": 85,
    "yum": 42
  }
}
GET /api/v1/packages/by-manager/{manager_name}

Get packages available through a specific package manager.

🔒 Authentication Required

Path Parameters

  • manager_name (string) - Package manager name (apt, yum, dnf, etc.)

Query Parameters

  • limit (integer, optional) - Maximum results (default: 100)
  • offset (integer, optional) - Results offset (default: 0)

Response (200 OK)

[
  {
    "name": "apache2",
    "version": "2.4.52-1ubuntu4.7",
    "description": "Apache HTTP Server",
    "architecture": "amd64",
    "size": "1,432 KB",
    "section": "httpd"
  }
]

Package Installation

POST /api/v1/fleet/agent/{hostname}/install-package

Install a package on a specific host.

🔒 Authentication Required

Path Parameters

  • hostname (string) - Target hostname

Request Body

{
  "package_name": "nginx",
  "version": "latest",
  "manager": "apt",
  "force": false,
  "assume_yes": true
}

Response (200 OK)

{
  "execution_id": "uuid",
  "status": "initiated",
  "message": "Package installation started",
  "estimated_time": "2-5 minutes"
}

Example

curl -X POST "https://your-server.example.com/api/v1/fleet/agent/web-01/install-package" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "package_name": "nginx",
       "version": "latest",
       "assume_yes": true
     }'

Package Uninstallation

POST /api/packages/uninstall/{host_id}

Uninstall one or more packages from a specific host using UUID-based tracking.

🔒 Authentication Required

Path Parameters

  • host_id (string) - UUID of the target host

Request Body

{
  "package_names": ["nginx", "apache2-utils"],
  "package_manager": "apt",
  "force": false,
  "assume_yes": true,
  "remove_dependencies": false
}

Request Parameters

  • package_names (array) - List of package names to uninstall
  • package_manager (string, optional) - Specific package manager to use ("auto" for automatic detection)
  • force (boolean, optional) - Force uninstallation (default: false)
  • assume_yes (boolean, optional) - Assume yes to all prompts (default: true)
  • remove_dependencies (boolean, optional) - Remove unused dependencies (default: false)

Response (200 OK)

{
  "success": true,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Successfully queued 2 packages for uninstallation",
  "packages": ["nginx", "apache2-utils"],
  "host_id": "uuid",
  "estimated_time": "2-5 minutes",
  "operation_type": "uninstall"
}

Response (400 Bad Request)

{
  "detail": "No packages specified for uninstallation"
}

Response (404 Not Found)

{
  "detail": "Host not found"
}

Example

curl -X POST "https://your-server.example.com/api/packages/uninstall/550e8400-e29b-41d4-a716-446655440000" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "package_names": ["nginx", "apache2-utils"],
       "package_manager": "auto",
       "assume_yes": true
     }'
GET /api/packages/operations/{host_id}

Get package operation history for a specific host, including both installations and uninstallations.

🔒 Authentication Required

Path Parameters

  • host_id (string) - UUID of the target host

Query Parameters

  • operation_type (string, optional) - Filter by operation type: "install", "uninstall", or "all" (default: "all")
  • status (string, optional) - Filter by status: "pending", "in_progress", "completed", "failed"
  • limit (integer, optional) - Maximum results (default: 50)
  • offset (integer, optional) - Results offset (default: 0)

Response (200 OK)

[
  {
    "installation_id": "550e8400-e29b-41d4-a716-446655440000",
    "package_name": "nginx",
    "package_manager": "apt",
    "operation_type": "uninstall",
    "status": "completed",
    "requested_by": "admin@example.com",
    "requested_at": "2024-01-01T10:00:00Z",
    "started_at": "2024-01-01T10:01:00Z",
    "completed_at": "2024-01-01T10:03:00Z",
    "success": true,
    "error_message": null,
    "installation_log": "Reading package lists...\nRemoving nginx (1.18.0-6ubuntu14.4) ...\nProcessing triggers..."
  },
  {
    "installation_id": "660e8400-e29b-41d4-a716-446655440001",
    "package_name": "apache2",
    "package_manager": "apt",
    "operation_type": "install",
    "status": "completed",
    "requested_by": "admin@example.com",
    "requested_at": "2024-01-01T09:00:00Z",
    "started_at": "2024-01-01T09:01:00Z",
    "completed_at": "2024-01-01T09:05:00Z",
    "success": true,
    "error_message": null,
    "installation_log": "Reading package lists...\nInstalling apache2 (2.4.52-1ubuntu4.7) ...\nProcessing triggers..."
  }
]

Example

curl -X GET "https://your-server.example.com/api/packages/operations/550e8400-e29b-41d4-a716-446655440000?operation_type=uninstall&status=completed" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"

Package Updates

GET /api/v1/updates/

Get available package updates across all hosts.

🔒 Authentication Required

Response (200 OK)

[
  {
    "host_id": "uuid",
    "hostname": "web-01",
    "updates_available": 15,
    "security_updates": 3,
    "updates": [
      {
        "package": "nginx",
        "current_version": "1.18.0-6ubuntu14.3",
        "available_version": "1.18.0-6ubuntu14.4",
        "type": "security",
        "size": "1.2 MB"
      }
    ],
    "last_checked": "2024-01-01T12:00:00Z"
  }
]
GET /api/v1/updates/{host_id}

Get available updates for a specific host.

🔒 Authentication Required

Path Parameters

  • host_id (string) - UUID of the target host

Response (200 OK)

{
  "host_id": "uuid",
  "hostname": "web-01",
  "updates_available": 15,
  "security_updates": 3,
  "updates": [
    {
      "package": "linux-image-generic",
      "current_version": "5.15.0.91.88",
      "available_version": "5.15.0.92.89",
      "type": "security",
      "size": "12.5 MB",
      "description": "Linux kernel security update"
    }
  ],
  "last_checked": "2024-01-01T12:00:00Z"
}
POST /api/v1/updates/execute

Execute package updates on specified hosts.

🔒 Authentication Required

Request Body

{
  "host_ids": ["uuid1", "uuid2"],
  "update_type": "security",
  "packages": ["nginx", "apache2"],
  "reboot_if_required": false,
  "schedule_time": null
}

Response (200 OK)

{
  "batch_id": "uuid",
  "total_hosts": 2,
  "status": "initiated",
  "estimated_completion": "2024-01-01T12:30:00Z",
  "results": [
    {
      "host_id": "uuid1",
      "hostname": "web-01",
      "status": "started",
      "execution_id": "uuid"
    }
  ]
}
GET /api/v1/updates/execution-log/{host_id}

Get update execution log for a specific host.

🔒 Authentication Required

Path Parameters

  • host_id (string) - UUID of the target host

Response (200 OK)

{
  "host_id": "uuid",
  "execution_id": "uuid",
  "status": "completed",
  "started_at": "2024-01-01T12:00:00Z",
  "completed_at": "2024-01-01T12:15:00Z",
  "packages_updated": 15,
  "packages_failed": 0,
  "reboot_required": false,
  "log_entries": [
    {
      "timestamp": "2024-01-01T12:00:30Z",
      "level": "info",
      "message": "Starting package update: nginx"
    }
  ]
}

OS Upgrades

GET /api/v1/updates/os-upgrades

Get available operating system upgrades across all hosts.

🔒 Authentication Required

Response (200 OK)

[
  {
    "host_id": "uuid",
    "hostname": "web-01",
    "current_version": "Ubuntu 20.04.6 LTS",
    "available_version": "Ubuntu 22.04.3 LTS",
    "upgrade_type": "lts",
    "estimated_size": "1.2 GB",
    "estimated_time": "45-60 minutes",
    "requires_reboot": true
  }
]
POST /api/v1/updates/execute-os-upgrades

Execute operating system upgrades on specified hosts.

🔒 Authentication Required

Request Body

{
  "host_ids": ["uuid1", "uuid2"],
  "target_version": "22.04",
  "backup_before_upgrade": true,
  "schedule_time": "2024-01-01T02:00:00Z"
}

Response (200 OK)

{
  "batch_id": "uuid",
  "total_hosts": 2,
  "status": "scheduled",
  "scheduled_time": "2024-01-01T02:00:00Z",
  "estimated_completion": "2024-01-01T04:00:00Z"
}

Package Cache Management

POST /api/v1/packages/refresh/{os_name}/{os_version}

Refresh package cache for a specific OS version.

🔒 Authentication Required

Path Parameters

  • os_name (string) - Operating system name
  • os_version (string) - Operating system version

Response (200 OK)

{
  "message": "Package cache refresh initiated",
  "task_id": "uuid",
  "estimated_completion": "2024-01-01T12:10:00Z"
}

Important Notes

General Package Operations

  • Package operations are executed asynchronously - use execution IDs to track progress
  • Some operations require root/administrator privileges on target hosts
  • Always test operations on non-production systems first
  • Package availability depends on configured repositories
  • Use UUID-based tracking for grouped operations to ensure atomicity

Package Uninstallation

  • ⚠️ Irreversible Operations: Package uninstallation cannot be undone through the API
  • Dependency Management: Uninstalling packages may automatically remove dependencies
  • System Stability: Removing system packages can cause instability or service disruption
  • Backup Recommended: Create system snapshots before uninstalling critical packages
  • Confirmation Required: Web interface requires explicit confirmation for uninstall operations
  • Audit Trail: All uninstallation operations are logged with full details and user attribution

Updates and Upgrades

  • OS upgrades should be scheduled during maintenance windows
  • Backup systems before major updates or OS upgrades
  • Monitor system resources during large package operations

Security Considerations

  • Implement proper role-based access controls for package management
  • Review package sources and repositories for security
  • Monitor package operations for unauthorized changes
  • Use approval workflows for critical system modifications

Quick Navigation

← Host Management WebSocket API →