• Logo
    Landscape
  • ubuntu.com/landscape
  • More resources
    • Discourse
    • GitHub
Contents Menu Expand Light mode Dark mode Auto light/dark, in light mode Auto light/dark, in dark mode Skip to content
Landscape documentation
Landscape documentation
  • Landscape Documentation
  • What is Landscape?
  • Tutorial
  • How-to guides
    • Landscape installation and set-up
      • Cloud providers
        • Install on Google Cloud
        • Install on Microsoft Azure
        • Deploy from the Azure Marketplace
        • Set up Ubuntu Amazon WorkSpaces
      • Quickstart installation
      • SaaS account
      • Manual installation
      • Juju installation
      • Juju HA installation
      • Install in a LXD container
      • Deploy with Terraform
      • Install on FIPS-compliant machines
      • Install in a DISA STIG compliant environment
      • Install in an airgapped environment
      • Install Landscape Client
      • Configure Landscape Client
      • Configure RabbitMQ
      • Use a remote RabbitMQ server
      • Configure Outbox
      • Configure Task Handler
      • Configure Postfix
      • Set up Debarchive
    • Upgrade
      • Upgrade Landscape
      • Upgrade to Landscape 26.04 LTS
      • Upgrade to Landscape 26.04 LTS (charm)
      • Upgrade to Landscape 24.04 LTS
      • Migrate repository mirrors to Debarchive
    • Backup and maintenance
      • Backup and restore
      • Backup and restore a charmed deployment
      • Manage maintenance cron jobs
      • Remove duplicate instances
    • Ubuntu Pro
      • Attach Ubuntu Pro
      • Enable Landscape
    • External authentication
      • Active Directory
      • OIDC
      • PAM
    • Repository mirrors
      • Manage repositories in the web portal
      • Manage repositories with the Legacy API
      • Set up repository mirroring end-to-end (26.04 and later)
      • Manage repositories in an airgapped environment
      • Create tiered-repository mirrors
    • Web portal
      • Manage instances
      • Manage administrators and roles
      • Manage access groups
      • Manage packages and snaps
      • Manage Livepatch and kernel updates
      • Use profiles
      • Use remote script execution
      • Use annotations
      • Sanitize instances
      • Legacy web portal
        • Manage computers
        • Manage administrators and roles
        • Manage access groups
        • Manage packages
        • Manage snaps
        • Other tasks
    • IoT for devices
      • Install the snap
      • Configure the snap
      • Create an Ubuntu Core image that includes the snap
      • Use remote script execution
      • Use annotations
      • Secure removal
      • Manage snaps with validation sets
    • WSL integration
      • Configure Landscape after upgrade
      • Configure a Juju deployment
      • Register WSL hosts
      • Manage WSL instances
      • Use WSL profiles
      • Perform common tasks
      • Get support
    • Ubuntu installer
      • Configure a deployment for autoinstall provisioning
      • Set up autoinstall provisioning
      • Provision a workstation
    • Security
      • Harden your deployment
      • Apply security updates
      • Use USG profiles
    • API
      • Make a REST API request
      • Legacy API
        • Use the legacy API command-line client
        • Use the legacy API via HTTPS requests
        • Use the legacy API Python module
    • NVIDIA DGX Spark
      • Set up NVIDIA DGX Spark for Landscape management
      • Use NVIDIA DGX Spark management scripts with Landscape
    • Troubleshooting
      • Common Landscape Client issues
      • Idle activities
  • Reference
    • API
      • REST API endpoints
        • Access groups
        • Accounts
        • Activities
        • Administrators
        • Alerts
        • Beta-only
        • Child Instance Profiles
        • Computers
        • Credentials
        • GPG Key
        • Invitations
        • License Management
        • Livepatch
        • Login
        • Package Change Plans
        • Package Search
        • Packages
        • Password
        • Person
        • Preferences
        • Processes
        • Reboot Profiles
        • FDE Recovery Key
        • Repositories
        • Repository Profiles
        • Script Profiles
        • Scripts
        • Self-hosted Landscape license
        • Snaps
        • Switch Account
        • Tokens
        • Users
        • USG Profiles
        • WSL
      • Debarchive API
      • Legacy API endpoints
        • Activities
        • Administrators
        • Alerts
        • Computers
        • Event Log
        • GPG
        • Package Profiles
        • Packages
        • Removal Profiles
        • Reporting
        • Repositories
        • Role Based Access Control
        • Saved Searches
        • Scripts
        • Upgrade Profiles
        • WSL
    • Release notes
      • 26.04 LTS release notes
      • 24.04 LTS release notes
      • 26.10 release notes
      • 25.10 release notes
      • 25.04 release notes
      • 24.10 release notes
      • Older release notes
        • 23.10 release notes
        • 23.03 release notes
        • 19.10 release notes
        • 19.01 release notes
        • 18.03 release notes
        • 17.03 release notes
        • 16.06 release notes
        • 16.03 release notes
        • 15.11 release notes
        • 15.10 release notes
        • 15.01 release notes
        • 14.10 release notes
    • Configuration
      • Immutable configuration settings
      • The service.conf file
      • Landscape Outbox configuration reference
      • Landscape Task Handler configuration reference
    • Networking
      • Internal network requirements
      • Network firewall
    • Landscape Server Charm
      • HAProxy route endpoints
      • Terraform charm module
      • Terraform product modules
    • Terms
      • Access groups
      • Administrators
      • Profiles
      • Roles
      • Tags
    • Supported versions and PPAs
    • Logs
    • Database
    • Known issues
    • lsctl
  • Explanation
    • Landscape
      • About Landscape
      • Deployment models
      • Self-hosted Landscape
      • Licenses
      • Landscape Server architecture
      • Landscape Client architecture
    • Landscape Server charm
      • Charm integration compatibility
      • PgBouncer integration
    • Features
      • Activities
      • Alerts
      • Repository mirroring
      • Package reporting
      • Bulk package management
      • Remote script execution
      • Full Disk Encryption recovery keys
    • Security
      • Security overview
      • Cryptographic technology
      • Data handling
      • Authentication and authorization
      • AppArmor
      • Disclosure and reporting
    • Related tools
      • Landscape and Ansible
      • Landscape and NVIDIA DGX Spark
  • Contribute to our documentation
Back to top
Contribute to this page

Package Search¶

These endpoints search for packages and available upgrades across a computer selection.

Note

You must be running Landscape Server 26.10 or later to use the REST API for package management.

This feature is available on self-hosted and select accounts on SaaS. It is not generally available to all SaaS accounts.

Filter states¶

Some parameters are tri-state filters. Accepted values are:

  • "true": keep only packages matching the condition.

  • "false": keep only packages not matching the condition.

  • "unspecified" (default): don’t filter on it.

POST /packages:search¶

Search packages across a computer selection.

Request body parameters¶

Required:

  • computer_query: Query string selecting the target computers (same syntax as the query parameter on Computers).

Optional:

  • text: Matches against package name, summary, and description.

  • names: Package names as one comma-separated string, such as "curl,nginx". Each name takes an optional version constraint using =, >>, <<, >=, or <=, such as "curl>=8.5".

  • installed: Whether the package is installed on a selected computer. See filter states.

  • available: Whether the package is available from an APT source.

  • upgrade: Whether a newer version is available.

  • held: Whether the package is held.

  • security: Whether the package comes from a security pocket.

  • limit: Maximum number of packages to return (default: 100).

  • offset: Offset into the result list (default: 0).

Response fields¶

  • packages: Matched packages.

    • id: Package ID.

    • name: Package name.

    • summary: Short description.

    • version: Version string.

    • computers.count: Number of selected computers that have this package.

  • count: Total number of matching packages.

  • next: The link to the next page.

  • prev: The link to the previous page.

Example¶

Example request–installed packages matching “ssh”:

curl -s -X POST https://landscape.canonical.com/api/v2/packages:search \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "computer_query": "tag:production",
    "text": "ssh",
    "installed": "true",
    "limit": 2
  }'

Example response (200 OK):

{
  "packages": [
    {
      "id": 1,
      "name": "openssh-server",
      "summary": "secure shell (SSH) server, for secure access from remote machines",
      "version": "1:9.6p1-3ubuntu13.5",
      "computers": {
        "count": 50
      },
    }
  ],
  "count": 1,
  "next": null,
  "prev": null,
}

POST /packages:search-upgrades¶

Search available (latest) package upgrades across a computer selection.

Request body parameters¶

Required:

  • computer_query: Query string selecting the target computers (same syntax as the query parameter on Computers).

Optional:

  • text: Matches against package name, summary, and description.

  • names: Package names as one comma-separated string, such as "curl,nginx". Each name takes an optional version constraint using =, >>, <<, >=, or <=, such as "curl>=8.5".

  • security: Whether the upgrade comes from a security pocket. See filter states.

  • limit: Maximum number of packages to return (default: 100).

  • offset: Offset into the result list (default: 0).

Response fields¶

Same shape as /packages:search, where each package is the upgrade candidate rather than the installed version.

  • packages: Upgradable packages.

    • id: Package ID of the new version.

    • name: Package name.

    • summary: Short description.

    • version: Version string of the new version.

    • computers.count: Number of selected computers that can take this upgrade.

  • count: Total number of matching upgrades.

  • next: The link to the next page.

  • prev: The link to the previous page.

Example¶

Example request–security upgrades only:

curl -s -X POST https://landscape.canonical.com/api/v2/packages:search-upgrades \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "computer_query": "tag:production",
    "security": "true"
  }'

Example response (200 OK):

{
  "packages": [
    {
      "id": 2,
      "name": "openssh-server",
      "summary": "secure shell (SSH) server, for secure access from remote machines",
      "version": "1:9.6p1-3ubuntu13.9",
      "computers": {
        "count": 50
      },
    },
    {
      "id": 4,
      "name": "curl",
      "summary": "command line tool for transferring data with URL syntax",
      "version": "8.5.0-2ubuntu10.6",
      "computers": {
        "count": 31
      },
    }
  ],
  "count": 2,
  "next": null,
  "prev": null,
}
© 2026 Canonical Ltd.
Last updated on Oct 09, 2026
Manage your tracker settings
Contents
  • Package Search
    • Filter states
    • POST /packages:search
      • Request body parameters
      • Response fields
      • Example
    • POST /packages:search-upgrades
      • Request body parameters
      • Response fields
      • Example