Skip to main content

Add a catalog source

POST 
/catalog-sources

Required role: admin. Only an account or token with the admin role can call this operation.

Example request
curl --request POST \
  --header "Authorization: Bearer $HOSERVA_TOKEN" \
  --header "Content-Type: application/json" \
  --data @body.json \
  "https://$HOSERVA_HOST:8008/api/v1/catalog-sources"

Adds a catalog source URL of the user's own: the archive catalog.tar.zst is fetched from beneath url in the same format as the curated catalog and installed, and only then is the source recorded, so a source that cannot be fetched or verified leaves nothing behind. Hoserva contacts the URL only because the user added it, and only again when the user refreshes it. The URL must be an https address with no credentials, query or fragment (400 invalid_catalog_source otherwise, before anything is fetched), a redirect must stay on the same host, and the archive is size-capped as the curated one is. With a publicKey (PEM, or the base64 of the raw 32-byte Ed25519 key) the archive's detached signature catalog.tar.zst.sig is required and must verify against that key, and the source is signed. With no publicKey the source is accepted unsigned: no signature is requested and every entry it supplies is badged signed false. A template of an unsigned source still goes through the same privilege summary and warnings at install. Refused with 409 catalog_source_exists when a source with that URL (the curated one included) exists, 502 catalog_source_unreachable when the archive could not be fetched, and 422 catalog_source_rejected when the archive was fetched but refused (a signature that does not verify, a malformed archive).

Request​

Responses​

The source that was added.