Archivos por ruta

Archivos direccionados por una ruta del repositorio: revisiones, historial, restauración y archivos sin procesar en una sola solicitud.

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

Listar rutas de archivo por prefijo

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

Acceso: Permiso de repositorio: asset.read; claves de archivo: read · Reintento: Se puede repetir (lectura)

Devuelve todas las rutas de archivo que empiezan por prefix (literal, no un patrón; vacío para todas), ordenadas por ruta, cada una con su revisión actual y el ID del artefacto. No hay paginación: más de 1000 coincidencias producen un 400 que pide un prefijo más específico, así que prefiera listAssetPage para árboles grandes.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
`repository`	ruta	string	sí	coincide con `^[a-z0-9][a-z0-9_-]{0,63}$`
`prefix`	consulta	string	no	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
`items`	array de object	no	—
`items[].path`	string	sí	—
`items[].revision`	integer	sí	1–2147483647
`items[].artifactId`	string (uuid)	sí	—

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

bash

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

Listar rutas de archivo página por página

GET HEAD /api/v1/repositories/{repository}/assets/page

Acceso: Permiso de repositorio: asset.read; claves de archivo: read · Reintento: Se puede repetir (lectura)

Devuelve las rutas de archivo actuales que empiezan por prefix (literal; vacío para todas) en orden de bytes UTF-8, cada una con su revisión actual y el ID del artefacto. Las páginas contienen limit elementos (1–100, 50 por defecto); continúe pasando el next opaco como after. Las páginas no son una instantánea: las rutas modificadas entre solicitudes pueden aparecer con su revisión más reciente o quedar fuera hasta la siguiente pasada.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
`repository`	ruta	string	sí	coincide con `^[a-z0-9][a-z0-9_-]{0,63}$`
`prefix`	consulta	string	no	hasta 1024 caracteres; predeterminado: ``; Case-sensitive literal prefix; % and _ are ordinary characters.
`after`	consulta	string	no	coincide con `^[A-Za-z0-9_-]+$`; 1–8192 caracteres
`limit`	consulta	integer	no	1–100; predeterminado: `50`

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
`items`	array de object	sí	hasta 100 elementos
`items[].path`	string	sí	—
`items[].revision`	integer	sí	1–2147483647
`items[].artifactId`	string (uuid)	sí	—
`next`	string	sí	coincide con `^[A-Za-z0-9_-]+$`; 1–8192 caracteres; puede ser null; Cursor opaco ligado al repositorio y al prefijo; null al final. Nunca concede acceso.

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

bash

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

Obtener la revisión actual de una ruta de archivo

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

Acceso: Permiso de repositorio: asset.read; claves de archivo: read · Reintento: Se puede repetir (lectura)

Devuelve la revision actual de path y el ID del artefacto al que apunta; una ruta desconocida es un 404. Una ruta tiene de 1 a 1024 caracteres en segmentos separados por /, sin segmentos vacíos, . ni .., y sin \, : ni caracteres de control. Descargue los bytes con downloadAssetContent o pase la revisión a setAsset como expectedRevision.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
`repository`	ruta	string	sí	coincide con `^[a-z0-9][a-z0-9_-]{0,63}$`
`path`	consulta	string	sí	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
`path`	string	sí	—
`revision`	integer	sí	1–2147483647
`artifactId`	string (uuid)	sí	—

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Apuntar una ruta de archivo a un artefacto

PUT /api/v1/repositories/{repository}/asset

Acceso: Permiso de repositorio: asset.write, artifact.read; claves de archivo: read, write · Reintento: Repetir solo con la revisión esperada (compare-and-swap)

Hace que path nombre un artefacto publicado del mismo repositorio como su nueva revisión; expectedRevision es 0 para crear la ruta y la revisión actual para reemplazarla; de lo contrario, 409 revision_mismatch. Las revisiones anteriores permanecen en el historial e impiden que sus artefactos se eliminen. Para almacenar bytes y nombrarlos en una sola solicitud, use putRawFile.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
`repository`	ruta	string	sí	coincide con `^[a-z0-9][a-z0-9_-]{0,63}$`

Cuerpo de la solicitud (application/json)

Campo	Tipo	Obligatorio	Reglas
`path`	string	sí	—
`artifactId`	string (uuid)	sí	—
`expectedRevision`	integer	sí	0–2147483646

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
`path`	string	sí	—
`revision`	integer	sí	1–2147483647
`artifactId`	string (uuid)	sí	—

Respuestas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Ejemplo

bash

curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"<path>","artifactId":"00000000-0000-4000-8000-000000000000","expectedRevision":0}'

Listar las revisiones de una ruta de archivo

GET HEAD /api/v1/repositories/{repository}/asset/history

Acceso: Permiso de repositorio: asset.read; claves de archivo: read · Reintento: Se puede repetir (lectura)

Devuelve las revisiones de path, de la más reciente a la más antigua, 50 por página, cada una con su artefacto, el actor, la hora y, en una restauración, la sourceRevision que copió (el actor y la hora son null en las revisiones registradas por las primeras versiones del servidor). Continúe pasando next como before. Una ruta desconocida es un 404.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
`repository`	ruta	string	sí	coincide con `^[a-z0-9][a-z0-9_-]{0,63}$`
`path`	consulta	string	sí	—
`before`	consulta	integer	no	1–2147483647; Only revisions strictly smaller than this value

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
`items`	array de object	sí	hasta 50 elementos
`items[].path`	string	sí	—
`items[].revision`	integer	sí	1–2147483647
`items[].artifactId`	string (uuid)	sí	—
`items[].actor`	string	sí	puede ser null; Null para el historial registrado antes de la migración 4
`items[].createdAt`	string (date-time)	sí	puede ser null; Null para el historial registrado antes de la migración 4
`items[].sourceRevision`	integer	sí	1–2147483647; puede ser null; Revisión restaurada; null en un reemplazo ordinario
`next`	integer	sí	1–2147483647; puede ser null; Cursor exclusivo para before; null al final

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/history?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Obtener una revisión de una ruta de archivo

GET HEAD /api/v1/repositories/{repository}/asset/revision

Acceso: Permiso de repositorio: asset.read; claves de archivo: read · Reintento: Se puede repetir (lectura)

Devuelve la revisión revision de path con el ID de su artefacto, el actor, la hora y el origen de la restauración. Las revisiones nunca cambian, por lo que el ID del artefacto se puede guardar en caché; descárguelo con downloadArtifact. Una ruta o una revisión inexistente es un 404.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
`repository`	ruta	string	sí	coincide con `^[a-z0-9][a-z0-9_-]{0,63}$`
`path`	consulta	string	sí	—
`revision`	consulta	integer	sí	1–2147483647

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
`path`	string	sí	—
`revision`	integer	sí	1–2147483647
`artifactId`	string (uuid)	sí	—
`actor`	string	sí	puede ser null; Null para el historial registrado antes de la migración 4
`createdAt`	string (date-time)	sí	puede ser null; Null para el historial registrado antes de la migración 4
`sourceRevision`	integer	sí	1–2147483647; puede ser null; Revisión restaurada; null en un reemplazo ordinario

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/revision?path=$PATH&revision=$REVISION" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Restaurar una revisión anterior de una ruta de archivo

POST /api/v1/repositories/{repository}/asset/restore

Acceso: Permiso de repositorio: asset.restore, asset.read, artifact.read; claves de archivo: read, write · Reintento: Repetir solo con la revisión esperada (compare-and-swap)

Añade una nueva revisión de path que apunta al artefacto de sourceRevision; no se copia nada ni se elimina ninguna revisión. expectedRevision debe ser la revisión actual (al menos 1); de lo contrario, 409 revision_mismatch, de modo que repetir una restauración que ya tuvo éxito produce un 409 y no una segunda restauración. La nueva revisión registra sourceRevision y el cambio se audita en la misma transacción.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
`repository`	ruta	string	sí	coincide con `^[a-z0-9][a-z0-9_-]{0,63}$`

Cuerpo de la solicitud (application/json)

Campo	Tipo	Obligatorio	Reglas
`path`	string	sí	—
`sourceRevision`	integer	sí	1–2147483647
`expectedRevision`	integer	sí	1–2147483646

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
`path`	string	sí	—
`revision`	integer	sí	1–2147483647
`artifactId`	string (uuid)	sí	—

Respuestas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Ejemplo

bash

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/restore" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"<path>","sourceRevision":1,"expectedRevision":1}'

Descargar un archivo por ruta

GET HEAD /api/v1/repositories/{repository}/asset/content

Acceso: Permiso de repositorio: content.read; claves de archivo: read · Reintento: Se puede repetir (lectura)

Resuelve path a su revisión actual y transmite ese artefacto como downloadArtifact, con Range, If-Range, If-None-Match y HEAD. La ruta se resuelve en cada solicitud, así que reanude con If-Range igual al ETag devuelto: si la ruta ya apunta a otra revisión, la respuesta es el archivo nuevo completo en lugar de uno mezclado. downloadRawFile hace lo mismo con la ruta en la URL.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
`repository`	ruta	string	sí	coincide con `^[a-z0-9][a-z0-9_-]{0,63}$`
`Range`	encabezado	string	no	Single bytes range; multi-range is unsupported. HEAD ignores Range.
`If-Range`	encabezado	string	no	Exact strong ETag; a mismatch causes a full response.
`If-None-Match`	encabezado	string	no	Matching ETag returns 304, including HEAD.
`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.
`path`	consulta	string	sí	—

Respuestas: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507

Ejemplo

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/content?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -o file

Subir un archivo a una ruta en una sola solicitud

PUT /api/v1/repositories/{repository}/raw/{assetPath}

Acceso: Permiso de repositorio: upload.create, upload.write, upload.complete, asset.read, asset.write, artifact.read; claves de archivo: write · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto

Almacena el cuerpo de la solicitud, de cualquier tipo de medio, como la nueva revisión de la ruta de la URL, pensado para scripts y CI (curl -T); la respuesta es 201 con la ruta, la revisión y el artefacto. Con X-Checksum-Sha256 y Content-Length, los bytes se transmiten directamente al almacenamiento y se verifican; sin ellos pasan primero por un área temporal y se calcula su hash (422 si el cuerpo no coincide con una suma de comprobación indicada). Los mismos bytes que la revisión actual no añaden nada y responden 200 con created: false; If-None-Match: * solo crea (409 already_exists), y un escritor simultáneo de la misma ruta recibe 409 revision_mismatch. Para archivos muy grandes, prefiera las sesiones de subida reanudables.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
`repository`	ruta	string	sí	coincide con `^[a-z0-9][a-z0-9_-]{0,63}$`
`assetPath`	ruta	string	sí	1–1024 caracteres; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon.
`X-Checksum-Sha256`	encabezado	string	no	coincide con `^[a-fA-F0-9]{64}$`; SHA-256 of the body (64 hex digits); a mismatch stores nothing (422).
`If-None-Match`	encabezado	string	no	uno de ``; "": store only when the path does not exist yet (409 already_exists).

Cuerpo de la solicitud (application/octet-stream)

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
`path`	string	sí	—
`revision`	integer	sí	como mínimo 1
`created`	boolean	sí	—
`artifact`	object	sí	—
`artifact.id`	string (uuid)	sí	—
`artifact.size`	string	sí	un número entero en dígitos decimales, enviado como cadena
`artifact.sha256`	string	sí	SHA-256: 64 dígitos hexadecimales en minúsculas

Respuestas: 200, 201, 400, 401, 403, 404, 405, 409, 422, 503, 507

Ejemplo

bash

curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @file

Descargar un archivo por la ruta de la URL

GET HEAD /api/v1/repositories/{repository}/raw/{assetPath}

Acceso: Permiso de repositorio: content.read; claves de archivo: read · Reintento: Se puede repetir (lectura)

Transmite la revisión actual de la ruta de la URL como downloadArtifact, con Range, If-Range, If-None-Match, HEAD y X-Arkvory-Artifact-Id, que nombra el artefacto. La ruta se resuelve en cada solicitud, así que reanude con If-Range igual al ETag devuelto, o descargue el artefacto por ID.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
`repository`	ruta	string	sí	coincide con `^[a-z0-9][a-z0-9_-]{0,63}$`
`assetPath`	ruta	string	sí	1–1024 caracteres; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon.
`Range`	encabezado	string	no	Single bytes range; multi-range is unsupported. HEAD ignores Range.
`If-Range`	encabezado	string	no	Exact strong ETag; a mismatch causes a full response.
`If-None-Match`	encabezado	string	no	Matching ETag returns 304, including HEAD.
`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.

Respuestas: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507

Ejemplo

bash

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

Archivos por ruta ​

Operaciones ​

Listar rutas de archivo por prefijo ​

Listar rutas de archivo página por página ​

Obtener la revisión actual de una ruta de archivo ​

Apuntar una ruta de archivo a un artefacto ​

Listar las revisiones de una ruta de archivo ​

Obtener una revisión de una ruta de archivo ​

Restaurar una revisión anterior de una ruta de archivo ​

Descargar un archivo por ruta ​

Subir un archivo a una ruta en una sola solicitud ​

Descargar un archivo por la ruta de la URL ​

Archivos por ruta

Operaciones

Listar rutas de archivo por prefijo

Listar rutas de archivo página por página

Obtener la revisión actual de una ruta de archivo

Apuntar una ruta de archivo a un artefacto

Listar las revisiones de una ruta de archivo

Obtener una revisión de una ruta de archivo

Restaurar una revisión anterior de una ruta de archivo

Descargar un archivo por ruta

Subir un archivo a una ruta en una sola solicitud

Descargar un archivo por la ruta de la URL