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), 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 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

  • Package operations are executed asynchronously - use execution IDs to track progress
  • Some operations require root/administrator privileges on target hosts
  • OS upgrades should be scheduled during maintenance windows
  • Always test updates on non-production systems first
  • Backup systems before major updates or OS upgrades
  • Package availability depends on configured repositories

Quick Navigation

← Host Management WebSocket API →