Skip to content

API

API root URL

https://<FQDN>/api/v2

Repomanager exposes an API that allows performing certain actions.

From a client host:

  • Register or unregister a host into Repomanager
  • Send general host information to Repomanager
  • Send packages information to Repomanager
  • Retrieve the configuration of a host profile from Repomanager

From a desktop:

  • Import source repositories
  • Upload a package to a repository
  • Rebuild repository metadata
  • ...

API key

An API key must be retrieved from userspace.

Once generated, copy the key and keep it safe. This key is used to authenticate with the API and to perform certain actions when there is no host Id+token pair available.

Generate API key

Info

If a new API key is generated, the old key becomes invalid and unusable.

Endpoints

Info

<REPO_ID> can be retrieved from the URL when you browse repository statistics or from the API when you list repositories from the API.

<SNAPSHOT_ID> can be retrieved from the URL when you browse a snapshot from the repositories list or from the API when you list snapshots of a repository.

Source repositories

Endpoint and method Authentication Parameter(s) Description Example
/source/
GET		 <APIKEY> List all source repositories 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/source/
/source/<TYPE>/
GET		 <APIKEY> type (required, in URL: deb or rpm) List all source repositories of a specific type 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/source/deb/
/source/<TYPE>/<NAME>
GET		 <APIKEY> type (required, in URL: deb or rpm)
name (required, in URL)		 Retrieve source repository details by name 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/source/deb/nginx
/source/<TYPE>/import
POST		 <APIKEY> template (required, YAML file) Import source repositories from a YAML template file 
curl --fail-with-body --post301 -L -s -X POST -H "Authorization: Bearer <APIKEY>" -F "template=@/tmp/template.yml" https://repomanager.mydomain.net/api/v2/source/deb/import

Repositories

Endpoint and method Authentication Parameter(s) Description Example
/repo/
GET		 <APIKEY> List all repositories 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/repo/
/repo/
GET		 <APIKEY> List all repositories whose name is nginx 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/repo/ | jq -r '.results[] | select(.Name == "nginx")'
/repo/
GET		 <APIKEY> (RPM repos) List all repositories whose name is nginx and the release version is 8 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/repo/ | jq -r '.results[] | select(.Name == "nginx")'
/repo/
GET		 <APIKEY> (DEB repos) List all repositories whose name is nginx, the distribution is bookworm and the section/component is nginx 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/repo/ | jq -r '.results[] | select(.Name == "nginx" and .Dist == "bookworm" and .Section == "nginx")'
/repo/<REPO_ID>/
GET		 <APIKEY> List all snapshots of a repository whose ID is 12 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/repo/12/
/repo/<REPO_ID>/
GET		 <APIKEY> Get the ID of the most recent snapshot of a repository whose ID is 12 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/repo/12/ | jq -r .results[].Id | head -n1

Snapshots

Endpoint and method Authentication Parameter(s) Description Example
/snapshot/<SNAPSHOT_ID>/
GET		 <APIKEY> List snapshot details 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/snapshot/<SNAPSHOT_ID>/
/snapshot/<SNAPSHOT_ID>/packages
GET		 <APIKEY> List all packages of a snapshot 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/snapshot/<SNAPSHOT_ID>/packages
/snapshot/<SNAPSHOT_ID>/upload
POST		 <APIKEY> file (required) overwrite (optional, default: false) ignore-if-exists (optional, default: false) Upload one or more packages to a repository snapshot. Overwrite the package if it already exists in the snapshot if overwrite is set to true. Ignore the upload if the package already exists if ignore-if-exists is set to true. Single file example: 
curl --fail-with-body --post301 -L -s -X POST -H "Authorization: Bearer <APIKEY>" -F "file1=@/tmp/mypackage.deb" https://repomanager.mydomain.net/api/v2/snapshot/<SNAPSHOT_ID>/upload
Multiple files example: 
curl --fail-with-body --post301 -L -s -X POST -H "Authorization: Bearer <APIKEY>" -F "file1=@/tmp/mypackage1.deb" -F "file2=@/tmp/mypackage2.deb" https://repomanager.mydomain.net/api/v2/snapshot/<SNAPSHOT_ID>/upload
Overwrite example: 
curl --fail-with-body --post301 -L -s -X POST -H "Authorization: Bearer <APIKEY>" -F "file1=@/tmp/mypackage.deb" -F "overwrite=true" https://repomanager.mydomain.net/api/v2/snapshot/<SNAPSHOT_ID>/upload
Ignore if exists example: 
curl --fail-with-body --post301 -L -s -X POST -H "Authorization: Bearer <APIKEY>" -F "file1=@/tmp/mypackage.deb" -F "ignore-if-exists=true" https://repomanager.mydomain.net/api/v2/snapshot/<SNAPSHOT_ID>/upload
/snapshot/<SNAPSHOT_ID>/rebuild
PUT		 <APIKEY> gpgSign (required) Rebuild repository snapshot metadata. 
curl --fail-with-body --post301 -L -s -X PUT -H "Authorization: Bearer <APIKEY>" -H "Content-Type: application/json" -d '{"gpgSign":"true"}' https://repomanager.mydomain.net/api/v2/snapshot/<SNAPSHOT_ID>/rebuild
/snapshot/<SNAPSHOT_ID>/packages
DELETE		 <APIKEY> packages (required, JSON array of package names) Delete one or more packages from a snapshot 
curl --fail-with-body -L -s -X DELETE -H "Authorization: Bearer <APIKEY>" -H "Content-Type: application/json" -d '{"packages":["mypackage1.deb", "mypackage2.deb"]}' https://repomanager.mydomain.net/api/v2/snapshot/<SNAPSHOT_ID>/packages

Hosts listing

Endpoint and method Authentication Parameter(s) Description Example
/hosts/
GET		 <APIKEY> List all hosts 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/
/hosts/os/<OS>/<OS_VERSION?>
GET		 <APIKEY> os (required, in URL)
os_version (optional, in URL)		 List hosts by OS name and optionally by OS version. Use %20 to encode spaces in OS names (e.g. linux%20mint). 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/os/ubuntu/
With OS version: 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/os/ubuntu/26.04
/hosts/kernel/<KERNEL>
GET		 <APIKEY> kernel (required, in URL) List hosts by kernel version 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/kernel/5.15.0-89-generic
/hosts/arch/<ARCH>
GET		 <APIKEY> arch (required, in URL) List hosts by architecture 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/arch/x86_64
/hosts/profile/<PROFILE>
GET		 <APIKEY> profile (required, in URL) List hosts by profile name 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/profile/app_server
/hosts/environment/<ENV>
GET		 <APIKEY> environment (required, in URL) List hosts by environment 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/environment/prod
/hosts/package/<PACKAGE>/<VERSION?>
GET		 <APIKEY> package (required, in URL)
version (optional, in URL)		 List hosts that have the specified package installed, optionally filtered by version 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/package/nginx
With version: 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/package/nginx/1.24.0-1
/hosts/uptodate
GET		 <APIKEY> List all up-to-date hosts (hosts with no or few available updates based on configured threshold) 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/uptodate
/hosts/outdated
GET		 <APIKEY> List all outdated hosts (hosts with available updates exceeding the configured threshold) 
curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/outdated

Host profiles

Endpoint and method Authentication Parameter(s) Description Example
/profile
GET		 <APIKEY>
or
<HOST_ID> and <HOST_TOKEN>		 Retrieve all available profile configurations 
curl --fail-with-body -L -s -X GET -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" https://repomanager.mydomain.net/api/v2/profile
/profile/<PROFILE>
GET		 <APIKEY>
or
<HOST_ID> and <HOST_TOKEN>		 Retrieve profile's global configuration 
curl --fail-with-body -L -s -X GET -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" https://repomanager.mydomain.net/api/v2/profile/app_server
/profile/<PROFILE>/excludes
GET		 <APIKEY>
or
<HOST_ID> and <HOST_TOKEN>		 Retrieve profile's package exclusion configuration 
curl --fail-with-body -L -s -X GET -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" https://repomanager.mydomain.net/api/v2/profile/app_server/excludes
/profile/<PROFILE>/repos
GET		 <APIKEY>
or
<HOST_ID> and <HOST_TOKEN>		 Retrieve profile's repository configuration 
curl --fail-with-body -L -s -X GET -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" https://repomanager.mydomain.net/api/v2/profile/app_server/repos

Host registration and status update

Mainly used by the linupdate agent, these endpoints allow to register a host to Repomanager and to send host information (general information, installed packages, available updates, package events) to Repomanager.

Endpoint and method Authentication Parameter(s) Description Example
/host/registering
POST		 <APIKEY> hostname (required)
ip (required)		 Register a host to Repomanager and retrieve host ID and token 
curl --fail-with-body --post301 -L -s -X POST -H "Authorization: Bearer <APIKEY>" -H "Content-Type: application/json" -d '{"hostname":"<FQDN>","ip":"<IP>"}' https://repomanager.mydomain.net/api/v2/host/registering
/host/registering
DELETE		 <APIKEY>
or
<HOST_ID> and <HOST_TOKEN>		 hostname (required if API key is used) Unregister a host from Repomanager With API key: 
curl --fail-with-body -L -s -X DELETE -H "Authorization: Bearer <APIKEY>" -H "Content-Type: application/json" -d '{"hostname":"<hostname>"}' https://repomanager.mydomain.net/api/v2/host/registering
With host ID and token: 
curl --fail-with-body -L -s -X DELETE -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" -H "Content-Type: application/json" https://repomanager.mydomain.net/api/v2/host/registering
/host/status
PUT		 <HOST_ID> and <HOST_TOKEN> hostname (optional)
os (optional)
os_version (optional)
os_family (optional)
type (=virtualization type) (optional)
kernel (optional)
arch (optional)
profile (optional)
env (optional)
agent_status (optional)
linupdate_version (optional)
reboot_required (optional)		 Send host general information to Repomanager 
curl --fail-with-body --post301 -L -s -X PUT -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" -H "Content-Type: application/json" -d '{"hostname":"myfqdn.localhost","os":"ubuntu","os_version":"22.04","os_family":"Debian","type":"Bare metal","kernel":"5.15.0-89-generic","arch":"x86_64","profile":"PC","env":"prod","agent_status":"running","linupdate_version":"2.2.2","reboot_required":"false"}' https://repomanager.mydomain.net/api/v2/host/status
/host/packages/installed
PUT		 <HOST_ID> and <HOST_TOKEN> installed_packages (required)
Each package must be separated by a comma and contains the package name and the version number separated by a pipe		 Send list of installed packages to Repomanager 
curl --fail-with-body --post301 -L -s -X PUT -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" -H "Content-Type: application/json" -d '{"installed_packages":"accountsservice|22.07.5-2ubuntu1.4,acl|2.3.1-1,acpi-support|0.144,acpid|1:2.0.33-1ubuntu1,add-apt-key|1.0-0.5,adduser, etc..."}' https://repomanager.mydomain.net/api/v2/host/packages/installed
/host/packages/available
PUT		 <HOST_ID> and <HOST_TOKEN> available_packages (required)
Each package must be separated by a comma and contains the package name and the version number separated by a pipe		 Send list of available packages (can be updated) to Repomanager 
curl --fail-with-body --post301 -L -s -X PUT -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" -H "Content-Type: application/json" -d '{"available_packages":"accountsservice|22.07.6-2ubuntu1,add-apt-key|1.0-0.6,adduser|3.118ubuntu5, etc..."}' https://repomanager.mydomain.net/api/v2/host/packages/available
/host/packages/event
PUT		 <HOST_ID> and <HOST_TOKEN> events (required) Send package event history (installed / upgraded / removed / downgraded) to Repomanager 
curl --fail-with-body --post301 -L -s -X PUT -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" -H "Content-Type: application/json" -d '
{
    "events": [
        {
            "date_start": "2022-11-01",
            "date_end": "2022-11-01",
            "time_start": "12:47:30",
            "time_end": "12:47:57",
            "command": "/usr/bin/apt upgrade",
            "upgraded": [
                {
                    "name": "firefox-locale-en",
                    "version": "106.0.3+linuxmint1+vanessa"
                },
                {
                    "name": "php8.1-opcache",
                    "version": "8.1.12-1+ubuntu22.04.1+deb.sury.org+1"
                },
            ],
        },
        {
            "date_start": "2022-11-05",
            "date_end": "2022-11-05",
            "time_start": "12:21:40",
            "time_end": "12:21:41",
            "command": "/usr/bin/apt install php8.1-curl",
            "installed": [
                {
                    "name": "php8.1-curl",
                    "version": "8.1.12-1+ubuntu22.04.1+deb.sury.org+1"
                }
            ]
        },
        {
            "date_start": "2022-11-16",
            "date_end": "2022-11-16",
            "time_start": "16:26:15",
            "time_end": "16:26:20",
            "command": "/usr/bin/apt autoremove",
            "removed": [
                {
                    "name": "linux-headers-5.15.0-50-generic",
                    "version": "5.15.0-50.56"
                },
                {
                    "name": "linux-modules-5.15.0-50-generic",
                    "version": "5.15.0-50.56"
                }
            ]
        }
    ]
}' https://repomanager.mydomain.net/api/v2/host/packages/event