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.

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.

### Global query parameters

• normalize (optional): when set on a request, all keys in the JSON response are converted to lowercase recursively.

Example:

curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" "https://repomanager.mydomain.net/api/v2/hosts/?normalize"

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
/snapshot/<SNAPSHOT_ID>/diff/<SNAPSHOT_ID_2> GET	<APIKEY>		Compare two snapshots and list added/removed packages	curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/snapshot/<SNAPSHOT_ID>/diff/<SNAPSHOT_ID_2>

Environment

Endpoint and method	Authentication	Parameter(s)	Description	Example
/environment/<ENV>/point PATCH	<APIKEY>	snapshot Id (required, JSON body)	Point an environment to an existing snapshot (starts an asynchronous task; returns 202 and task-id).	curl --fail-with-body -L -s -X PATCH -H "Authorization: Bearer <APIKEY>" -H "Content-Type: application/json" -d '{"snapshot":1}' https://repomanager.mydomain.net/api/v2/environment/prod/point

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) strict (optional, query parameter) strict-name (optional, query parameter) strict-version (optional, query parameter) absent (optional, query parameter)	List hosts that have the specified package installed, optionally filtered by version. By default, package name and version matching can be non-strict. Use strict to enable strict matching for both package name and version, or use strict-name and strict-version independently. Set absent to list hosts where the package (and optional version) is not installed.	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 Strict on both name and 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?strict" Strict package name only: curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" "https://repomanager.mydomain.net/api/v2/hosts/package/nginx?strict-name" Strict version only: 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?strict-version" Return hosts where package is absent: curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" "https://repomanager.mydomain.net/api/v2/hosts/package/nginx?absent" Return hosts where exact package version is absent: 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?absent&strict"
/hosts/uptodate GET	<APIKEY>		List hosts with no available updates (0 pending updates).	curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/uptodate
/hosts/outdated GET	<APIKEY>	packages (optional, query parameter)	List hosts with at least one available update (>= 1 pending update). Set the packages query parameter to include the list of available updates for each host.	curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/outdated Including the list of available updates: curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" "https://repomanager.mydomain.net/api/v2/hosts/outdated?packages"
/hosts/compliant GET	<APIKEY>	packages (optional, query parameter)	List hosts compliant with all configured compliance criteria (pending updates threshold, latest update recency, and optional reboot-required check). Set the packages query parameter to include the list of available updates for each host.	curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/compliant Including the list of available updates: curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" "https://repomanager.mydomain.net/api/v2/hosts/compliant?packages"
/hosts/non-compliant GET	<APIKEY>	packages (optional, query parameter)	List hosts not compliant with at least one configured compliance criterion. Set the packages query parameter to include the list of available updates for each host.	curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/non-compliant Including the list of available updates: curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" "https://repomanager.mydomain.net/api/v2/hosts/non-compliant?packages"

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/<HOST_ID>/installed GET	<APIKEY>		Get installed packages of a specific host	curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/host/<HOST_ID>/installed
/host/<HOST_ID>/available GET	<APIKEY>		Get available updates for a specific host	curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/host/<HOST_ID>/available
/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) agent_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","agent_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

Tasks

Endpoint and method	Authentication	Parameter(s)	Description	Example
/tasks/ GET	<APIKEY>		List all tasks	curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/tasks/
/tasks/running GET	<APIKEY>		List running tasks	curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/tasks/running
/tasks/queued GET	<APIKEY>		List queued tasks	curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/tasks/queued
/tasks/scheduled GET	<APIKEY>		List scheduled tasks	curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/tasks/scheduled
/tasks/done GET	<APIKEY>		List done tasks	curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/tasks/done
/task/<TASK_ID>/ GET	<APIKEY>		Retrieve task details by task ID	curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/task/<TASK_ID>/
/task/<TASK_ID>/stop POST	<APIKEY>		Stop a running task	curl --fail-with-body --post301 -L -s -X POST -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/task/<TASK_ID>/stop
/task/<TASK_ID>/enable POST	<APIKEY>		Enable a recurrent task	curl --fail-with-body --post301 -L -s -X POST -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/task/<TASK_ID>/enable
/task/<TASK_ID>/disable POST	<APIKEY>		Disable a recurrent task	curl --fail-with-body --post301 -L -s -X POST -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/task/<TASK_ID>/disable
/task/<TASK_ID>/delete DELETE	<APIKEY>		Delete a recurrent task	curl --fail-with-body -L -s -X DELETE -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/task/<TASK_ID>/delete