Artefactos y catálogo
Artefactos publicados: listado, detalles, contenido, anotaciones, referencias, búsqueda, la auditoría del catálogo y su fuente de cambios.
Operaciones de este grupo con su regla de acceso, su regla de reintento, sus parámetros y sus respuestas. Cada solicitud lleva una clave: Authorization: Bearer <clave> (consulte «Autenticación»).
Operaciones
Obtener las anotaciones de un artefacto
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/annotations
Acceso: Permiso de repositorio: annotation.read; claves de archivo: read · Reintento: Se puede repetir (lectura)
Devuelve las etiquetas, los metadatos y las colecciones actuales de un artefacto publicado con su revision. La revisión 0 significa que nunca se reemplazaron: las etiquetas y los metadatos son los indicados al crear la subida y las colecciones están vacías. Pase la revisión a setAnnotations como expectedRevision.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | ruta | string (uuid) | sí | — |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
revision | integer | sí | 0–2147483647 |
labels | array de string | sí | hasta 32 elementos |
metadata | mapa de string | sí | hasta 32 entradas |
collections | array de string | sí | hasta 32 elementos |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/annotations" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Reemplazar las anotaciones de un artefacto
PUT /api/v1/repositories/{repository}/artifacts/{id}/annotations
Acceso: Permiso de repositorio: annotation.write, artifact.read; claves de archivo: read, write · Reintento: Repetir solo con la revisión esperada (compare-and-swap)
Reemplaza labels, metadata y collections de un artefacto publicado de una sola vez; un campo omitido en value queda vacío. expectedRevision debe ser la revisión actual (0 para el primer cambio); de lo contrario, 409 revision_mismatch: lea de nuevo las anotaciones y vuelva a aplicar el cambio. Hasta 32 etiquetas y 32 colecciones (1–64 letras, dígitos o _.:-) y 32 entradas de metadatos (valores de hasta 1024 caracteres); los bytes y el descriptor original nunca cambian.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | ruta | string (uuid) | sí | — |
Cuerpo de la solicitud (application/json)
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
expectedRevision | integer | sí | 0–2147483646 |
value | object | sí | — |
value.labels | array de string | no | hasta 32 elementos |
value.metadata | mapa de string | no | hasta 32 entradas |
value.collections | array de string | no | hasta 32 elementos |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
revision | integer | sí | 0–2147483647 |
labels | array de string | sí | hasta 32 elementos |
metadata | mapa de string | sí | hasta 32 entradas |
collections | array de string | sí | hasta 32 elementos |
Respuestas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Ejemplo
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":{}}'Registrar un artefacto como paquete UPack
POST /api/v1/repositories/{repository}/artifacts/{id}/package
Acceso: Permiso de repositorio: package.publish, artifact.read; claves de archivo: read, write · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto
Abre el artefacto publicado como un ZIP de UPack, lee el upack.json de la raíz (name, group opcional y version SemVer) y registra esa versión del paquete para él; los archivos ZIP no seguros o no válidos se rechazan con 400. Una versión es inmutable: registrar el mismo artefacto de nuevo devuelve la misma entrada, y otro artefacto para un grupo, nombre y versión ya existentes (comparados sin distinguir mayúsculas) produce un 409 version_exists. Después la versión aparece en listPackages y se resuelve por nombre, rango y etapa.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | ruta | string (uuid) | sí | — |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
group | string | no | — |
name | string | no | — |
version | string | no | — |
artifactId | string (uuid) | no | — |
manifest | object | no | — |
Respuestas: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Ejemplo
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/package" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Buscar artefactos
GET HEAD /api/v1/repositories/{repository}/search
Acceso: Permiso de repositorio: artifact.list; claves de archivo: read · Reintento: Se puede repetir (lectura)
Encuentra artefactos publicados por q (una subcadena, sin distinguir mayúsculas, del nombre o de un valor de metadatos actual), una label actual exacta, una collection y un par exacto metadataKey/metadataValue, que van juntos; deben cumplirse todos los filtros indicados. Los resultados llegan en páginas de 100 ordenadas por ID, cada uno con tamaño, horas de creación y de publicación, etiquetas actuales y etapas de promoción; continúe pasando next como after. Los metadatos y las colecciones no se devuelven: léalos con getAnnotations.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
q | consulta | string | no | — |
label | consulta | string | no | — |
collection | consulta | string | no | — |
after | consulta | string | no | — |
metadataKey | consulta | string | no | coincide con ^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$; hasta 64 caracteres; Exact metadata key; requires metadataValue. |
metadataValue | consulta | string | no | hasta 1024 caracteres; Exact case-sensitive value; requires metadataKey. Empty string is allowed. |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
items | array de object | sí | hasta 100 elementos |
items[].id | string (uuid) | sí | — |
items[].name | string | sí | — |
items[].size | string | sí | un número entero en dígitos decimales, enviado como cadena; Tamaño en bytes, cadena decimal |
items[].createdAt | string (date-time) | sí | Hora de reserva de la subida |
items[].publishedAt | string (date-time) | sí | puede ser null; Hora de publicación; null solo cuando no se registró ninguna |
items[].labels | array de string | sí | hasta 32 elementos; Etiquetas actuales: la anotación si se reemplazó; en otro caso, el descriptor de la subida |
items[].stages | array de string | sí | hasta 16 elementos; cada elemento: coincide con ^[a-z0-9][a-z0-9_.-]{0,31}$; Etapas de promoción actuales en orden de bytes |
next | string (uuid) | sí | puede ser null; Último ID de una página completa; páselo como after |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/search" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Leer la auditoría del catálogo de un repositorio
GET HEAD /api/v1/repositories/{repository}/audit
Acceso: Permiso de repositorio: audit.read; claves de archivo: write · Reintento: Se puede repetir (lectura)
Devuelve, del más antiguo al más reciente, hasta 100 cambios del catálogo del repositorio posteriores al número de secuencia after (0 por defecto): publicaciones, eliminaciones, cambios de anotaciones y de adjuntos, registros de paquetes, cambios de rutas de archivo, referencias, etapas y promociones, cada uno con actor, acción, artefacto y hora. Para seguir leyendo, pase el último sequence de la página como after; no hay campo next. Las descargas y los inicios de sesión no figuran en ella; los espejos siguen listCatalogChanges, que omite los actores.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | consulta | string | no | — |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
items | array de object | no | — |
items[].sequence | string | no | — |
items[].actor | string | no | — |
items[].action | string | no | — |
items[].artifactId | string | no | — |
items[].occurredAt | string (date-time) | no | — |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/audit" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Añadir una referencia a un artefacto
POST /api/v1/repositories/{repository}/artifacts/{id}/references
Acceso: Permiso de repositorio: reference.write, artifact.read; claves de archivo: read, write · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto
Registra que algo ajeno a Arkvory usa este artefacto, bajo una key a su elección (1–256 letras, dígitos o _.:/-), por ejemplo el nombre de un despliegue. Un artefacto con referencias no se puede eliminar ni la retención puede retirarlo hasta que desaparezcan todas. La referencia pertenece al solicitante; añadir de nuevo la misma clave no cambia nada.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | ruta | string (uuid) | sí | — |
Cuerpo de la solicitud (application/json)
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
key | string | sí | hasta 256 caracteres |
Respuestas: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Ejemplo
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>"}'Quitar una referencia de un artefacto
DELETE /api/v1/repositories/{repository}/artifacts/{id}/references
Acceso: Permiso de repositorio: reference.write, artifact.read; claves de archivo: read, write · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto
Quita del artefacto la referencia propia del solicitante key; las referencias de otros solicitantes permanecen. Quitar una clave que no existe también se completa con éxito.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | ruta | string (uuid) | sí | — |
Cuerpo de la solicitud (application/json)
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
key | string | sí | hasta 256 caracteres |
Respuestas: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Ejemplo
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>"}'Listar artefactos
GET HEAD /api/v1/repositories/{repository}/artifacts
Acceso: Permiso de repositorio: artifact.list; claves de archivo: read · Reintento: Se puede repetir (lectura)
Enumera los artefactos publicados del repositorio ordenados por ID, limit por página (1–100, 50 por defecto); continúe pasando next como after. next se establece siempre que una página está llena, por lo que la última página puede estar vacía. Cada elemento lleva el descriptor indicado en la subida; las etiquetas y los metadatos actuales están en getAnnotations.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | consulta | string (uuid) | no | — |
limit | consulta | integer | no | 1–100; predeterminado: 50 |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
items | array de object | no | — |
items[].id | string (uuid) | sí | — |
items[].repository | string | sí | — |
items[].status | string | sí | uno de pending, available, cancelled |
items[].createdAt | string (date-time) | sí | — |
items[].expiresAt | string (date-time) | sí | — |
items[].descriptor | object | sí | — |
items[].descriptor.name | string | sí | 1–240 caracteres |
items[].descriptor.size | string | sí | un número entero en dígitos decimales, enviado como cadena |
items[].descriptor.sha256 | string | sí | SHA-256: 64 dígitos hexadecimales en minúsculas |
items[].descriptor.labels | array de string | no | hasta 32 elementos; cada elemento: hasta 64 caracteres |
items[].descriptor.metadata | mapa de string | no | hasta 32 entradas |
next | string | no | puede ser null |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Obtener un artefacto
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}
Acceso: Permiso de repositorio: artifact.read; claves de archivo: read · Reintento: Se puede repetir (lectura)
Devuelve un artefacto publicado: su ID, repositorio, estado, hora de creación y el descriptor indicado en la subida (nombre, tamaño, SHA-256, etiquetas y metadatos originales). Los artefactos pendientes, cancelados y eliminados responden 404. Para leer los bytes use downloadArtifact.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | ruta | string (uuid) | sí | — |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
id | string (uuid) | sí | — |
repository | string | sí | — |
status | string | sí | uno de pending, available, cancelled |
createdAt | string (date-time) | sí | — |
expiresAt | string (date-time) | sí | — |
descriptor | object | sí | — |
descriptor.name | string | sí | 1–240 caracteres |
descriptor.size | string | sí | un número entero en dígitos decimales, enviado como cadena |
descriptor.sha256 | string | sí | SHA-256: 64 dígitos hexadecimales en minúsculas |
descriptor.labels | array de string | no | hasta 32 elementos; cada elemento: hasta 64 caracteres |
descriptor.metadata | mapa de string | no | hasta 32 entradas |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Eliminar un artefacto
DELETE /api/v1/repositories/{repository}/artifacts/{id}
Acceso: Permiso de repositorio: artifact.delete · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto
Elimina lógicamente un artefacto publicado: desaparece de inmediato de las listas, las búsquedas y las descargas, y la limpieza física en línea del repositorio (setCleanup, desactivada por defecto) recupera sus bytes tras su período de gracia. expectedAnnotationRevision debe ser igual a la revisión actual de las anotaciones. La respuesta es 200 con un outcome: deleted, already_deleted, changed (la revisión difiere), not_found o protected con los blockers que lo retienen (una referencia, una revisión de ruta de archivo, un adjunto de compilación o una etapa de promoción). Compruébelo antes con inspectArtifactDeletion.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | ruta | string (uuid) | sí | — |
Cuerpo de la solicitud (application/json)
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
expectedAnnotationRevision | integer | sí | 0–2147483647 |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
id | string (uuid) | sí | — |
outcome | string | sí | uno de deleted, already_deleted, protected, changed, not_eligible, not_found |
blockers | array de string | sí | hasta 4 elementos; sin elementos repetidos; cada elemento: uno de reference, asset_history, attachment_history, protected_label, promotion_stage |
Respuestas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Ejemplo
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedAnnotationRevision":0}'Descargar un artefacto
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/content
Acceso: Permiso de repositorio: content.read; claves de archivo: read · Reintento: Se puede repetir (lectura)
Transmite los bytes originales con Content-Length, Content-Disposition (el nombre del artefacto) y un ETag fuerte ("sha256:<hex>"). Un único Range da 206 (uno no satisfacible, 416); If-Range con el ETag reanuda de forma segura y If-None-Match responde 304. HEAD devuelve las mismas cabeceras sin cuerpo e ignora Range. En lugar de una cabecera Authorization, la solicitud puede llevar como token un enlace de descarga creado con createDownloadLink; las descargas esperan una ranura libre de la admisión de descargas del servidor.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | ruta | string (uuid) | sí | — |
Range | encabezado | string | no | — |
If-Range | encabezado | string | no | — |
If-None-Match | encabezado | string | no | — |
Arkvory-Download-Id | encabezado | string | no | coincide con ^[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 | encabezado | string | no | hasta 80 caracteres; 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 | encabezado | string | no | uno de 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 | consulta | string | no | coincide con ^dtl_[A-Za-z0-9_-]{43}$; Download link from POST …/artifacts/{id}/links, instead of an Authorization header |
Respuestas: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/content" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o fileLeer el resumen de los sitios
GET HEAD /api/v1/fleet/overview
Acceso: Administrador · Reintento: Se puede repetir (lectura)
Alertas de los sitios gestionados y de esta instalación, las más graves primero (critical, warning, info), y los vínculos de espejo entre ellos. Se construye con las últimas lecturas en segundo plano, como mucho una vez cada 5 segundos. Un origen en cuya dirección no responde ningún sitio gestionado es external:<origin>; esta instalación es self y los vínculos hacia ella solo aparecen con ARKVORY_SITE_URL definido. Solo responde el proceso de escritura.
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
generatedAt | string (date-time) | sí | — |
self | object | sí | — |
self.name | string | sí | — |
self.version | string | sí | — |
self.url | string | sí | puede ser null |
alerts | array de object | sí | — |
alerts[].site | string | sí | — |
alerts[].name | string | sí | — |
alerts[].kind | string | sí | uno de unreachable, certificate, revoked, refused, invalid, stale, not-writable, copies, single-copy, mirror-failing, mirror-lag, updates-failed, version-skew |
alerts[].severity | string | sí | uno de critical, warning, info |
alerts[].subject | string | sí | puede ser null |
alerts[].since | string (date-time) | sí | puede ser null |
links | array de object | sí | — |
links[].from | string | sí | — |
links[].to | string | sí | — |
links[].repository | string | sí | — |
links[].sourceRepository | string | sí | — |
links[].mode | string | sí | uno de mirror, import |
links[].lagChanges | string | sí | un número entero en dígitos decimales, enviado como cadena; puede ser null |
links[].failing | boolean | sí | — |
links[].stale | boolean | no | — |
external | array de string | sí | — |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/fleet/overview" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Listar los sitios gestionados
GET HEAD /api/v1/fleet/sites
Acceso: Administrador · Reintento: Se puede repetir (lectura)
Lista los sitios que gestiona esta instalación (ADR 0077) con lo último que informó cada uno: state (ok, o por qué no se leyó: unreachable, certificate, revoked, invalid, refused), cuándo se vio por última vez y su última topology. Los sitios se leen cada 30 segundos en segundo plano. Nunca se devuelve la clave de un sitio.
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
items | array de object | sí | hasta 256 elementos |
items[].id | string (uuid) | sí | — |
items[].name | string | sí | — |
items[].url | string | sí | — |
items[].fingerprint | string | sí | coincide con ^[0-9a-f]{64}$; puede ser null |
items[].addedBy | string | sí | — |
items[].addedAt | string (date-time) | sí | — |
items[].seenAt | string (date-time) | sí | puede ser null |
items[].state | string | sí | uno de pending, ok, unreachable, certificate, revoked, invalid, refused |
items[].error | string | sí | puede ser null |
items[].topology | object | sí | puede ser null |
items[].topology.collectedAt | string (date-time) | sí | — |
items[].topology.site | object | sí | — |
items[].topology.health | object | sí | — |
items[].topology.replication | object | sí | puede ser null |
items[].topology.gateways | array de object | sí | hasta 16 elementos |
items[].topology.mirrors | array de object | sí | hasta 64 elementos |
items[].topology.updates | object | sí | puede ser null |
items[].topology.downloads | object | sí | — |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/fleet/sites" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Emparejar con un sitio
POST /api/v1/fleet/sites
Acceso: Administrador · Reintento: No repetir automáticamente
Empareja un sitio: el controlador vuelve a conectarse, el certificado debe seguir teniendo la fingerprint que confirmó el administrador (null para HTTP en loopback), el code de emparejamiento creado en el sitio se canjea por una clave y la clave se sella con ARKVORY_FLEET_KEY_FILE. El sitio se lee una vez antes de responder. Sin el archivo de clave la respuesta es 503.
Cuerpo de la solicitud (application/json)
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
url | string | sí | — |
fingerprint | string | sí | coincide con ^[0-9a-f]{64}$; puede ser null |
code | string | sí | hasta 32 caracteres |
Respuesta 201
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
id | string (uuid) | sí | — |
name | string | sí | — |
url | string | sí | — |
fingerprint | string | sí | coincide con ^[0-9a-f]{64}$; puede ser null |
addedBy | string | sí | — |
addedAt | string (date-time) | sí | — |
seenAt | string (date-time) | sí | puede ser null |
state | string | sí | uno de pending, ok, unreachable, certificate, revoked, invalid, refused |
error | string | sí | puede ser null |
topology | object | sí | puede ser null |
topology.collectedAt | string (date-time) | sí | — |
topology.site | object | sí | — |
topology.site.name | string | sí | — |
topology.site.version | string | sí | — |
topology.site.schema | integer | sí | como mínimo 0 |
topology.site.role | string | sí | uno de api, reader |
topology.health | object | sí | — |
topology.health.available | boolean | sí | — |
topology.health.writable | boolean | sí | — |
topology.health.draining | boolean | sí | — |
topology.replication | object | sí | puede ser null |
topology.replication.copies | integer | sí | 0–16 |
topology.replication.required | integer | sí | 1–16 |
topology.replication.singleCopyUntil | string (date-time) | sí | puede ser null |
topology.replication.node | string | no | hasta 63 caracteres |
topology.replication.profile | string | no | uno de ha-2, ha-3 |
topology.replication.peers | array de object | no | hasta 16 elementos |
topology.gateways | array de object | sí | hasta 16 elementos |
topology.gateways[].slot | integer | sí | como mínimo 0 |
topology.gateways[].active | boolean | sí | — |
topology.gateways[].expiresAt | string (date-time) | sí | — |
topology.mirrors | array de object | sí | hasta 64 elementos |
topology.mirrors[].repository | string | sí | — |
topology.mirrors[].mode | string | sí | uno de mirror, import |
topology.mirrors[].upstream | string | sí | — |
topology.mirrors[].sourceRepository | string | sí | — |
topology.mirrors[].phase | string | sí | — |
topology.mirrors[].errorCode | string | sí | puede ser null |
topology.mirrors[].checkedAt | string (date-time) | sí | puede ser null |
topology.mirrors[].syncedAt | string (date-time) | sí | puede ser null |
topology.mirrors[].lagChanges | string | sí | un número entero en dígitos decimales, enviado como cadena; puede ser null |
topology.mirrors[].copiedArtifacts | integer | sí | como mínimo 0 |
topology.mirrors[].copiedBytes | string | sí | un número entero en dígitos decimales, enviado como cadena |
topology.updates | object | sí | puede ser null |
topology.updates.currentVersion | string | sí | — |
topology.updates.latest | string | sí | puede ser null |
topology.updates.phase | string | sí | — |
topology.updates.error | string | sí | puede ser null |
topology.updates.automatic | boolean | sí | — |
topology.updates.heartbeatAt | string (date-time) | sí | — |
topology.downloads | object | sí | — |
topology.downloads.strategy | string | sí | uno de ordered, smallest-first, shared |
topology.downloads.sessions | integer | sí | como mínimo 0 |
topology.downloads.active | integer | sí | como mínimo 0 |
topology.downloads.waiting | integer | sí | como mínimo 0 |
topology.downloads.oldestWaitSeconds | integer | sí | como mínimo 0 |
topology.downloads.bytesPerSecond | integer | sí | como mínimo 0 |
Respuestas: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Ejemplo
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>"}'Leer el certificado de un sitio
POST /api/v1/fleet/sites/probe
Acceso: Administrador · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto
Se conecta a la dirección y lee el certificado del sitio sin enviar nada: compare su fingerprint con la que ve el administrador del sitio antes de emparejar.
Cuerpo de la solicitud (application/json)
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
url | string | sí | — |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
url | string | sí | — |
certificate | object | sí | puede ser null |
certificate.fingerprint | string | sí | coincide con ^[0-9a-f]{64}$ |
certificate.subject | string | sí | — |
certificate.issuer | string | sí | — |
certificate.validTo | string (date-time) | sí | — |
Respuestas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Ejemplo
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/probe" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"<url>"}'Olvidar un sitio
DELETE /api/v1/fleet/sites/{id}
Acceso: Administrador · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto
Olvida aquí un sitio y su clave sellada. Revoque también este controlador en el sitio; hasta entonces la clave sigue siendo válida allí.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
id | ruta | string (uuid) | sí | — |
Respuestas: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Ejemplo
curl -X DELETE "$ARKVORY_URL/api/v1/fleet/sites/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Leer el catálogo de un sitio
GET HEAD /api/v1/fleet/sites/{id}/read
Acceso: Administrador · Reintento: Se puede repetir (lectura)
Pasa una lectura del catálogo a un sitio gestionado y devuelve su respuesta sin cambios: repositorios, búsqueda, artefactos, anotaciones, etapas, paquetes, páginas e historial de archivos, uso de almacenamiento, estado del espejo. path es la ruta del sitio con su consulta. Otras rutas y los bytes de archivos se rechazan con 400.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
id | ruta | string (uuid) | sí | — |
path | consulta | string | sí | coincide con ^/api/v1/; hasta 2048 caracteres; 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. |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/fleet/sites/$ID/read?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Cambiar un ajuste de un sitio
POST /api/v1/fleet/sites/{id}/change
Acceso: Administrador · Reintento: No repetir automáticamente
Pasa un cambio a un sitio gestionado y devuelve su respuesta sin cambios. path es una de estas rutas: /api/v1/system/downloads/settings (ajustes de la cola de descargas, enviado como PUT) o /api/v1/system/updates/requests (una solicitud de actualización, enviada como POST). El cuerpo llega al sitio tal cual; el sitio comprueba la revisión o el id de la solicitud, así que un cambio repetido no se aplica dos veces. Otras rutas se rechazan con 400.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
id | ruta | string (uuid) | sí | — |
path | consulta | string | sí | coincide con ^/api/v1/; hasta 2048 caracteres; A change route of the site, from a fixed list: PUT /api/v1/system/downloads/settings, POST /api/v1/system/updates/requests. |
Cuerpo de la solicitud (application/json)
Respuestas: 200, 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Ejemplo
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/change?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Leer un sitio ahora
POST /api/v1/fleet/sites/{id}/refresh
Acceso: Administrador · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto
Lee el sitio ahora en lugar de esperar a la siguiente ronda y lo devuelve con el nuevo estado.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
id | ruta | string (uuid) | sí | — |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
id | string (uuid) | sí | — |
name | string | sí | — |
url | string | sí | — |
fingerprint | string | sí | coincide con ^[0-9a-f]{64}$; puede ser null |
addedBy | string | sí | — |
addedAt | string (date-time) | sí | — |
seenAt | string (date-time) | sí | puede ser null |
state | string | sí | uno de pending, ok, unreachable, certificate, revoked, invalid, refused |
error | string | sí | puede ser null |
topology | object | sí | puede ser null |
topology.collectedAt | string (date-time) | sí | — |
topology.site | object | sí | — |
topology.site.name | string | sí | — |
topology.site.version | string | sí | — |
topology.site.schema | integer | sí | como mínimo 0 |
topology.site.role | string | sí | uno de api, reader |
topology.health | object | sí | — |
topology.health.available | boolean | sí | — |
topology.health.writable | boolean | sí | — |
topology.health.draining | boolean | sí | — |
topology.replication | object | sí | puede ser null |
topology.replication.copies | integer | sí | 0–16 |
topology.replication.required | integer | sí | 1–16 |
topology.replication.singleCopyUntil | string (date-time) | sí | puede ser null |
topology.replication.node | string | no | hasta 63 caracteres |
topology.replication.profile | string | no | uno de ha-2, ha-3 |
topology.replication.peers | array de object | no | hasta 16 elementos |
topology.gateways | array de object | sí | hasta 16 elementos |
topology.gateways[].slot | integer | sí | como mínimo 0 |
topology.gateways[].active | boolean | sí | — |
topology.gateways[].expiresAt | string (date-time) | sí | — |
topology.mirrors | array de object | sí | hasta 64 elementos |
topology.mirrors[].repository | string | sí | — |
topology.mirrors[].mode | string | sí | uno de mirror, import |
topology.mirrors[].upstream | string | sí | — |
topology.mirrors[].sourceRepository | string | sí | — |
topology.mirrors[].phase | string | sí | — |
topology.mirrors[].errorCode | string | sí | puede ser null |
topology.mirrors[].checkedAt | string (date-time) | sí | puede ser null |
topology.mirrors[].syncedAt | string (date-time) | sí | puede ser null |
topology.mirrors[].lagChanges | string | sí | un número entero en dígitos decimales, enviado como cadena; puede ser null |
topology.mirrors[].copiedArtifacts | integer | sí | como mínimo 0 |
topology.mirrors[].copiedBytes | string | sí | un número entero en dígitos decimales, enviado como cadena |
topology.updates | object | sí | puede ser null |
topology.updates.currentVersion | string | sí | — |
topology.updates.latest | string | sí | puede ser null |
topology.updates.phase | string | sí | — |
topology.updates.error | string | sí | puede ser null |
topology.updates.automatic | boolean | sí | — |
topology.updates.heartbeatAt | string (date-time) | sí | — |
topology.downloads | object | sí | — |
topology.downloads.strategy | string | sí | uno de ordered, smallest-first, shared |
topology.downloads.sessions | integer | sí | como mínimo 0 |
topology.downloads.active | integer | sí | como mínimo 0 |
topology.downloads.waiting | integer | sí | como mínimo 0 |
topology.downloads.oldestWaitSeconds | integer | sí | como mínimo 0 |
topology.downloads.bytesPerSecond | integer | sí | como mínimo 0 |
Respuestas: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Ejemplo
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/refresh" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Crear un código de emparejamiento
POST /api/v1/system/fleet/pairings
Acceso: Administrador · Reintento: No repetir automáticamente
Crea un código de un solo uso, válido diez minutos, que el administrador de un controlador introduce para gestionar este sitio. El código se muestra una vez y solo se guarda como hash. Solo el administrador global del sitio puede crearlo.
Respuesta 201
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
code | string | sí | coincide con ^[0-9A-Z]{4}-[0-9A-Z]{4}-[0-9A-Z]{4}$ |
expiresAt | string (date-time) | sí | — |
fingerprint | string | sí | coincide con ^[0-9a-f]{64}$; puede ser null |
Respuestas: 201, 400, 401, 403, 404, 405, 409, 422, 503, 507
Ejemplo
curl -X POST "$ARKVORY_URL/api/v1/system/fleet/pairings" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Listar los controladores del sitio
GET HEAD /api/v1/system/fleet/controllers
Acceso: Administrador · Reintento: Se puede repetir (lectura)
Lista los controladores que pueden gestionar este sitio: nombre, quién los emparejó, cuándo y cuándo se usó su clave por última vez.
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
items | array de object | sí | hasta 100 elementos |
items[].id | string (uuid) | sí | — |
items[].name | string | sí | — |
items[].pairedBy | string | sí | — |
items[].pairedAt | string (date-time) | sí | — |
items[].usedAt | string (date-time) | sí | puede ser null |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/system/fleet/controllers" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Revocar un controlador
DELETE /api/v1/system/fleet/controllers/{id}
Acceso: Administrador · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto
Revoca un controlador: su clave de flota se rechaza de inmediato. Para volver a gestionar el sitio debe emparejarse con un código nuevo.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
id | ruta | string (uuid) | sí | — |
Respuestas: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Ejemplo
curl -X DELETE "$ARKVORY_URL/api/v1/system/fleet/controllers/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Emparejar con un controlador
POST /api/v1/system/fleet/enrollment
Acceso: Cualquiera, sin clave · Reintento: No repetir automáticamente
Canjea una vez un código de emparejamiento vigente por una clave de flota. El controlador lo llama por TLS fijado a la huella que confirmó el administrador. La clave se devuelve una vez y solo alcanza las rutas que necesita un controlador.
Cuerpo de la solicitud (application/json)
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
code | string | sí | hasta 32 caracteres |
name | string | sí | 1–63 caracteres |
Respuesta 201
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
key | string | sí | coincide con ^afk_[A-Za-z0-9_-]{43}$ |
site | object | sí | — |
site.name | string | sí | — |
site.version | string | sí | — |
Respuestas: 201, 400, 403, 405, 413, 415, 503
Ejemplo
curl -X POST "$ARKVORY_URL/api/v1/system/fleet/enrollment" \
-H "Content-Type: application/json" \
-d '{"code":"<code>","name":"<name>"}'Obtener este sitio para la consola de flota
GET HEAD /api/v1/system/topology
Acceso: Administrador · Reintento: Se puede repetir (lectura)
Devuelve esta instalación como un sitio de una flota (ADR 0077): nombre, versión, esquema y rol, si está disponible y admite escrituras, las copias y nodos de HA, las pasarelas de lectura según sus arrendamientos, cada espejo e importación con su fase, última sincronización y lagChanges (cambios del origen aún no aplicados), el estado del agente de actualizaciones y la cola de descargas. Solo puede leerlo el administrador global del sitio o un controlador emparejado con él.
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
collectedAt | string (date-time) | sí | — |
site | object | sí | — |
site.name | string | sí | — |
site.version | string | sí | — |
site.schema | integer | sí | como mínimo 0 |
site.role | string | sí | uno de api, reader |
health | object | sí | — |
health.available | boolean | sí | — |
health.writable | boolean | sí | — |
health.draining | boolean | sí | — |
replication | object | sí | puede ser null |
replication.copies | integer | sí | 0–16 |
replication.required | integer | sí | 1–16 |
replication.singleCopyUntil | string (date-time) | sí | puede ser null |
replication.node | string | no | hasta 63 caracteres |
replication.profile | string | no | uno de ha-2, ha-3 |
replication.peers | array de object | no | hasta 16 elementos |
replication.peers[].name | string | sí | hasta 63 caracteres |
replication.peers[].connected | boolean | sí | — |
replication.peers[].disk | string | sí | hasta 24 caracteres |
replication.peers[].complete | boolean | sí | — |
replication.peers[].witness | boolean | sí | — |
gateways | array de object | sí | hasta 16 elementos |
gateways[].slot | integer | sí | como mínimo 0 |
gateways[].active | boolean | sí | — |
gateways[].expiresAt | string (date-time) | sí | — |
mirrors | array de object | sí | hasta 64 elementos |
mirrors[].repository | string | sí | — |
mirrors[].mode | string | sí | uno de mirror, import |
mirrors[].upstream | string | sí | — |
mirrors[].sourceRepository | string | sí | — |
mirrors[].phase | string | sí | — |
mirrors[].errorCode | string | sí | puede ser null |
mirrors[].checkedAt | string (date-time) | sí | puede ser null |
mirrors[].syncedAt | string (date-time) | sí | puede ser null |
mirrors[].lagChanges | string | sí | un número entero en dígitos decimales, enviado como cadena; puede ser null |
mirrors[].copiedArtifacts | integer | sí | como mínimo 0 |
mirrors[].copiedBytes | string | sí | un número entero en dígitos decimales, enviado como cadena |
updates | object | sí | puede ser null |
updates.currentVersion | string | sí | — |
updates.latest | string | sí | puede ser null |
updates.phase | string | sí | — |
updates.error | string | sí | puede ser null |
updates.automatic | boolean | sí | — |
updates.heartbeatAt | string (date-time) | sí | — |
downloads | object | sí | — |
downloads.strategy | string | sí | uno de ordered, smallest-first, shared |
downloads.sessions | integer | sí | como mínimo 0 |
downloads.active | integer | sí | como mínimo 0 |
downloads.waiting | integer | sí | como mínimo 0 |
downloads.oldestWaitSeconds | integer | sí | como mínimo 0 |
downloads.bytesPerSecond | integer | sí | como mínimo 0 |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/system/topology" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Leer los ajustes de la cola de descargas
GET HEAD /api/v1/system/downloads/settings
Acceso: Administrador · Reintento: Se puede repetir (lectura)
Devuelve los valores cambiados (overrides), lo que fija el entorno del servidor (defaults) y lo que usa la cola ahora (effective), con la revisión que hay que enviar al cambiar. problem indica por qué los ajustes guardados no encajan en este servidor; entonces la cola funciona con los valores por defecto.
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
revision | integer | sí | 0–9007199254740991 |
overrides | object | sí | — |
overrides.strategy | string | no | uno de ordered, smallest-first, shared |
overrides.sessions | integer | no | 1–1024 |
overrides.reserve | integer | no | 0–1023 |
overrides.perPrincipal | integer | no | 1–1024 |
overrides.weights | object | no | — |
overrides.weights.interactive | integer | sí | 1–1000 |
overrides.weights.release | integer | sí | 1–1000 |
overrides.weights.bulk | integer | sí | 1–1000 |
overrides.weights.background | integer | sí | 1–1000 |
overrides.sessionMinBytes | integer | no | 0–9007199254740991 |
overrides.idleSeconds | integer | no | 1–3600 |
overrides.agingMinutes | integer | no | 0–10080 |
overrides.preempt | boolean | no | — |
overrides.rangesPerSession | integer | no | 1–64 |
defaults | object | sí | — |
defaults.strategy | string | sí | uno de ordered, smallest-first, shared |
defaults.sessions | integer | sí | 1–1024 |
defaults.reserve | integer | sí | 0–1023 |
defaults.perPrincipal | integer | sí | 1–1024 |
defaults.weights | object | sí | — |
defaults.weights.interactive | integer | sí | 1–1000 |
defaults.weights.release | integer | sí | 1–1000 |
defaults.weights.bulk | integer | sí | 1–1000 |
defaults.weights.background | integer | sí | 1–1000 |
defaults.sessionMinBytes | integer | sí | 0–9007199254740991 |
defaults.idleSeconds | integer | sí | 1–3600 |
defaults.agingMinutes | integer | sí | 0–10080 |
defaults.preempt | boolean | sí | — |
defaults.rangesPerSession | integer | sí | 1–64 |
effective | object | sí | — |
effective.strategy | string | sí | uno de ordered, smallest-first, shared |
effective.sessions | integer | sí | 1–1024 |
effective.reserve | integer | sí | 0–1023 |
effective.perPrincipal | integer | sí | 1–1024 |
effective.weights | object | sí | — |
effective.weights.interactive | integer | sí | 1–1000 |
effective.weights.release | integer | sí | 1–1000 |
effective.weights.bulk | integer | sí | 1–1000 |
effective.weights.background | integer | sí | 1–1000 |
effective.sessionMinBytes | integer | sí | 0–9007199254740991 |
effective.idleSeconds | integer | sí | 1–3600 |
effective.agingMinutes | integer | sí | 0–10080 |
effective.preempt | boolean | sí | — |
effective.rangesPerSession | integer | sí | 1–64 |
admission | string | sí | uno de sessions, per-request |
updatedAt | string (date-time) | sí | puede ser null |
updatedBy | string | sí | puede ser null |
actor | string | sí | puede ser null |
problem | string | sí | puede ser null |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/system/downloads/settings" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Cambiar los ajustes de la cola de descargas
PUT /api/v1/system/downloads/settings
Acceso: Administrador · Reintento: Repetir solo con la revisión esperada (compare-and-swap)
Guarda overrides sobre el entorno del servidor y los aplica sin reiniciar: las nuevas decisiones los siguen de inmediato y las descargas activas conservan su lugar. Los valores enviados reemplazan todos los cambios anteriores; {} vuelve al entorno. Los ajustes que no pueden funcionar aquí se rechazan con 400 indicando el campo; una expectedRevision desactualizada recibe 409. Las pasarelas de lectura conservan su entorno.
Cuerpo de la solicitud (application/json)
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
expectedRevision | integer | sí | 0–9007199254740991 |
overrides | object | sí | — |
overrides.strategy | string | no | uno de ordered, smallest-first, shared |
overrides.sessions | integer | no | 1–1024 |
overrides.reserve | integer | no | 0–1023 |
overrides.perPrincipal | integer | no | 1–1024 |
overrides.weights | object | no | — |
overrides.weights.interactive | integer | sí | 1–1000 |
overrides.weights.release | integer | sí | 1–1000 |
overrides.weights.bulk | integer | sí | 1–1000 |
overrides.weights.background | integer | sí | 1–1000 |
overrides.sessionMinBytes | integer | no | 0–9007199254740991 |
overrides.idleSeconds | integer | no | 1–3600 |
overrides.agingMinutes | integer | no | 0–10080 |
overrides.preempt | boolean | no | — |
overrides.rangesPerSession | integer | no | 1–64 |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
revision | integer | sí | 0–9007199254740991 |
overrides | object | sí | — |
overrides.strategy | string | no | uno de ordered, smallest-first, shared |
overrides.sessions | integer | no | 1–1024 |
overrides.reserve | integer | no | 0–1023 |
overrides.perPrincipal | integer | no | 1–1024 |
overrides.weights | object | no | — |
overrides.weights.interactive | integer | sí | 1–1000 |
overrides.weights.release | integer | sí | 1–1000 |
overrides.weights.bulk | integer | sí | 1–1000 |
overrides.weights.background | integer | sí | 1–1000 |
overrides.sessionMinBytes | integer | no | 0–9007199254740991 |
overrides.idleSeconds | integer | no | 1–3600 |
overrides.agingMinutes | integer | no | 0–10080 |
overrides.preempt | boolean | no | — |
overrides.rangesPerSession | integer | no | 1–64 |
defaults | object | sí | — |
defaults.strategy | string | sí | uno de ordered, smallest-first, shared |
defaults.sessions | integer | sí | 1–1024 |
defaults.reserve | integer | sí | 0–1023 |
defaults.perPrincipal | integer | sí | 1–1024 |
defaults.weights | object | sí | — |
defaults.weights.interactive | integer | sí | 1–1000 |
defaults.weights.release | integer | sí | 1–1000 |
defaults.weights.bulk | integer | sí | 1–1000 |
defaults.weights.background | integer | sí | 1–1000 |
defaults.sessionMinBytes | integer | sí | 0–9007199254740991 |
defaults.idleSeconds | integer | sí | 1–3600 |
defaults.agingMinutes | integer | sí | 0–10080 |
defaults.preempt | boolean | sí | — |
defaults.rangesPerSession | integer | sí | 1–64 |
effective | object | sí | — |
effective.strategy | string | sí | uno de ordered, smallest-first, shared |
effective.sessions | integer | sí | 1–1024 |
effective.reserve | integer | sí | 0–1023 |
effective.perPrincipal | integer | sí | 1–1024 |
effective.weights | object | sí | — |
effective.weights.interactive | integer | sí | 1–1000 |
effective.weights.release | integer | sí | 1–1000 |
effective.weights.bulk | integer | sí | 1–1000 |
effective.weights.background | integer | sí | 1–1000 |
effective.sessionMinBytes | integer | sí | 0–9007199254740991 |
effective.idleSeconds | integer | sí | 1–3600 |
effective.agingMinutes | integer | sí | 0–10080 |
effective.preempt | boolean | sí | — |
effective.rangesPerSession | integer | sí | 1–64 |
admission | string | sí | uno de sessions, per-request |
updatedAt | string (date-time) | sí | puede ser null |
updatedBy | string | sí | puede ser null |
actor | string | sí | puede ser null |
problem | string | sí | puede ser null |
Respuestas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Ejemplo
curl -X PUT "$ARKVORY_URL/api/v1/system/downloads/settings" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"overrides":{}}'Leer los cambios del sitio
GET HEAD /api/v1/system/changes
Acceso: Administrador · Reintento: Se puede repetir (lectura)
Devuelve si el agente del sitio responde (agent), la solicitud pendiente y las 20 más recientes con su estado: pending, applying, done o failed con el motivo. Las claves de origen nunca aparecen aquí.
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
agent | boolean | sí | — |
updating | boolean | sí | — |
blocked | string | sí | uno de expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; puede ser null |
pending | object | sí | puede ser null |
pending.id | string (uuid) | sí | — |
pending.kind | string | sí | uno de mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy |
pending.actor | string | sí | hasta 200 caracteres |
pending.requestedAt | string (date-time) | sí | — |
recent | array de object | sí | hasta 20 elementos |
recent[].id | string (uuid) | sí | — |
recent[].digest | string | sí | coincide con ^[0-9a-f]{64}$ |
recent[].kind | string | sí | uno de mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy |
recent[].state | string | sí | uno de pending, applying, done, failed |
recent[].error | string | sí | uno de expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; puede ser null |
recent[].actor | string | sí | hasta 200 caracteres |
recent[].requestedAt | string (date-time) | sí | — |
recent[].finishedAt | string (date-time) | sí | puede ser null |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/system/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Poner en cola un cambio del sitio
POST /api/v1/system/changes
Acceso: Administrador · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto
Pone en cola un cambio para el agente del sitio, que lo aplica en menos de un minuto con las comprobaciones y la reversión de arkvory configure y cluster-*: conectar un espejo o una importación, sustituir su clave de origen, desconectar espejos, cambiar el nodo HA activo (el nombre del nodo se escribe dos veces) o decidir escrituras con una copia. id lo elige el cliente; repetirlo no vuelve a poner el cambio en cola. key es la clave de origen solo de mirror-attach y mirror-key: llega al agente en su propio archivo 0600 y nunca se devuelve. 202 significa en cola, no aplicado.
Cuerpo de la solicitud (application/json)
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
id | string (uuid) | sí | — |
change | object | sí | — |
change.kind | string | sí | uno de mirror-attach |
change.repository | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.upstream | string | sí | hasta 255 caracteres |
change.sourceRepository | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.stages | array de string | no | 1–16 elementos; cada elemento: coincide con ^[a-z0-9][a-z0-9_.-]{0,31}$; puede ser null |
change.repositories | array de string | sí | 1–64 elementos; cada elemento: coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.node | string | sí | coincide con ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$ |
change.confirm | string | sí | coincide con ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$ |
change.until | string (date-time) | sí | puede ser null |
change.reason | string | sí | 1–200 caracteres |
key | string | no | 16–4000 caracteres |
Respuesta 202
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
id | string (uuid) | sí | — |
Respuestas: 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Ejemplo
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>"}}'Seguir el flujo de cambios de un repositorio
GET HEAD /api/v1/repositories/{repository}/changes
Acceso: Permiso de repositorio: artifact.list; claves de archivo: read · Reintento: Se puede repetir (lectura)
Devuelve, en orden de confirmación, hasta limit cambios (1–100, 100 por defecto) posteriores a la secuencia after (0 por defecto): acción, artefacto y, para rutas de archivo y etapas, la ruta o la etapa en detail; los actores se omiten, por lo que basta con el permiso de listado. head es la secuencia más reciente del repositorio y next el cursor de la página siguiente, o null cuando la página llegó hasta head. Un espejo guarda la última secuencia que aplicó y sondea desde ahí.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | consulta | string | no | un número entero en dígitos decimales, enviado como cadena; Sequence cursor, default 0 |
limit | consulta | integer | no | 1–100 |
Respuesta 200
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
items | array de object | sí | — |
items[].sequence | string | sí | un número entero en dígitos decimales, enviado como cadena |
items[].action | string | sí | — |
items[].artifactId | string (uuid) | sí | — |
items[].detail | string | sí | puede ser null |
head | string | sí | un número entero en dígitos decimales, enviado como cadena |
next | string | sí | un número entero en dígitos decimales, enviado como cadena; puede ser null |
Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Ejemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Crear un enlace de descarga
POST /api/v1/repositories/{repository}/artifacts/{id}/links
Acceso: Permiso de repositorio: content.read; claves de archivo: read · Reintento: No repetir automáticamente
Devuelve un token secreto, una url relativa al origen de la API y expiresAt para usar downloadArtifact con este único artefacto sin clave; ttlSeconds fija la duración (de 60 segundos a un día, una hora por defecto). El token se muestra solo en esta respuesta y no se puede revocar: deja de funcionar cuando caduca o se elimina el artefacto, y las descargas con él cuentan para los límites de transferencia de su creador. Un solicitante puede tener 1000 enlaces vigentes (507 token_limit), y un enlace de descarga no puede crear más enlaces.
Parámetros
| Nombre | Ubicación | Tipo | Obligatorio | Reglas |
|---|---|---|---|---|
repository | ruta | string | sí | coincide con ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | ruta | string (uuid) | sí | — |
Cuerpo de la solicitud (application/json)
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
ttlSeconds | integer | no | 60–86400; predeterminado: 3600 |
Respuesta 201
| Campo | Tipo | Obligatorio | Reglas |
|---|---|---|---|
token | string | sí | coincide con ^dtl_[A-Za-z0-9_-]{43}$ |
url | string | sí | — |
expiresAt | string (date-time) | sí | — |
Respuestas: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Ejemplo
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/links" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'