Políticas de armazenamento e retenção

Cotas, uso, políticas de retenção, a visualização e a execução delas, limpeza e exclusão de artefatos.

Operações deste grupo com a regra de acesso, a regra de repetição, os parâmetros e as respostas. Toda solicitação leva uma chave: Authorization: Bearer <chave> (consulte “Autenticação”).

Operações

Verificar se um artefato pode ser excluído

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

Acesso: Permissão no repositório: artifact.delete · Repetição: Pode ser repetida com segurança (leitura)

Retorna o nome, o tamanho, a data de publicação e o annotationRevision atual do artefato, além dos blockers que impediriam sua exclusão: reference (uma referência externa ou o uso por uma imagem de contêiner, Git LFS ou npm), asset_history (uma revisão atual ou anterior de um caminho de arquivo), attachment_history ou promotion_stage. Nada é alterado; passe a revisão para deleteArtifact como expectedAnnotationRevision.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
repository	caminho	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$
id	caminho	string (uuid)	sim	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
id	string (uuid)	sim	—
name	string	sim	1–240 caracteres
size	string	sim	um número inteiro em dígitos decimais, enviado como string
publishedAt	string (date-time)	sim	—
annotationRevision	integer	sim	0–2147483647
blockers	array de string	sim	até 4 itens; sem itens repetidos; cada item: um destes: reference, asset_history, attachment_history, protected_label, promotion_stage

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

Exemplo

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

Pré-visualizar os candidatos da retenção

POST /api/v1/repositories/{repository}/retention/preview

Acesso: Permissão no repositório: artifact.delete · Repetição: Pode ser repetida com segurança (leitura)

Lista os artefatos publicados antes de criteria.publishedBefore (uma hora UTC passada, com milissegundos), ordenados por ID, cada um com sua revisão de anotações e seus bloqueadores (blockers); protected_label indica um dos criteria.protectedLabels (uma lista explícita de até 32). As páginas contêm limit itens (1–100, padrão 50); continue com after definido como next. Nada é reservado: escolha os itens a excluir e passe-os com suas revisões para applyRetention, que os verifica novamente.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
repository	caminho	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
criteria	object	sim	—
criteria.publishedBefore	string (date-time)	sim	corresponde a ^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$
criteria.protectedLabels	array de string	sim	até 32 itens; sem itens repetidos; cada item: 1–64 caracteres
limit	integer	não	1–100
after	string (uuid)	não	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
items	array de object	sim	até 100 itens
items[].id	string (uuid)	sim	—
items[].name	string	sim	1–240 caracteres
items[].size	string	sim	um número inteiro em dígitos decimais, enviado como string
items[].publishedAt	string (date-time)	sim	—
items[].annotationRevision	integer	sim	0–2147483647
items[].blockers	array de string	sim	até 4 itens; sem itens repetidos; cada item: um destes: reference, asset_history, attachment_history, protected_label, promotion_stage
next	string (uuid)	sim	pode ser null

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

Exemplo

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/retention/preview" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"criteria":{"publishedBefore":"2026-01-01T00:00:00.000Z","protectedLabels":[]}}'

Excluir os candidatos de retenção selecionados

POST /api/v1/repositories/{repository}/retention/apply

Acesso: Permissão no repositório: artifact.delete · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito

Verifica novamente de 1 a 100 artefatos escolhidos em previewRetention (items com id e expectedAnnotationRevision) segundo os mesmos criteria e exclui logicamente os elegíveis em uma única transação. Cada item recebe um outcome: deleted, already_deleted, changed (as anotações mudaram), not_eligible (publicado tarde demais), protected com seus bloqueadores ou not_found. Os bytes permanecem reservados até que a limpeza online do repositório os recupere.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
repository	caminho	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
criteria	object	sim	—
criteria.publishedBefore	string (date-time)	sim	corresponde a ^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$
criteria.protectedLabels	array de string	sim	até 32 itens; sem itens repetidos; cada item: 1–64 caracteres
items	array de object	sim	1–100 itens
items[].id	string (uuid)	sim	—
items[].expectedAnnotationRevision	integer	sim	0–2147483647

Resposta 200

Campo	Tipo	Obrigatório	Regras
items	array de object	sim	1–100 itens
items[].id	string (uuid)	sim	—
items[].outcome	string	sim	um destes: deleted, already_deleted, protected, changed, not_eligible, not_found
items[].blockers	array de string	sim	até 4 itens; sem itens repetidos; cada item: um destes: reference, asset_history, attachment_history, protected_label, promotion_stage

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

Exemplo

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/retention/apply" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"criteria":{"publishedBefore":"2026-01-01T00:00:00.000Z","protectedLabels":[]},"items":[{"id":"00000000-0000-4000-8000-000000000000","expectedAnnotationRevision":0}]}'

Obter a política de armazenamento

GET HEAD /api/v1/repositories/{repository}/storage/policy

Acesso: Permissão no repositório: storage.read · Repetição: Pode ser repetida com segurança (leitura)

Retorna as configurações de limpeza automática e de cota do repositório com sua revision, a próxima e a última execução agendada, quantos builds a última execução excluiu e seu erro. Por padrão, a política está desativada e não há cota de repositório (a capacidade global do servidor continua valendo).

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
repository	caminho	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$

Resposta 200

Campo	Tipo	Obrigatório	Regras
revision	integer	sim	0–2147483647
policy	object	sim	—
policy.enabled	boolean	sim	—
policy.grouping	string	sim	um destes: package-channel, package, repository
policy.keepLast	integer	sim	1–100000
policy.channels	array de object	sim	até 32 itens
policy.channels[].label	string	sim	1–64 caracteres
policy.channels[].keepLast	integer	sim	1–100000
policy.protectedLabels	array de string	sim	até 32 itens; sem itens repetidos; cada item: 1–64 caracteres
policy.minAgeHours	integer	sim	0–87600
policy.intervalMinutes	integer	sim	1–10080
policy.quotaBytes	string	sim	um número inteiro em dígitos decimais, enviado como string; pode ser null
policy.warningPercent	integer	sim	1–98
policy.criticalPercent	integer	sim	2–99
nextRunAt	string (date-time)	sim	pode ser null
lastRunAt	string (date-time)	sim	pode ser null
lastDeleted	integer	sim	0–100
lastError	string	sim	até 64 caracteres; pode ser null

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

Exemplo

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

Substituir a política de armazenamento

PUT /api/v1/repositories/{repository}/storage/policy

Acesso: Permissão no repositório: storage.manage · Repetição: Repetir somente com a revisão esperada (compare-and-swap)

Substitui a política inteira: manter os últimos keepLast builds UPack registrados por pacote, por rótulo de canal (channels) ou por repositório (grouping), nunca excluir protectedLabels nem builds mais novos que minAgeHours, executar a cada intervalMinutes e limitar o repositório com quotaBytes (uma string decimal, null para nenhum limite) e seus limiares de alerta. expectedRevision deve ser a revisão atual; caso contrário, 409 revision_mismatch. Ativar também exige artifact.delete e vincula o agendamento à chave gerenciada que faz a chamada: quando essa chave é revogada, expira ou perde essas permissões, a exclusão agendada para até que a política seja salva com outra chave. Arquivos comuns contam na cota, mas nunca são excluídos por ela.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
repository	caminho	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
expectedRevision	integer	sim	0–2147483647
policy	object	sim	—
policy.enabled	boolean	sim	—
policy.grouping	string	sim	um destes: package-channel, package, repository
policy.keepLast	integer	sim	1–100000
policy.channels	array de object	sim	até 32 itens
policy.channels[].label	string	sim	1–64 caracteres
policy.channels[].keepLast	integer	sim	1–100000
policy.protectedLabels	array de string	sim	até 32 itens; sem itens repetidos; cada item: 1–64 caracteres
policy.minAgeHours	integer	sim	0–87600
policy.intervalMinutes	integer	sim	1–10080
policy.quotaBytes	string	sim	um número inteiro em dígitos decimais, enviado como string; pode ser null
policy.warningPercent	integer	sim	1–98
policy.criticalPercent	integer	sim	2–99

Resposta 200

Campo	Tipo	Obrigatório	Regras
revision	integer	sim	0–2147483647
policy	object	sim	—
policy.enabled	boolean	sim	—
policy.grouping	string	sim	um destes: package-channel, package, repository
policy.keepLast	integer	sim	1–100000
policy.channels	array de object	sim	até 32 itens
policy.channels[].label	string	sim	1–64 caracteres
policy.channels[].keepLast	integer	sim	1–100000
policy.protectedLabels	array de string	sim	até 32 itens; sem itens repetidos; cada item: 1–64 caracteres
policy.minAgeHours	integer	sim	0–87600
policy.intervalMinutes	integer	sim	1–10080
policy.quotaBytes	string	sim	um número inteiro em dígitos decimais, enviado como string; pode ser null
policy.warningPercent	integer	sim	1–98
policy.criticalPercent	integer	sim	2–99
nextRunAt	string (date-time)	sim	pode ser null
lastRunAt	string (date-time)	sim	pode ser null
lastDeleted	integer	sim	0–100
lastError	string	sim	até 64 caracteres; pode ser null

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

Exemplo

curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/storage/policy" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0,"policy":{"enabled":false,"grouping":"package-channel","keepLast":1,"channels":[],"protectedLabels":[],"minAgeHours":0,"intervalMinutes":1,"quotaBytes":"1024","warningPercent":1,"criticalPercent":2}}'

Obter o uso de armazenamento de um repositório

GET HEAD /api/v1/repositories/{repository}/storage/usage

Acesso: Permissão no repositório: storage.read · Repetição: Pode ser repetida com segurança (leitura)

Retorna os bytes reservados pelo repositório como strings decimais: publicados, uploads pendentes e retirados (excluídos ou cancelados, ainda não recuperados), sua soma reservedBytes, a cota e um state (unlimited, normal, warning, critical, exceeded). Essa é a reserva lógica contada na cota, não o espaço usado em disco.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
repository	caminho	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$

Resposta 200

Campo	Tipo	Obrigatório	Regras
publishedBytes	string	sim	um número inteiro em dígitos decimais, enviado como string
pendingBytes	string	sim	um número inteiro em dígitos decimais, enviado como string
retiredBytes	string	sim	um número inteiro em dígitos decimais, enviado como string
reservedBytes	string	sim	um número inteiro em dígitos decimais, enviado como string
quotaBytes	string	sim	um número inteiro em dígitos decimais, enviado como string; pode ser null
state	string	sim	um destes: unlimited, normal, warning, critical, exceeded

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

Exemplo

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

Pré-visualizar o que a política de armazenamento excluiria

GET HEAD /api/v1/repositories/{repository}/storage/preview

Acesso: Permissão no repositório: artifact.delete · Repetição: Pode ser repetida com segurança (leitura)

Retorna até 100 builds registrados que a política salva excluiria agora (mesmo estando desativada), com a revision da política e hasMore; builds mantidos por referências, caminhos de arquivo, anexos, rótulos protegidos ou idade ficam de fora. Nada é reservado: uma execução classifica os builds novamente.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
repository	caminho	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$

Resposta 200

Campo	Tipo	Obrigatório	Regras
revision	integer	sim	0–2147483647
items	array de object	sim	até 100 itens
items[].id	string (uuid)	sim	—
items[].name	string	sim	até 240 caracteres
items[].size	string	sim	um número inteiro em dígitos decimais, enviado como string
items[].publishedAt	string (date-time)	sim	—
items[].annotationRevision	integer	sim	0–2147483647
items[].blockers	array de string	sim	até 0 itens
hasMore	boolean	sim	—

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

Exemplo

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

Executar a política de armazenamento agora

POST /api/v1/repositories/{repository}/storage/run

Acesso: Permissão no repositório: storage.manage, artifact.delete · Repetição: Não repetir automaticamente

Executa imediatamente um lote da política ativada em vez de esperar pelo agendamento: classifica os builds novamente, verifica permissões e dependências e exclui logicamente até 100, retornando um resultado para cada um. expectedRevision deve ser a revisão atual da política e a política deve estar ativada; caso contrário, 409. Os bytes são recuperados depois pela limpeza online do repositório, que tem sua própria política (setCleanup).

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
repository	caminho	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
expectedRevision	integer	sim	0–2147483647

Resposta 200

Campo	Tipo	Obrigatório	Regras
items	array de object	sim	até 100 itens
items[].id	string (uuid)	sim	—
items[].outcome	string	sim	um destes: deleted, already_deleted, protected, changed, not_eligible, not_found
items[].blockers	array de string	sim	até 4 itens; cada item: um destes: reference, asset_history, attachment_history, protected_label, promotion_stage

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

Exemplo

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/storage/run" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0}'

Listar os eventos de armazenamento de um repositório

GET HEAD /api/v1/repositories/{repository}/storage/events

Acesso: Permissão no repositório: diagnostics.read · Repetição: Pode ser repetida com segurança (leitura)

Retorna até 100 eventos de diagnóstico de políticas de armazenamento, cotas, retenção e limpeza após a sequência after (padrão 0), do mais antigo para o mais recente, cada um com nível, código e alguns detalhes; level (info, warning, error) os filtra; continue com after definido como next. Somente os 1000 eventos mais recentes por repositório e 20 000 no total são mantidos; portanto, exporte-os para uma retenção mais longa.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
repository	caminho	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$
after	consulta	string	não	um número inteiro em dígitos decimais, enviado como string
level	consulta	string	não	um destes: info, warning, error

Resposta 200

Campo	Tipo	Obrigatório	Regras
items	array de object	sim	até 100 itens
items[].sequence	string	sim	um número inteiro em dígitos decimais, enviado como string
items[].occurredAt	string (date-time)	sim	—
items[].level	string	sim	um destes: info, warning, error
items[].code	string	sim	até 96 caracteres
items[].details	mapa de string | integer	sim	até 16 entradas
next	string	sim	um número inteiro em dígitos decimais, enviado como string; pode ser null

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

Exemplo

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

Obter as configurações da limpeza online

GET HEAD /api/v1/repositories/{repository}/storage/cleanup

Acesso: Permissão no repositório: storage.read · Repetição: Pode ser repetida com segurança (leitura)

Retorna a política de limpeza online do repositório com sua revision (enabled, graceHours, batchSize, intervalSeconds, delayMilliseconds), a última e a próxima execução, e quantos objetos o último lote recuperou, adiou ou não conseguiu processar, com os bytes liberados. A limpeza é o que remove fisicamente uploads cancelados e artefatos excluídos; ela vem desativada por padrão.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
repository	caminho	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$

Resposta 200

Campo	Tipo	Obrigatório	Regras
revision	integer	sim	0–2147483647
policy	object	sim	—
policy.enabled	boolean	sim	—
policy.graceHours	integer	sim	0–8760
policy.batchSize	integer	sim	1–100
policy.intervalSeconds	integer	sim	5–86400
policy.delayMilliseconds	integer	sim	0–1000
lastRunAt	string (date-time)	sim	pode ser null
nextRunAt	string (date-time)	sim	pode ser null
lastCollected	integer	sim	0–100
lastDeferred	integer	sim	0–100
lastFailed	integer	sim	0–100
lastReclaimedBytes	string	sim	um número inteiro em dígitos decimais, enviado como string
lastError	string	sim	pode ser null

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

Exemplo

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

Configurar a limpeza online

PUT /api/v1/repositories/{repository}/storage/cleanup

Acesso: Permissão no repositório: storage.manage · Repetição: Repetir somente com a revisão esperada (compare-and-swap)

Substitui a política de limpeza com o servidor em execução: enabled (também para pausar), graceHours (0–8760, por quanto tempo o conteúdo excluído permanece antes da remoção), batchSize (1–100 objetos), intervalSeconds (5–86400) e delayMilliseconds (0–1000 entre objetos). expectedRevision deve ser a revisão atual (0 antes da primeira alteração); caso contrário, 409 revision_mismatch. Uma alteração entra em vigor entre objetos, nunca no meio de um.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
repository	caminho	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
expectedRevision	integer	sim	0–2147483647
policy	object	sim	—
policy.enabled	boolean	sim	—
policy.graceHours	integer	sim	0–8760
policy.batchSize	integer	sim	1–100
policy.intervalSeconds	integer	sim	5–86400
policy.delayMilliseconds	integer	sim	0–1000

Resposta 200

Campo	Tipo	Obrigatório	Regras
revision	integer	sim	0–2147483647
policy	object	sim	—
policy.enabled	boolean	sim	—
policy.graceHours	integer	sim	0–8760
policy.batchSize	integer	sim	1–100
policy.intervalSeconds	integer	sim	5–86400
policy.delayMilliseconds	integer	sim	0–1000
lastRunAt	string (date-time)	sim	pode ser null
nextRunAt	string (date-time)	sim	pode ser null
lastCollected	integer	sim	0–100
lastDeferred	integer	sim	0–100
lastFailed	integer	sim	0–100
lastReclaimedBytes	string	sim	um número inteiro em dígitos decimais, enviado como string
lastError	string	sim	pode ser null

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

Exemplo

curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/storage/cleanup" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0,"policy":{"enabled":false,"graceHours":0,"batchSize":1,"intervalSeconds":5,"delayMilliseconds":0}}'

Solicitar um lote de limpeza agora

POST /api/v1/repositories/{repository}/storage/cleanup/run

Acesso: Permissão no repositório: storage.manage · Repetição: Não repetir automaticamente

Agenda o próximo lote da política de limpeza ativada para começar imediatamente; a resposta é o estado da limpeza, e os bytes só são liberados quando o lote tiver sido executado (veja lastRunAt em getCleanup). expectedRevision deve ser a revisão atual; uma limpeza desativada gera 409 state_conflict. Objetos que estão sendo lidos ou gravados são adiados para um lote posterior.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
repository	caminho	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
expectedRevision	integer	sim	0–2147483647

Resposta 200

Campo	Tipo	Obrigatório	Regras
revision	integer	sim	0–2147483647
policy	object	sim	—
policy.enabled	boolean	sim	—
policy.graceHours	integer	sim	0–8760
policy.batchSize	integer	sim	1–100
policy.intervalSeconds	integer	sim	5–86400
policy.delayMilliseconds	integer	sim	0–1000
lastRunAt	string (date-time)	sim	pode ser null
nextRunAt	string (date-time)	sim	pode ser null
lastCollected	integer	sim	0–100
lastDeferred	integer	sim	0–100
lastFailed	integer	sim	0–100
lastReclaimedBytes	string	sim	um número inteiro em dígitos decimais, enviado como string
lastError	string	sim	pode ser null

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

Exemplo

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/storage/cleanup/run" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0}'