Artefacts et catalogue

Artefacts publiés : liste, détails, contenu, annotations, références, recherche, audit du catalogue et son flux de modifications.

Opérations de ce groupe, avec leur règle d’accès, leur règle de nouvelle tentative, leurs paramètres et leurs réponses. Chaque requête porte une clé : Authorization: Bearer <clé> (voir « Authentification »).

Opérations

Obtenir les annotations d’un artefact

GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/annotations

Accès: Autorisation sur le dépôt : annotation.read; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)

Renvoie les étiquettes, les métadonnées et les collections actuelles d’un artefact publié, avec leur revision. La révision 0 signifie qu’elles n’ont jamais été remplacées : les étiquettes et les métadonnées sont celles données à la création du téléversement, et les collections sont vides. Passez la révision à setAnnotations comme expectedRevision.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
repository	chemin	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
id	chemin	string (uuid)	oui	—

Réponse 200

Champ	Type	Obligatoire	Règles
revision	integer	oui	0–2147483647
labels	tableau de string	oui	jusqu’à 32 éléments
metadata	dictionnaire de string	oui	jusqu’à 32 entrées
collections	tableau de string	oui	jusqu’à 32 éléments

Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemple

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/annotations" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Remplacer les annotations d’un artefact

PUT /api/v1/repositories/{repository}/artifacts/{id}/annotations

Accès: Autorisation sur le dépôt : annotation.write, artifact.read; clés de fichier : read, write · Nouvelle tentative: Répéter uniquement avec la révision attendue (compare-and-swap)

Remplace d’un seul coup labels, metadata et collections d’un artefact publié ; un champ absent de value devient vide. expectedRevision doit être la révision actuelle (0 pour la première modification), sinon 409 revision_mismatch : relisez les annotations et réappliquez la modification. Jusqu’à 32 étiquettes et 32 collections (1–64 lettres, chiffres ou _.:-) et 32 entrées de métadonnées (valeurs jusqu’à 1024 caractères) ; les octets et le descripteur d’origine ne changent jamais.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
repository	chemin	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
id	chemin	string (uuid)	oui	—

Corps de la requête (application/json)

Champ	Type	Obligatoire	Règles
expectedRevision	integer	oui	0–2147483646
value	object	oui	—
value.labels	tableau de string	non	jusqu’à 32 éléments
value.metadata	dictionnaire de string	non	jusqu’à 32 entrées
value.collections	tableau de string	non	jusqu’à 32 éléments

Réponse 200

Champ	Type	Obligatoire	Règles
revision	integer	oui	0–2147483647
labels	tableau de string	oui	jusqu’à 32 éléments
metadata	dictionnaire de string	oui	jusqu’à 32 entrées
collections	tableau de string	oui	jusqu’à 32 éléments

Réponses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Exemple

curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/annotations" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0,"value":{}}'

Enregistrer un artefact comme paquet UPack

POST /api/v1/repositories/{repository}/artifacts/{id}/package

Accès: Autorisation sur le dépôt : package.publish, artifact.read; clés de fichier : read, write · Nouvelle tentative: Peut être répétée sans risque : la même requête a le même effet

Ouvre l’artefact publié comme un ZIP UPack, lit le upack.json racine (name, group facultatif, version SemVer) et enregistre cette version de paquet pour lui ; les archives dangereuses ou invalides sont rejetées avec 400. Une version est immuable : enregistrer à nouveau le même artefact renvoie la même entrée, tandis qu’un autre artefact pour un groupe, un nom et une version existants (comparés sans tenir compte de la casse) donne 409 version_exists. Ensuite, la version apparaît dans listPackages et se résout par nom, plage de versions et étape.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
repository	chemin	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
id	chemin	string (uuid)	oui	—

Réponse 200

Champ	Type	Obligatoire	Règles
group	string	non	—
name	string	non	—
version	string	non	—
artifactId	string (uuid)	non	—
manifest	object	non	—

Réponses: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507

Exemple

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/package" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Rechercher des artefacts

GET HEAD /api/v1/repositories/{repository}/search

Accès: Autorisation sur le dépôt : artifact.list; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)

Trouve les artefacts publiés selon q (sous-chaîne, sans tenir compte de la casse, du nom ou d’une valeur de métadonnées actuelle), une étiquette label exacte et actuelle, une collection, et une paire exacte metadataKey/metadataValue, qui vont ensemble ; tous les filtres donnés doivent correspondre. Les résultats arrivent par pages de 100 triées par ID, chacun avec sa taille, ses dates de création et de publication, ses étiquettes actuelles et ses étapes de promotion ; poursuivez avec after défini sur next. Les métadonnées et les collections ne sont pas renvoyées : lisez-les avec getAnnotations.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
repository	chemin	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
q	requête	string	non	—
label	requête	string	non	—
collection	requête	string	non	—
after	requête	string	non	—
metadataKey	requête	string	non	correspond à ^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$; jusqu’à 64 caractères; Exact metadata key; requires metadataValue.
metadataValue	requête	string	non	jusqu’à 1024 caractères; Exact case-sensitive value; requires metadataKey. Empty string is allowed.

Réponse 200

Champ	Type	Obligatoire	Règles
items	tableau de object	oui	jusqu’à 100 éléments
items[].id	string (uuid)	oui	—
items[].name	string	oui	—
items[].size	string	oui	un nombre entier en chiffres décimaux, transmis sous forme de chaîne; Taille en octets, chaîne décimale
items[].createdAt	string (date-time)	oui	Heure de réservation du téléversement
items[].publishedAt	string (date-time)	oui	peut être null; Date de publication ; null seulement si aucune n’a été enregistrée
items[].labels	tableau de string	oui	jusqu’à 32 éléments; Étiquettes actuelles : celles de l’annotation si elle a été remplacée, sinon celles du descripteur du téléversement
items[].stages	tableau de string	oui	jusqu’à 16 éléments; chaque élément : correspond à ^[a-z0-9][a-z0-9_.-]{0,31}$; Étapes de promotion actuelles, dans l’ordre des octets
next	string (uuid)	oui	peut être null; Dernier ID d’une page pleine ; à passer comme after

Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemple

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/search" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Lire l’audit du catalogue d’un dépôt

GET HEAD /api/v1/repositories/{repository}/audit

Accès: Autorisation sur le dépôt : audit.read; clés de fichier : write · Nouvelle tentative: Peut être répétée sans risque (lecture)

Renvoie, du plus ancien au plus récent, jusqu’à 100 modifications du catalogue du dépôt après le numéro de séquence after (0 par défaut) : publications, suppressions, modifications d’annotations et de pièces jointes, enregistrements de paquets, modifications de chemins de fichiers, références, étapes et promotions, chacune avec l’acteur, l’action, l’artefact et l’heure. Pour lire la suite, passez le dernier sequence de la page comme after ; il n’y a pas de champ next. Les téléchargements et les connexions n’y figurent pas ; les miroirs suivent listCatalogChanges, qui omet les acteurs.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
repository	chemin	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
after	requête	string	non	—

Réponse 200

Champ	Type	Obligatoire	Règles
items	tableau de object	non	—
items[].sequence	string	non	—
items[].actor	string	non	—
items[].action	string	non	—
items[].artifactId	string	non	—
items[].occurredAt	string (date-time)	non	—

Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemple

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/audit" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Ajouter une référence à un artefact

POST /api/v1/repositories/{repository}/artifacts/{id}/references

Accès: Autorisation sur le dépôt : reference.write, artifact.read; clés de fichier : read, write · Nouvelle tentative: Peut être répétée sans risque : la même requête a le même effet

Enregistre que quelque chose d’extérieur à Arkvory utilise cet artefact, sous une key de votre choix (1–256 lettres, chiffres ou _.:/-), par exemple un nom de déploiement. Un artefact référencé ne peut être ni supprimé ni retiré par la rétention tant qu’il reste une référence. La référence appartient à l’appelant ; ajouter à nouveau la même clé ne change rien.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
repository	chemin	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
id	chemin	string (uuid)	oui	—

Corps de la requête (application/json)

Champ	Type	Obligatoire	Règles
key	string	oui	jusqu’à 256 caractères

Réponses: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Exemple

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/references" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"<key>"}'

Retirer une référence d’un artefact

DELETE /api/v1/repositories/{repository}/artifacts/{id}/references

Accès: Autorisation sur le dépôt : reference.write, artifact.read; clés de fichier : read, write · Nouvelle tentative: Peut être répétée sans risque : la même requête a le même effet

Retire de l’artefact la référence key de l’appelant ; les références des autres appelants restent. Retirer une clé absente réussit aussi.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
repository	chemin	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
id	chemin	string (uuid)	oui	—

Corps de la requête (application/json)

Champ	Type	Obligatoire	Règles
key	string	oui	jusqu’à 256 caractères

Réponses: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Exemple

curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/references" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"<key>"}'

Lister les artefacts

GET HEAD /api/v1/repositories/{repository}/artifacts

Accès: Autorisation sur le dépôt : artifact.list; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)

Liste les artefacts publiés du dépôt triés par ID, limit par page (1–100, 50 par défaut) ; poursuivez avec after défini sur next. next est défini dès qu’une page est pleine, de sorte que la dernière page peut être vide. Chaque élément porte le descripteur donné au téléversement ; les étiquettes et les métadonnées actuelles se trouvent dans getAnnotations.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
repository	chemin	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
after	requête	string (uuid)	non	—
limit	requête	integer	non	1–100; par défaut 50

Réponse 200

Champ	Type	Obligatoire	Règles
items	tableau de object	non	—
items[].id	string (uuid)	oui	—
items[].repository	string	oui	—
items[].status	string	oui	une valeur parmi pending, available, cancelled
items[].createdAt	string (date-time)	oui	—
items[].expiresAt	string (date-time)	oui	—
items[].descriptor	object	oui	—
items[].descriptor.name	string	oui	1–240 caractères
items[].descriptor.size	string	oui	un nombre entier en chiffres décimaux, transmis sous forme de chaîne
items[].descriptor.sha256	string	oui	SHA-256 : 64 chiffres hexadécimaux en minuscules
items[].descriptor.labels	tableau de string	non	jusqu’à 32 éléments; chaque élément : jusqu’à 64 caractères
items[].descriptor.metadata	dictionnaire de string	non	jusqu’à 32 entrées
next	string	non	peut être null

Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemple

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Obtenir un artefact

GET HEAD /api/v1/repositories/{repository}/artifacts/{id}

Accès: Autorisation sur le dépôt : artifact.read; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)

Renvoie un artefact publié : son ID, son dépôt, son statut, sa date de création et le descripteur donné au téléversement (nom, taille, SHA-256, étiquettes et métadonnées d’origine). Les artefacts en attente, annulés et supprimés répondent 404. Pour lire les octets, utilisez downloadArtifact.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
repository	chemin	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
id	chemin	string (uuid)	oui	—

Réponse 200

Champ	Type	Obligatoire	Règles
id	string (uuid)	oui	—
repository	string	oui	—
status	string	oui	une valeur parmi pending, available, cancelled
createdAt	string (date-time)	oui	—
expiresAt	string (date-time)	oui	—
descriptor	object	oui	—
descriptor.name	string	oui	1–240 caractères
descriptor.size	string	oui	un nombre entier en chiffres décimaux, transmis sous forme de chaîne
descriptor.sha256	string	oui	SHA-256 : 64 chiffres hexadécimaux en minuscules
descriptor.labels	tableau de string	non	jusqu’à 32 éléments; chaque élément : jusqu’à 64 caractères
descriptor.metadata	dictionnaire de string	non	jusqu’à 32 entrées

Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemple

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Supprimer un artefact

DELETE /api/v1/repositories/{repository}/artifacts/{id}

Accès: Autorisation sur le dépôt : artifact.delete · Nouvelle tentative: Peut être répétée sans risque : la même requête a le même effet

Supprime logiquement un artefact publié : il disparaît aussitôt des listes, des recherches et des téléchargements, et ses octets sont récupérés par le nettoyage physique en ligne du dépôt (setCleanup, désactivé par défaut) après son délai de grâce. expectedAnnotationRevision doit être égale à la révision actuelle des annotations. La réponse est 200 avec un outcome : deleted, already_deleted, changed (la révision diffère), not_found, ou protected avec les blockers qui le retiennent (une référence, une révision de chemin de fichier, une pièce jointe de build ou une étape de promotion). Vérifiez au préalable avec inspectArtifactDeletion.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
repository	chemin	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
id	chemin	string (uuid)	oui	—

Corps de la requête (application/json)

Champ	Type	Obligatoire	Règles
expectedAnnotationRevision	integer	oui	0–2147483647

Réponse 200

Champ	Type	Obligatoire	Règles
id	string (uuid)	oui	—
outcome	string	oui	une valeur parmi deleted, already_deleted, protected, changed, not_eligible, not_found
blockers	tableau de string	oui	jusqu’à 4 éléments; aucun élément répété; chaque élément : une valeur parmi reference, asset_history, attachment_history, protected_label, promotion_stage

Réponses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Exemple

curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedAnnotationRevision":0}'

Télécharger un artefact

GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/content

Accès: Autorisation sur le dépôt : content.read; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)

Diffuse en flux les octets d’origine avec Content-Length, Content-Disposition (le nom de l’artefact) et un ETag fort ("sha256:<hex>"). Un seul Range donne 206 (une plage non satisfaisable, 416) ; If-Range avec l’ETag reprend en toute sécurité, et If-None-Match répond 304. HEAD renvoie les mêmes en-têtes sans corps et ignore Range. Au lieu d’un en-tête Authorization, la requête peut porter, comme token, un lien de téléchargement issu de createDownloadLink ; les téléchargements attendent un emplacement libre dans l’admission des téléchargements du serveur.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
repository	chemin	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
id	chemin	string (uuid)	oui	—
Range	en-tête	string	non	—
If-Range	en-tête	string	non	—
If-None-Match	en-tête	string	non	—
Arkvory-Download-Id	en-tête	string	non	correspond à ^[A-Za-z0-9_-]{16,64}$; The client own id of one download, the same on every range of it: the queue keys the session by it instead of the client address, answers a waiting request at once with 503 download_queued, and may ask it to yield its place at a range boundary. Without it, a waiting request is held until its turn for a bounded time.
Arkvory-Queue-Ticket	en-tête	string	non	jusqu’à 80 caractères; The last Arkvory-Queue-Ticket the server sent for this download: after a server restart the download takes its old turn. A ticket that is wrong, expired or of another download is ignored.
Arkvory-Download-Class	en-tête	string	non	une valeur parmi interactive, release, bulk, background; Queue class of the download. Only a class lower than the caller own one applies (people: interactive, services and links: release); an unknown value is 400. The response names the class applied.
token	requête	string	non	correspond à ^dtl_[A-Za-z0-9_-]{43}$; Download link from POST …/artifacts/{id}/links, instead of an Authorization header

Réponses: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507

Exemple

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/content" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -o file

Lire la vue d’ensemble des sites

GET HEAD /api/v1/fleet/overview

Accès: Administrateur · Nouvelle tentative: Peut être répétée sans risque (lecture)

Les alertes des sites gérés et de cette installation, les plus graves d’abord (critical, warning, info), et les liens de miroir entre eux. Construite à partir des dernières lectures en arrière-plan, au plus une fois toutes les 5 secondes. Une source à l’adresse de laquelle aucun site géré ne répond est external:<origin> ; cette installation est self et ne reçoit les liens vers elle que si ARKVORY_SITE_URL est défini. Seul le processus d’écriture répond.

Réponse 200

Champ	Type	Obligatoire	Règles
generatedAt	string (date-time)	oui	—
self	object	oui	—
self.name	string	oui	—
self.version	string	oui	—
self.url	string	oui	peut être null
alerts	tableau de object	oui	—
alerts[].site	string	oui	—
alerts[].name	string	oui	—
alerts[].kind	string	oui	une valeur parmi unreachable, certificate, revoked, refused, invalid, stale, not-writable, copies, single-copy, mirror-failing, mirror-lag, updates-failed, version-skew
alerts[].severity	string	oui	une valeur parmi critical, warning, info
alerts[].subject	string	oui	peut être null
alerts[].since	string (date-time)	oui	peut être null
links	tableau de object	oui	—
links[].from	string	oui	—
links[].to	string	oui	—
links[].repository	string	oui	—
links[].sourceRepository	string	oui	—
links[].mode	string	oui	une valeur parmi mirror, import
links[].lagChanges	string	oui	un nombre entier en chiffres décimaux, transmis sous forme de chaîne; peut être null
links[].failing	boolean	oui	—
links[].stale	boolean	non	—
external	tableau de string	oui	—

Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemple

curl -X GET "$ARKVORY_URL/api/v1/fleet/overview" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Lister les sites gérés

GET HEAD /api/v1/fleet/sites

Accès: Administrateur · Nouvelle tentative: Peut être répétée sans risque (lecture)

Liste les sites que gère cette installation (ADR 0077) avec ce que chacun a signalé en dernier : state (ok, ou pourquoi il n’a pas été lu : unreachable, certificate, revoked, invalid, refused), quand il a été vu pour la dernière fois et sa dernière topology. Les sites sont lus toutes les 30 secondes en arrière-plan. La clé d’un site n’est jamais renvoyée.

Réponse 200

Champ	Type	Obligatoire	Règles
items	tableau de object	oui	jusqu’à 256 éléments
items[].id	string (uuid)	oui	—
items[].name	string	oui	—
items[].url	string	oui	—
items[].fingerprint	string	oui	correspond à ^[0-9a-f]{64}$; peut être null
items[].addedBy	string	oui	—
items[].addedAt	string (date-time)	oui	—
items[].seenAt	string (date-time)	oui	peut être null
items[].state	string	oui	une valeur parmi pending, ok, unreachable, certificate, revoked, invalid, refused
items[].error	string	oui	peut être null
items[].topology	object	oui	peut être null
items[].topology.collectedAt	string (date-time)	oui	—
items[].topology.site	object	oui	—
items[].topology.health	object	oui	—
items[].topology.replication	object	oui	peut être null
items[].topology.gateways	tableau de object	oui	jusqu’à 16 éléments
items[].topology.mirrors	tableau de object	oui	jusqu’à 64 éléments
items[].topology.updates	object	oui	peut être null
items[].topology.downloads	object	oui	—

Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemple

curl -X GET "$ARKVORY_URL/api/v1/fleet/sites" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

S’appairer avec un site

POST /api/v1/fleet/sites

Accès: Administrateur · Nouvelle tentative: Ne pas répéter automatiquement

Appaire un site : le contrôleur se reconnecte, le certificat doit toujours avoir l’fingerprint confirmée par l’administrateur (null pour HTTP en loopback), le code d’appairage créé sur le site est échangé contre une clé, scellée avec ARKVORY_FLEET_KEY_FILE. Le site est lu une fois avant la réponse. Sans fichier de clé, la réponse est 503.

Corps de la requête (application/json)

Champ	Type	Obligatoire	Règles
url	string	oui	—
fingerprint	string	oui	correspond à ^[0-9a-f]{64}$; peut être null
code	string	oui	jusqu’à 32 caractères

Réponse 201

Champ	Type	Obligatoire	Règles
id	string (uuid)	oui	—
name	string	oui	—
url	string	oui	—
fingerprint	string	oui	correspond à ^[0-9a-f]{64}$; peut être null
addedBy	string	oui	—
addedAt	string (date-time)	oui	—
seenAt	string (date-time)	oui	peut être null
state	string	oui	une valeur parmi pending, ok, unreachable, certificate, revoked, invalid, refused
error	string	oui	peut être null
topology	object	oui	peut être null
topology.collectedAt	string (date-time)	oui	—
topology.site	object	oui	—
topology.site.name	string	oui	—
topology.site.version	string	oui	—
topology.site.schema	integer	oui	au moins 0
topology.site.role	string	oui	une valeur parmi api, reader
topology.health	object	oui	—
topology.health.available	boolean	oui	—
topology.health.writable	boolean	oui	—
topology.health.draining	boolean	oui	—
topology.replication	object	oui	peut être null
topology.replication.copies	integer	oui	0–16
topology.replication.required	integer	oui	1–16
topology.replication.singleCopyUntil	string (date-time)	oui	peut être null
topology.replication.node	string	non	jusqu’à 63 caractères
topology.replication.profile	string	non	une valeur parmi ha-2, ha-3
topology.replication.peers	tableau de object	non	jusqu’à 16 éléments
topology.gateways	tableau de object	oui	jusqu’à 16 éléments
topology.gateways[].slot	integer	oui	au moins 0
topology.gateways[].active	boolean	oui	—
topology.gateways[].expiresAt	string (date-time)	oui	—
topology.mirrors	tableau de object	oui	jusqu’à 64 éléments
topology.mirrors[].repository	string	oui	—
topology.mirrors[].mode	string	oui	une valeur parmi mirror, import
topology.mirrors[].upstream	string	oui	—
topology.mirrors[].sourceRepository	string	oui	—
topology.mirrors[].phase	string	oui	—
topology.mirrors[].errorCode	string	oui	peut être null
topology.mirrors[].checkedAt	string (date-time)	oui	peut être null
topology.mirrors[].syncedAt	string (date-time)	oui	peut être null
topology.mirrors[].lagChanges	string	oui	un nombre entier en chiffres décimaux, transmis sous forme de chaîne; peut être null
topology.mirrors[].copiedArtifacts	integer	oui	au moins 0
topology.mirrors[].copiedBytes	string	oui	un nombre entier en chiffres décimaux, transmis sous forme de chaîne
topology.updates	object	oui	peut être null
topology.updates.currentVersion	string	oui	—
topology.updates.latest	string	oui	peut être null
topology.updates.phase	string	oui	—
topology.updates.error	string	oui	peut être null
topology.updates.automatic	boolean	oui	—
topology.updates.heartbeatAt	string (date-time)	oui	—
topology.downloads	object	oui	—
topology.downloads.strategy	string	oui	une valeur parmi ordered, smallest-first, shared
topology.downloads.sessions	integer	oui	au moins 0
topology.downloads.active	integer	oui	au moins 0
topology.downloads.waiting	integer	oui	au moins 0
topology.downloads.oldestWaitSeconds	integer	oui	au moins 0
topology.downloads.bytesPerSecond	integer	oui	au moins 0

Réponses: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Exemple

curl -X POST "$ARKVORY_URL/api/v1/fleet/sites" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"<url>","fingerprint":"<fingerprint>","code":"<code>"}'

Lire le certificat d’un site

POST /api/v1/fleet/sites/probe

Accès: Administrateur · Nouvelle tentative: Peut être répétée sans risque : la même requête a le même effet

Se connecte à l’adresse et lit le certificat du site sans rien envoyer : comparez son fingerprint avec celle que voit l’administrateur du site avant l’appairage.

Corps de la requête (application/json)

Champ	Type	Obligatoire	Règles
url	string	oui	—

Réponse 200

Champ	Type	Obligatoire	Règles
url	string	oui	—
certificate	object	oui	peut être null
certificate.fingerprint	string	oui	correspond à ^[0-9a-f]{64}$
certificate.subject	string	oui	—
certificate.issuer	string	oui	—
certificate.validTo	string (date-time)	oui	—

Réponses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Exemple

curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/probe" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"<url>"}'

Oublier un site

DELETE /api/v1/fleet/sites/{id}

Accès: Administrateur · Nouvelle tentative: Peut être répétée sans risque : la même requête a le même effet

Oublie ici un site et sa clé scellée. Révoquez aussi ce contrôleur sur le site ; jusque-là, la clé y reste valable.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
id	chemin	string (uuid)	oui	—

Réponses: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

Exemple

curl -X DELETE "$ARKVORY_URL/api/v1/fleet/sites/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Lire le catalogue d’un site

GET HEAD /api/v1/fleet/sites/{id}/read

Accès: Administrateur · Nouvelle tentative: Peut être répétée sans risque (lecture)

Transmet une lecture du catalogue à un site géré et renvoie sa réponse telle quelle : dépôts, recherche, artefacts, annotations, étapes, paquets, pages et historique des fichiers, espace utilisé, état du miroir. path est la route du site avec sa requête. Les autres routes et les octets des fichiers sont refusés avec 400.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
id	chemin	string (uuid)	oui	—
path	requête	string	oui	correspond à ^/api/v1/; jusqu’à 2048 caractères; A read route of the site with its query, from a fixed list: catalog metadata (repositories, search, artifacts, annotations, stages, packages, file pages and history, storage usage, mirror state), download queue settings and update state. Never file bytes.

Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemple

curl -X GET "$ARKVORY_URL/api/v1/fleet/sites/$ID/read?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Modifier un réglage d’un site

POST /api/v1/fleet/sites/{id}/change

Accès: Administrateur · Nouvelle tentative: Ne pas répéter automatiquement

Transmet une modification à un site géré et renvoie sa réponse telle quelle. path est l’une de ces routes : /api/v1/system/downloads/settings (réglages de la file de téléchargements, envoyé en PUT) ou /api/v1/system/updates/requests (une demande de mise à jour, envoyée en POST). Le corps est transmis tel quel ; le site vérifie la révision ou l’id de la demande, une modification répétée ne s’applique donc pas deux fois. Les autres chemins sont refusés avec 400.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
id	chemin	string (uuid)	oui	—
path	requête	string	oui	correspond à ^/api/v1/; jusqu’à 2048 caractères; A change route of the site, from a fixed list: PUT /api/v1/system/downloads/settings, POST /api/v1/system/updates/requests.

Corps de la requête (application/json)

Réponses: 200, 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Exemple

curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/change?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Lire un site maintenant

POST /api/v1/fleet/sites/{id}/refresh

Accès: Administrateur · Nouvelle tentative: Peut être répétée sans risque : la même requête a le même effet

Lit le site maintenant au lieu d’attendre le prochain tour et le renvoie avec son nouvel état.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
id	chemin	string (uuid)	oui	—

Réponse 200

Champ	Type	Obligatoire	Règles
id	string (uuid)	oui	—
name	string	oui	—
url	string	oui	—
fingerprint	string	oui	correspond à ^[0-9a-f]{64}$; peut être null
addedBy	string	oui	—
addedAt	string (date-time)	oui	—
seenAt	string (date-time)	oui	peut être null
state	string	oui	une valeur parmi pending, ok, unreachable, certificate, revoked, invalid, refused
error	string	oui	peut être null
topology	object	oui	peut être null
topology.collectedAt	string (date-time)	oui	—
topology.site	object	oui	—
topology.site.name	string	oui	—
topology.site.version	string	oui	—
topology.site.schema	integer	oui	au moins 0
topology.site.role	string	oui	une valeur parmi api, reader
topology.health	object	oui	—
topology.health.available	boolean	oui	—
topology.health.writable	boolean	oui	—
topology.health.draining	boolean	oui	—
topology.replication	object	oui	peut être null
topology.replication.copies	integer	oui	0–16
topology.replication.required	integer	oui	1–16
topology.replication.singleCopyUntil	string (date-time)	oui	peut être null
topology.replication.node	string	non	jusqu’à 63 caractères
topology.replication.profile	string	non	une valeur parmi ha-2, ha-3
topology.replication.peers	tableau de object	non	jusqu’à 16 éléments
topology.gateways	tableau de object	oui	jusqu’à 16 éléments
topology.gateways[].slot	integer	oui	au moins 0
topology.gateways[].active	boolean	oui	—
topology.gateways[].expiresAt	string (date-time)	oui	—
topology.mirrors	tableau de object	oui	jusqu’à 64 éléments
topology.mirrors[].repository	string	oui	—
topology.mirrors[].mode	string	oui	une valeur parmi mirror, import
topology.mirrors[].upstream	string	oui	—
topology.mirrors[].sourceRepository	string	oui	—
topology.mirrors[].phase	string	oui	—
topology.mirrors[].errorCode	string	oui	peut être null
topology.mirrors[].checkedAt	string (date-time)	oui	peut être null
topology.mirrors[].syncedAt	string (date-time)	oui	peut être null
topology.mirrors[].lagChanges	string	oui	un nombre entier en chiffres décimaux, transmis sous forme de chaîne; peut être null
topology.mirrors[].copiedArtifacts	integer	oui	au moins 0
topology.mirrors[].copiedBytes	string	oui	un nombre entier en chiffres décimaux, transmis sous forme de chaîne
topology.updates	object	oui	peut être null
topology.updates.currentVersion	string	oui	—
topology.updates.latest	string	oui	peut être null
topology.updates.phase	string	oui	—
topology.updates.error	string	oui	peut être null
topology.updates.automatic	boolean	oui	—
topology.updates.heartbeatAt	string (date-time)	oui	—
topology.downloads	object	oui	—
topology.downloads.strategy	string	oui	une valeur parmi ordered, smallest-first, shared
topology.downloads.sessions	integer	oui	au moins 0
topology.downloads.active	integer	oui	au moins 0
topology.downloads.waiting	integer	oui	au moins 0
topology.downloads.oldestWaitSeconds	integer	oui	au moins 0
topology.downloads.bytesPerSecond	integer	oui	au moins 0

Réponses: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507

Exemple

curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/refresh" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Créer un code d’appairage

POST /api/v1/system/fleet/pairings

Accès: Administrateur · Nouvelle tentative: Ne pas répéter automatiquement

Crée un code à usage unique, valable dix minutes, que l’administrateur d’un contrôleur saisit pour gérer ce site. Le code est affiché une fois et n’est conservé que sous forme d’empreinte. Seul l’administrateur global du site peut le créer.

Réponse 201

Champ	Type	Obligatoire	Règles
code	string	oui	correspond à ^[0-9A-Z]{4}-[0-9A-Z]{4}-[0-9A-Z]{4}$
expiresAt	string (date-time)	oui	—
fingerprint	string	oui	correspond à ^[0-9a-f]{64}$; peut être null

Réponses: 201, 400, 401, 403, 404, 405, 409, 422, 503, 507

Exemple

curl -X POST "$ARKVORY_URL/api/v1/system/fleet/pairings" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Lister les contrôleurs du site

GET HEAD /api/v1/system/fleet/controllers

Accès: Administrateur · Nouvelle tentative: Peut être répétée sans risque (lecture)

Liste les contrôleurs autorisés à gérer ce site : nom, qui les a appairés, quand, et quand leur clé a servi pour la dernière fois.

Réponse 200

Champ	Type	Obligatoire	Règles
items	tableau de object	oui	jusqu’à 100 éléments
items[].id	string (uuid)	oui	—
items[].name	string	oui	—
items[].pairedBy	string	oui	—
items[].pairedAt	string (date-time)	oui	—
items[].usedAt	string (date-time)	oui	peut être null

Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemple

curl -X GET "$ARKVORY_URL/api/v1/system/fleet/controllers" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Révoquer un contrôleur

DELETE /api/v1/system/fleet/controllers/{id}

Accès: Administrateur · Nouvelle tentative: Peut être répétée sans risque : la même requête a le même effet

Révoque un contrôleur : sa clé de flotte est refusée immédiatement. Pour gérer à nouveau le site, il doit être appairé avec un nouveau code.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
id	chemin	string (uuid)	oui	—

Réponses: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

Exemple

curl -X DELETE "$ARKVORY_URL/api/v1/system/fleet/controllers/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

S’appairer à un contrôleur

POST /api/v1/system/fleet/enrollment

Accès: Tout le monde, sans clé · Nouvelle tentative: Ne pas répéter automatiquement

Échange une seule fois un code d’appairage valide contre une clé de flotte. Le contrôleur l’appelle par TLS épinglé sur l’empreinte confirmée par l’administrateur. La clé est renvoyée une fois et n’atteint que les routes dont un contrôleur a besoin.

Corps de la requête (application/json)

Champ	Type	Obligatoire	Règles
code	string	oui	jusqu’à 32 caractères
name	string	oui	1–63 caractères

Réponse 201

Champ	Type	Obligatoire	Règles
key	string	oui	correspond à ^afk_[A-Za-z0-9_-]{43}$
site	object	oui	—
site.name	string	oui	—
site.version	string	oui	—

Réponses: 201, 400, 403, 405, 413, 415, 503

Exemple

curl -X POST "$ARKVORY_URL/api/v1/system/fleet/enrollment" \
  -H "Content-Type: application/json" \
  -d '{"code":"<code>","name":"<name>"}'

Lire ce site pour la console de flotte

GET HEAD /api/v1/system/topology

Accès: Administrateur · Nouvelle tentative: Peut être répétée sans risque (lecture)

Renvoie cette installation comme un site d’une flotte (ADR 0077) : nom, version, schéma et rôle, disponibilité et acceptation des écritures, copies et nœuds HA, passerelles de lecture d’après leurs baux, chaque miroir et import avec sa phase, sa dernière synchronisation et lagChanges (changements de la source pas encore appliqués), l’état de l’agent de mise à jour et la file des téléchargements. Seul l’administrateur global du site ou un contrôleur appairé peut le lire.

Réponse 200

Champ	Type	Obligatoire	Règles
collectedAt	string (date-time)	oui	—
site	object	oui	—
site.name	string	oui	—
site.version	string	oui	—
site.schema	integer	oui	au moins 0
site.role	string	oui	une valeur parmi api, reader
health	object	oui	—
health.available	boolean	oui	—
health.writable	boolean	oui	—
health.draining	boolean	oui	—
replication	object	oui	peut être null
replication.copies	integer	oui	0–16
replication.required	integer	oui	1–16
replication.singleCopyUntil	string (date-time)	oui	peut être null
replication.node	string	non	jusqu’à 63 caractères
replication.profile	string	non	une valeur parmi ha-2, ha-3
replication.peers	tableau de object	non	jusqu’à 16 éléments
replication.peers[].name	string	oui	jusqu’à 63 caractères
replication.peers[].connected	boolean	oui	—
replication.peers[].disk	string	oui	jusqu’à 24 caractères
replication.peers[].complete	boolean	oui	—
replication.peers[].witness	boolean	oui	—
gateways	tableau de object	oui	jusqu’à 16 éléments
gateways[].slot	integer	oui	au moins 0
gateways[].active	boolean	oui	—
gateways[].expiresAt	string (date-time)	oui	—
mirrors	tableau de object	oui	jusqu’à 64 éléments
mirrors[].repository	string	oui	—
mirrors[].mode	string	oui	une valeur parmi mirror, import
mirrors[].upstream	string	oui	—
mirrors[].sourceRepository	string	oui	—
mirrors[].phase	string	oui	—
mirrors[].errorCode	string	oui	peut être null
mirrors[].checkedAt	string (date-time)	oui	peut être null
mirrors[].syncedAt	string (date-time)	oui	peut être null
mirrors[].lagChanges	string	oui	un nombre entier en chiffres décimaux, transmis sous forme de chaîne; peut être null
mirrors[].copiedArtifacts	integer	oui	au moins 0
mirrors[].copiedBytes	string	oui	un nombre entier en chiffres décimaux, transmis sous forme de chaîne
updates	object	oui	peut être null
updates.currentVersion	string	oui	—
updates.latest	string	oui	peut être null
updates.phase	string	oui	—
updates.error	string	oui	peut être null
updates.automatic	boolean	oui	—
updates.heartbeatAt	string (date-time)	oui	—
downloads	object	oui	—
downloads.strategy	string	oui	une valeur parmi ordered, smallest-first, shared
downloads.sessions	integer	oui	au moins 0
downloads.active	integer	oui	au moins 0
downloads.waiting	integer	oui	au moins 0
downloads.oldestWaitSeconds	integer	oui	au moins 0
downloads.bytesPerSecond	integer	oui	au moins 0

Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemple

curl -X GET "$ARKVORY_URL/api/v1/system/topology" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Lire les réglages de la file de téléchargements

GET HEAD /api/v1/system/downloads/settings

Accès: Administrateur · Nouvelle tentative: Peut être répétée sans risque (lecture)

Renvoie les valeurs modifiées (overrides), ce que fixe l’environnement du serveur (defaults) et ce que la file utilise maintenant (effective), avec la révision à renvoyer lors d’une modification. problem indique pourquoi les réglages enregistrés ne conviennent pas à ce serveur ; la file fonctionne alors avec les valeurs par défaut.

Réponse 200

Champ	Type	Obligatoire	Règles
revision	integer	oui	0–9007199254740991
overrides	object	oui	—
overrides.strategy	string	non	une valeur parmi ordered, smallest-first, shared
overrides.sessions	integer	non	1–1024
overrides.reserve	integer	non	0–1023
overrides.perPrincipal	integer	non	1–1024
overrides.weights	object	non	—
overrides.weights.interactive	integer	oui	1–1000
overrides.weights.release	integer	oui	1–1000
overrides.weights.bulk	integer	oui	1–1000
overrides.weights.background	integer	oui	1–1000
overrides.sessionMinBytes	integer	non	0–9007199254740991
overrides.idleSeconds	integer	non	1–3600
overrides.agingMinutes	integer	non	0–10080
overrides.preempt	boolean	non	—
overrides.rangesPerSession	integer	non	1–64
defaults	object	oui	—
defaults.strategy	string	oui	une valeur parmi ordered, smallest-first, shared
defaults.sessions	integer	oui	1–1024
defaults.reserve	integer	oui	0–1023
defaults.perPrincipal	integer	oui	1–1024
defaults.weights	object	oui	—
defaults.weights.interactive	integer	oui	1–1000
defaults.weights.release	integer	oui	1–1000
defaults.weights.bulk	integer	oui	1–1000
defaults.weights.background	integer	oui	1–1000
defaults.sessionMinBytes	integer	oui	0–9007199254740991
defaults.idleSeconds	integer	oui	1–3600
defaults.agingMinutes	integer	oui	0–10080
defaults.preempt	boolean	oui	—
defaults.rangesPerSession	integer	oui	1–64
effective	object	oui	—
effective.strategy	string	oui	une valeur parmi ordered, smallest-first, shared
effective.sessions	integer	oui	1–1024
effective.reserve	integer	oui	0–1023
effective.perPrincipal	integer	oui	1–1024
effective.weights	object	oui	—
effective.weights.interactive	integer	oui	1–1000
effective.weights.release	integer	oui	1–1000
effective.weights.bulk	integer	oui	1–1000
effective.weights.background	integer	oui	1–1000
effective.sessionMinBytes	integer	oui	0–9007199254740991
effective.idleSeconds	integer	oui	1–3600
effective.agingMinutes	integer	oui	0–10080
effective.preempt	boolean	oui	—
effective.rangesPerSession	integer	oui	1–64
admission	string	oui	une valeur parmi sessions, per-request
updatedAt	string (date-time)	oui	peut être null
updatedBy	string	oui	peut être null
actor	string	oui	peut être null
problem	string	oui	peut être null

Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemple

curl -X GET "$ARKVORY_URL/api/v1/system/downloads/settings" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Modifier les réglages de la file de téléchargements

PUT /api/v1/system/downloads/settings

Accès: Administrateur · Nouvelle tentative: Répéter uniquement avec la révision attendue (compare-and-swap)

Enregistre overrides par-dessus l’environnement du serveur et les applique sans redémarrage : les nouvelles décisions les suivent aussitôt, les téléchargements actifs gardent leur place. Les valeurs transmises remplacent toutes les modifications précédentes ; {} revient à l’environnement. Des réglages qui ne peuvent pas fonctionner ici sont refusés avec 400 en nommant le champ ; une expectedRevision périmée reçoit 409. Les passerelles de lecture gardent leur environnement.

Corps de la requête (application/json)

Champ	Type	Obligatoire	Règles
expectedRevision	integer	oui	0–9007199254740991
overrides	object	oui	—
overrides.strategy	string	non	une valeur parmi ordered, smallest-first, shared
overrides.sessions	integer	non	1–1024
overrides.reserve	integer	non	0–1023
overrides.perPrincipal	integer	non	1–1024
overrides.weights	object	non	—
overrides.weights.interactive	integer	oui	1–1000
overrides.weights.release	integer	oui	1–1000
overrides.weights.bulk	integer	oui	1–1000
overrides.weights.background	integer	oui	1–1000
overrides.sessionMinBytes	integer	non	0–9007199254740991
overrides.idleSeconds	integer	non	1–3600
overrides.agingMinutes	integer	non	0–10080
overrides.preempt	boolean	non	—
overrides.rangesPerSession	integer	non	1–64

Réponse 200

Champ	Type	Obligatoire	Règles
revision	integer	oui	0–9007199254740991
overrides	object	oui	—
overrides.strategy	string	non	une valeur parmi ordered, smallest-first, shared
overrides.sessions	integer	non	1–1024
overrides.reserve	integer	non	0–1023
overrides.perPrincipal	integer	non	1–1024
overrides.weights	object	non	—
overrides.weights.interactive	integer	oui	1–1000
overrides.weights.release	integer	oui	1–1000
overrides.weights.bulk	integer	oui	1–1000
overrides.weights.background	integer	oui	1–1000
overrides.sessionMinBytes	integer	non	0–9007199254740991
overrides.idleSeconds	integer	non	1–3600
overrides.agingMinutes	integer	non	0–10080
overrides.preempt	boolean	non	—
overrides.rangesPerSession	integer	non	1–64
defaults	object	oui	—
defaults.strategy	string	oui	une valeur parmi ordered, smallest-first, shared
defaults.sessions	integer	oui	1–1024
defaults.reserve	integer	oui	0–1023
defaults.perPrincipal	integer	oui	1–1024
defaults.weights	object	oui	—
defaults.weights.interactive	integer	oui	1–1000
defaults.weights.release	integer	oui	1–1000
defaults.weights.bulk	integer	oui	1–1000
defaults.weights.background	integer	oui	1–1000
defaults.sessionMinBytes	integer	oui	0–9007199254740991
defaults.idleSeconds	integer	oui	1–3600
defaults.agingMinutes	integer	oui	0–10080
defaults.preempt	boolean	oui	—
defaults.rangesPerSession	integer	oui	1–64
effective	object	oui	—
effective.strategy	string	oui	une valeur parmi ordered, smallest-first, shared
effective.sessions	integer	oui	1–1024
effective.reserve	integer	oui	0–1023
effective.perPrincipal	integer	oui	1–1024
effective.weights	object	oui	—
effective.weights.interactive	integer	oui	1–1000
effective.weights.release	integer	oui	1–1000
effective.weights.bulk	integer	oui	1–1000
effective.weights.background	integer	oui	1–1000
effective.sessionMinBytes	integer	oui	0–9007199254740991
effective.idleSeconds	integer	oui	1–3600
effective.agingMinutes	integer	oui	0–10080
effective.preempt	boolean	oui	—
effective.rangesPerSession	integer	oui	1–64
admission	string	oui	une valeur parmi sessions, per-request
updatedAt	string (date-time)	oui	peut être null
updatedBy	string	oui	peut être null
actor	string	oui	peut être null
problem	string	oui	peut être null

Réponses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Exemple

curl -X PUT "$ARKVORY_URL/api/v1/system/downloads/settings" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0,"overrides":{}}'

Lire les modifications du site

GET HEAD /api/v1/system/changes

Accès: Administrateur · Nouvelle tentative: Peut être répétée sans risque (lecture)

Indique si l’agent du site se signale (agent), la demande en attente et les 20 plus récentes avec leur état : pending, applying, done ou failed avec la raison. Les clés de source n’apparaissent jamais ici.

Réponse 200

Champ	Type	Obligatoire	Règles
agent	boolean	oui	—
updating	boolean	oui	—
blocked	string	oui	une valeur parmi expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; peut être null
pending	object	oui	peut être null
pending.id	string (uuid)	oui	—
pending.kind	string	oui	une valeur parmi mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy
pending.actor	string	oui	jusqu’à 200 caractères
pending.requestedAt	string (date-time)	oui	—
recent	tableau de object	oui	jusqu’à 20 éléments
recent[].id	string (uuid)	oui	—
recent[].digest	string	oui	correspond à ^[0-9a-f]{64}$
recent[].kind	string	oui	une valeur parmi mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy
recent[].state	string	oui	une valeur parmi pending, applying, done, failed
recent[].error	string	oui	une valeur parmi expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; peut être null
recent[].actor	string	oui	jusqu’à 200 caractères
recent[].requestedAt	string (date-time)	oui	—
recent[].finishedAt	string (date-time)	oui	peut être null

Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemple

curl -X GET "$ARKVORY_URL/api/v1/system/changes" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Mettre en file une modification du site

POST /api/v1/system/changes

Accès: Administrateur · Nouvelle tentative: Peut être répétée sans risque : la même requête a le même effet

Met en file une modification pour l’agent du site, qui l’applique en moins d’une minute avec les vérifications et le retour arrière de arkvory configure et cluster-* : rattacher un miroir ou un import, remplacer sa clé de source, détacher des miroirs, basculer le nœud HA actif (nom du nœud saisi deux fois) ou décider des écritures avec une seule copie. id est choisi par le client ; le répéter ne remet pas la modification en file. key est la clé de source de mirror-attach et mirror-key uniquement : elle va à l’agent dans son propre fichier 0600 et n’est jamais renvoyée. 202 signifie en file, pas appliqué.

Corps de la requête (application/json)

Champ	Type	Obligatoire	Règles
id	string (uuid)	oui	—
change	object	oui	—
change.kind	string	oui	une valeur parmi mirror-attach
change.repository	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
change.upstream	string	oui	jusqu’à 255 caractères
change.sourceRepository	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
change.stages	tableau de string	non	1–16 éléments; chaque élément : correspond à ^[a-z0-9][a-z0-9_.-]{0,31}$; peut être null
change.repositories	tableau de string	oui	1–64 éléments; chaque élément : correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
change.node	string	oui	correspond à ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$
change.confirm	string	oui	correspond à ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$
change.until	string (date-time)	oui	peut être null
change.reason	string	oui	1–200 caractères
key	string	non	16–4000 caractères

Réponse 202

Champ	Type	Obligatoire	Règles
id	string (uuid)	oui	—

Réponses: 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Exemple

curl -X POST "$ARKVORY_URL/api/v1/system/changes" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"00000000-0000-4000-8000-000000000000","change":{"kind":"mirror-attach","repository":"<repository>","upstream":"<upstream>","sourceRepository":"<sourceRepository>"}}'

Suivre le flux des modifications d’un dépôt

GET HEAD /api/v1/repositories/{repository}/changes

Accès: Autorisation sur le dépôt : artifact.list; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)

Renvoie, dans l’ordre de validation, jusqu’à limit modifications (1–100, 100 par défaut) après la séquence after (0 par défaut) : action, artefact et, pour les chemins de fichiers et les étapes, le chemin ou l’étape dans detail ; les acteurs sont omis, de sorte que le droit de lister suffit. head est la séquence la plus récente du dépôt, next le curseur de la page suivante, ou null lorsque la page a atteint la séquence la plus récente. Un miroir stocke la dernière séquence appliquée et interroge à partir de là.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
repository	chemin	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
after	requête	string	non	un nombre entier en chiffres décimaux, transmis sous forme de chaîne; Sequence cursor, default 0
limit	requête	integer	non	1–100

Réponse 200

Champ	Type	Obligatoire	Règles
items	tableau de object	oui	—
items[].sequence	string	oui	un nombre entier en chiffres décimaux, transmis sous forme de chaîne
items[].action	string	oui	—
items[].artifactId	string (uuid)	oui	—
items[].detail	string	oui	peut être null
head	string	oui	un nombre entier en chiffres décimaux, transmis sous forme de chaîne
next	string	oui	un nombre entier en chiffres décimaux, transmis sous forme de chaîne; peut être null

Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemple

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/changes" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Créer un lien de téléchargement

POST /api/v1/repositories/{repository}/artifacts/{id}/links

Accès: Autorisation sur le dépôt : content.read; clés de fichier : read · Nouvelle tentative: Ne pas répéter automatiquement

Renvoie un token secret, une url relative à l’origine de l’API et expiresAt pour un downloadArtifact de cet artefact seul, sans clé ; ttlSeconds fixe la durée de vie (de 60 secondes à un jour, une heure par défaut). Le jeton n’est montré que dans cette réponse et ne peut pas être révoqué : il cesse de fonctionner à son expiration ou à la suppression de l’artefact, et les téléchargements qui l’utilisent comptent dans les limites de transfert de son créateur. Un appelant peut détenir 1000 liens actifs (507 token_limit), et un lien de téléchargement ne peut pas créer d’autres liens.

Paramètres

Nom	Emplacement	Type	Obligatoire	Règles
repository	chemin	string	oui	correspond à ^[a-z0-9][a-z0-9_-]{0,63}$
id	chemin	string (uuid)	oui	—

Corps de la requête (application/json)

Champ	Type	Obligatoire	Règles
ttlSeconds	integer	non	60–86400; par défaut 3600

Réponse 201

Champ	Type	Obligatoire	Règles
token	string	oui	correspond à ^dtl_[A-Za-z0-9_-]{43}$
url	string	oui	—
expiresAt	string (date-time)	oui	—

Réponses: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Exemple

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/links" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'