Artefatos e catálogo

Artefatos publicados: listagem, detalhes, conteúdo, anotações, referências, pesquisa, a auditoria do catálogo e o feed de alterações.

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

Obter as anotações de um artefato

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

Acesso: Permissão no repositório: annotation.read; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)

Retorna os rótulos, os metadados e as coleções atuais de um artefato publicado com sua revision. A revisão 0 significa que nunca foram substituídos: os rótulos e os metadados são os informados quando o upload foi criado, e as coleções estão vazias. Passe a revisão para setAnnotations como expectedRevision.

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
revision	integer	sim	0–2147483647
labels	array de string	sim	até 32 itens
metadata	mapa de string	sim	até 32 entradas
collections	array de string	sim	até 32 itens

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

Exemplo

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

Substituir as anotações de um artefato

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

Acesso: Permissão no repositório: annotation.write, artifact.read; chaves em arquivo: read, write · Repetição: Repetir somente com a revisão esperada (compare-and-swap)

Substitui de uma só vez labels, metadata e collections de um artefato publicado; um campo omitido em value fica vazio. expectedRevision deve ser a revisão atual (0 para a primeira alteração); caso contrário, 409 revision_mismatch: leia as anotações novamente e reaplique a alteração. São permitidos até 32 rótulos e 32 coleções (1–64 letras, dígitos ou _.:-) e 32 entradas de metadados (valores de até 1024 caracteres); os bytes e o descritor original nunca mudam.

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	—

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
expectedRevision	integer	sim	0–2147483646
value	object	sim	—
value.labels	array de string	não	até 32 itens
value.metadata	mapa de string	não	até 32 entradas
value.collections	array de string	não	até 32 itens

Resposta 200

Campo	Tipo	Obrigatório	Regras
revision	integer	sim	0–2147483647
labels	array de string	sim	até 32 itens
metadata	mapa de string	sim	até 32 entradas
collections	array de string	sim	até 32 itens

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

Exemplo

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 um artefato como pacote UPack

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

Acesso: Permissão no repositório: package.publish, artifact.read; chaves em arquivo: read, write · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito

Abre o artefato publicado como um ZIP UPack, lê o upack.json da raiz (name, group opcional, version SemVer) e registra essa versão do pacote para ele; arquivos inseguros ou inválidos são rejeitados com 400. Uma versão é imutável: registrar o mesmo artefato novamente retorna a mesma entrada, e outro artefato para um grupo, nome e versão existentes (comparados sem distinção entre maiúsculas e minúsculas) gera 409 version_exists. Depois disso, a versão aparece em listPackages e é resolvida por nome, intervalo e estágio.

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
group	string	não	—
name	string	não	—
version	string	não	—
artifactId	string (uuid)	não	—
manifest	object	não	—

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

Exemplo

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

Pesquisar artefatos

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

Acesso: Permissão no repositório: artifact.list; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)

Encontra artefatos publicados por q (uma substring, sem distinção entre maiúsculas e minúsculas, do nome ou de um valor de metadados atual), um label atual exato, uma collection e um par exato metadataKey/metadataValue, que devem ser informados juntos; todos os filtros informados precisam coincidir. Os resultados vêm em páginas de 100 ordenadas por ID, cada um com tamanho, datas de criação e de publicação, rótulos atuais e estágios de promoção; continue com after definido como next. Metadados e coleções não são retornados: leia-os com getAnnotations.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
repository	caminho	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$
q	consulta	string	não	—
label	consulta	string	não	—
collection	consulta	string	não	—
after	consulta	string	não	—
metadataKey	consulta	string	não	corresponde a ^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$; até 64 caracteres; Exact metadata key; requires metadataValue.
metadataValue	consulta	string	não	até 1024 caracteres; Exact case-sensitive value; requires metadataKey. Empty string is allowed.

Resposta 200

Campo	Tipo	Obrigatório	Regras
items	array de object	sim	até 100 itens
items[].id	string (uuid)	sim	—
items[].name	string	sim	—
items[].size	string	sim	um número inteiro em dígitos decimais, enviado como string; Tamanho em bytes, string decimal
items[].createdAt	string (date-time)	sim	Hora da reserva do upload
items[].publishedAt	string (date-time)	sim	pode ser null; Hora de publicação; null somente quando nenhuma foi registrada
items[].labels	array de string	sim	até 32 itens; Rótulos atuais: os da anotação, quando substituídos; caso contrário, os do descritor do upload
items[].stages	array de string	sim	até 16 itens; cada item: corresponde a ^[a-z0-9][a-z0-9_.-]{0,31}$; Estágios de promoção atuais em ordem de bytes
next	string (uuid)	sim	pode ser null; Último ID de uma página cheia; passe-o como after

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

Exemplo

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

Ler a auditoria do catálogo de um repositório

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

Acesso: Permissão no repositório: audit.read; chaves em arquivo: write · Repetição: Pode ser repetida com segurança (leitura)

Retorna, do mais antigo para o mais recente, até 100 alterações do catálogo do repositório após o número de sequência after (padrão 0): publicações, exclusões, alterações de anotações e de anexos, registros de pacotes, alterações de caminhos de arquivo, referências, estágios e promoções, cada uma com ator, ação, artefato e hora. Para ler mais, passe o último sequence da página como after; não existe o campo next. Downloads e logins não constam nela; os espelhos seguem listCatalogChanges, que omite os atores.

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	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
items	array de object	não	—
items[].sequence	string	não	—
items[].actor	string	não	—
items[].action	string	não	—
items[].artifactId	string	não	—
items[].occurredAt	string (date-time)	não	—

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

Exemplo

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

Adicionar uma referência a um artefato

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

Acesso: Permissão no repositório: reference.write, artifact.read; chaves em arquivo: read, write · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito

Registra que algo fora do Arkvory usa este artefato, sob uma key à sua escolha (1–256 letras, dígitos ou _.:/-), por exemplo o nome de uma implantação. Um artefato referenciado não pode ser excluído nem removido pela retenção enquanto houver alguma referência. A referência pertence ao chamador; adicionar a mesma chave novamente não altera nada.

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	—

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
key	string	sim	até 256 caracteres

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

Exemplo

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>"}'

Remover uma referência de um artefato

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

Acesso: Permissão no repositório: reference.write, artifact.read; chaves em arquivo: read, write · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito

Remove do artefato a referência key do próprio chamador; as referências de outros chamadores permanecem. Remover uma chave que não existe também tem sucesso.

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	—

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
key	string	sim	até 256 caracteres

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

Exemplo

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 artefatos

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

Acesso: Permissão no repositório: artifact.list; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)

Lista os artefatos publicados do repositório ordenados por ID, limit por página (1–100, padrão 50); continue com after definido como next. next é definido sempre que uma página está cheia, portanto a última página pode estar vazia. Cada item traz o descritor informado no upload; os rótulos e os metadados atuais estão em getAnnotations.

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 (uuid)	não	—
limit	consulta	integer	não	1–100; padrão 50

Resposta 200

Campo	Tipo	Obrigatório	Regras
items	array de object	não	—
items[].id	string (uuid)	sim	—
items[].repository	string	sim	—
items[].status	string	sim	um destes: pending, available, cancelled
items[].createdAt	string (date-time)	sim	—
items[].expiresAt	string (date-time)	sim	—
items[].descriptor	object	sim	—
items[].descriptor.name	string	sim	1–240 caracteres
items[].descriptor.size	string	sim	um número inteiro em dígitos decimais, enviado como string
items[].descriptor.sha256	string	sim	SHA-256: 64 dígitos hexadecimais minúsculos
items[].descriptor.labels	array de string	não	até 32 itens; cada item: até 64 caracteres
items[].descriptor.metadata	mapa de string	não	até 32 entradas
next	string	não	pode ser null

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

Exemplo

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

Obter um artefato

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

Acesso: Permissão no repositório: artifact.read; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)

Retorna um artefato publicado: seu ID, repositório, status, data de criação e o descritor informado no upload (nome, tamanho, SHA-256, rótulos e metadados originais). Artefatos pendentes, cancelados e excluídos respondem 404. Para ler os bytes, use downloadArtifact.

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	—
repository	string	sim	—
status	string	sim	um destes: pending, available, cancelled
createdAt	string (date-time)	sim	—
expiresAt	string (date-time)	sim	—
descriptor	object	sim	—
descriptor.name	string	sim	1–240 caracteres
descriptor.size	string	sim	um número inteiro em dígitos decimais, enviado como string
descriptor.sha256	string	sim	SHA-256: 64 dígitos hexadecimais minúsculos
descriptor.labels	array de string	não	até 32 itens; cada item: até 64 caracteres
descriptor.metadata	mapa de string	não	até 32 entradas

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

Exemplo

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

Excluir um artefato

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

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

Exclui logicamente um artefato publicado: ele desaparece imediatamente de listas, pesquisas e downloads, e seus bytes são recuperados pela limpeza online do repositório (setCleanup, desativada por padrão) depois do período de carência. expectedAnnotationRevision deve ser igual à revisão atual das anotações. A resposta é 200 com um outcome: deleted, already_deleted, changed (a revisão difere), not_found ou protected com os blockers que o mantêm (uma referência, uma revisão de caminho de arquivo, um anexo de build ou um estágio de promoção). Verifique antes com inspectArtifactDeletion.

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	—

Corpo da solicitação (application/json)

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

Resposta 200

Campo	Tipo	Obrigatório	Regras
id	string (uuid)	sim	—
outcome	string	sim	um destes: deleted, already_deleted, protected, changed, not_eligible, not_found
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 DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedAnnotationRevision":0}'

Baixar um artefato

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

Acesso: Permissão no repositório: content.read; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)

Transmite os bytes originais com Content-Length, Content-Disposition (o nome do artefato) e um ETag forte ("sha256:<hex>"). Um único Range gera 206 (um intervalo fora do conteúdo gera 416); If-Range com o ETag retoma com segurança, e If-None-Match responde 304. HEAD retorna os mesmos cabeçalhos sem corpo e ignora Range. Em vez de um cabeçalho Authorization, a solicitação pode levar como token um link de download obtido de createDownloadLink; os downloads aguardam um slot livre na admissão de downloads do servidor.

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	—
Range	cabeçalho	string	não	—
If-Range	cabeçalho	string	não	—
If-None-Match	cabeçalho	string	não	—
Arkvory-Download-Id	cabeçalho	string	não	corresponde a ^[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	cabeçalho	string	não	até 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	cabeçalho	string	não	um destes: 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	não	corresponde a ^dtl_[A-Za-z0-9_-]{43}$; Download link from POST …/artifacts/{id}/links, instead of an Authorization header

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

Exemplo

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

Ler a visão geral dos sites

GET HEAD /api/v1/fleet/overview

Acesso: Administrador · Repetição: Pode ser repetida com segurança (leitura)

Alertas dos sites gerenciados e desta instalação, os mais graves primeiro (critical, warning, info), e os vínculos de espelho entre eles. Montada a partir das últimas leituras em segundo plano, no máximo uma vez a cada 5 segundos. Uma origem em cujo endereço nenhum site gerenciado responde é external:<origin>; esta instalação é self e só recebe vínculos quando ARKVORY_SITE_URL está definido. Somente o processo de gravação responde.

Resposta 200

Campo	Tipo	Obrigatório	Regras
generatedAt	string (date-time)	sim	—
self	object	sim	—
self.name	string	sim	—
self.version	string	sim	—
self.url	string	sim	pode ser null
alerts	array de object	sim	—
alerts[].site	string	sim	—
alerts[].name	string	sim	—
alerts[].kind	string	sim	um destes: unreachable, certificate, revoked, refused, invalid, stale, not-writable, copies, single-copy, mirror-failing, mirror-lag, updates-failed, version-skew
alerts[].severity	string	sim	um destes: critical, warning, info
alerts[].subject	string	sim	pode ser null
alerts[].since	string (date-time)	sim	pode ser null
links	array de object	sim	—
links[].from	string	sim	—
links[].to	string	sim	—
links[].repository	string	sim	—
links[].sourceRepository	string	sim	—
links[].mode	string	sim	um destes: mirror, import
links[].lagChanges	string	sim	um número inteiro em dígitos decimais, enviado como string; pode ser null
links[].failing	boolean	sim	—
links[].stale	boolean	não	—
external	array de string	sim	—

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

Exemplo

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

Listar os sites gerenciados

GET HEAD /api/v1/fleet/sites

Acesso: Administrador · Repetição: Pode ser repetida com segurança (leitura)

Lista os sites que esta instalação gerencia (ADR 0077) com o que cada um informou por último: state (ok, ou por que não foi lido: unreachable, certificate, revoked, invalid, refused), quando foi visto pela última vez e sua última topology. Os sites são lidos a cada 30 segundos em segundo plano. A chave de um site nunca é retornada.

Resposta 200

Campo	Tipo	Obrigatório	Regras
items	array de object	sim	até 256 itens
items[].id	string (uuid)	sim	—
items[].name	string	sim	—
items[].url	string	sim	—
items[].fingerprint	string	sim	corresponde a ^[0-9a-f]{64}$; pode ser null
items[].addedBy	string	sim	—
items[].addedAt	string (date-time)	sim	—
items[].seenAt	string (date-time)	sim	pode ser null
items[].state	string	sim	um destes: pending, ok, unreachable, certificate, revoked, invalid, refused
items[].error	string	sim	pode ser null
items[].topology	object	sim	pode ser null
items[].topology.collectedAt	string (date-time)	sim	—
items[].topology.site	object	sim	—
items[].topology.health	object	sim	—
items[].topology.replication	object	sim	pode ser null
items[].topology.gateways	array de object	sim	até 16 itens
items[].topology.mirrors	array de object	sim	até 64 itens
items[].topology.updates	object	sim	pode ser null
items[].topology.downloads	object	sim	—

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

Exemplo

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

Parear com um site

POST /api/v1/fleet/sites

Acesso: Administrador · Repetição: Não repetir automaticamente

Pareia um site: o controlador conecta de novo, o certificado precisa ainda ter a fingerprint que o administrador confirmou (null para HTTP em loopback), o code de pareamento criado no site é trocado por uma chave, e a chave é selada com ARKVORY_FLEET_KEY_FILE. O site é lido uma vez antes da resposta. Sem o arquivo de chave a resposta é 503.

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
url	string	sim	—
fingerprint	string	sim	corresponde a ^[0-9a-f]{64}$; pode ser null
code	string	sim	até 32 caracteres

Resposta 201

Campo	Tipo	Obrigatório	Regras
id	string (uuid)	sim	—
name	string	sim	—
url	string	sim	—
fingerprint	string	sim	corresponde a ^[0-9a-f]{64}$; pode ser null
addedBy	string	sim	—
addedAt	string (date-time)	sim	—
seenAt	string (date-time)	sim	pode ser null
state	string	sim	um destes: pending, ok, unreachable, certificate, revoked, invalid, refused
error	string	sim	pode ser null
topology	object	sim	pode ser null
topology.collectedAt	string (date-time)	sim	—
topology.site	object	sim	—
topology.site.name	string	sim	—
topology.site.version	string	sim	—
topology.site.schema	integer	sim	pelo menos 0
topology.site.role	string	sim	um destes: api, reader
topology.health	object	sim	—
topology.health.available	boolean	sim	—
topology.health.writable	boolean	sim	—
topology.health.draining	boolean	sim	—
topology.replication	object	sim	pode ser null
topology.replication.copies	integer	sim	0–16
topology.replication.required	integer	sim	1–16
topology.replication.singleCopyUntil	string (date-time)	sim	pode ser null
topology.replication.node	string	não	até 63 caracteres
topology.replication.profile	string	não	um destes: ha-2, ha-3
topology.replication.peers	array de object	não	até 16 itens
topology.gateways	array de object	sim	até 16 itens
topology.gateways[].slot	integer	sim	pelo menos 0
topology.gateways[].active	boolean	sim	—
topology.gateways[].expiresAt	string (date-time)	sim	—
topology.mirrors	array de object	sim	até 64 itens
topology.mirrors[].repository	string	sim	—
topology.mirrors[].mode	string	sim	um destes: mirror, import
topology.mirrors[].upstream	string	sim	—
topology.mirrors[].sourceRepository	string	sim	—
topology.mirrors[].phase	string	sim	—
topology.mirrors[].errorCode	string	sim	pode ser null
topology.mirrors[].checkedAt	string (date-time)	sim	pode ser null
topology.mirrors[].syncedAt	string (date-time)	sim	pode ser null
topology.mirrors[].lagChanges	string	sim	um número inteiro em dígitos decimais, enviado como string; pode ser null
topology.mirrors[].copiedArtifacts	integer	sim	pelo menos 0
topology.mirrors[].copiedBytes	string	sim	um número inteiro em dígitos decimais, enviado como string
topology.updates	object	sim	pode ser null
topology.updates.currentVersion	string	sim	—
topology.updates.latest	string	sim	pode ser null
topology.updates.phase	string	sim	—
topology.updates.error	string	sim	pode ser null
topology.updates.automatic	boolean	sim	—
topology.updates.heartbeatAt	string (date-time)	sim	—
topology.downloads	object	sim	—
topology.downloads.strategy	string	sim	um destes: ordered, smallest-first, shared
topology.downloads.sessions	integer	sim	pelo menos 0
topology.downloads.active	integer	sim	pelo menos 0
topology.downloads.waiting	integer	sim	pelo menos 0
topology.downloads.oldestWaitSeconds	integer	sim	pelo menos 0
topology.downloads.bytesPerSecond	integer	sim	pelo menos 0

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

Exemplo

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>"}'

Ler o certificado de um site

POST /api/v1/fleet/sites/probe

Acesso: Administrador · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito

Conecta ao endereço e lê o certificado do site sem enviar nada: compare sua fingerprint com a que o administrador do site vê antes de parear.

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
url	string	sim	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
url	string	sim	—
certificate	object	sim	pode ser null
certificate.fingerprint	string	sim	corresponde a ^[0-9a-f]{64}$
certificate.subject	string	sim	—
certificate.issuer	string	sim	—
certificate.validTo	string (date-time)	sim	—

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

Exemplo

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

Esquecer um site

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

Acesso: Administrador · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito

Esquece aqui um site e sua chave selada. Revogue também este controlador no site; até lá a chave continua válida lá.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
id	caminho	string (uuid)	sim	—

Respostas: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

Exemplo

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

Ler o catálogo de um site

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

Acesso: Administrador · Repetição: Pode ser repetida com segurança (leitura)

Repassa uma leitura do catálogo a um site gerenciado e devolve a resposta dele sem alterações: repositórios, busca, artefatos, anotações, estágios, pacotes, páginas e histórico de arquivos, uso de armazenamento, estado do espelho. path é a rota do site com sua consulta. Outras rotas e bytes de arquivos são recusados com 400.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
id	caminho	string (uuid)	sim	—
path	consulta	string	sim	corresponde a ^/api/v1/; até 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.

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

Exemplo

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

Alterar uma configuração de um site

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

Acesso: Administrador · Repetição: Não repetir automaticamente

Repassa uma alteração a um site gerenciado e devolve a resposta dele sem alterações. path é uma destas rotas: /api/v1/system/downloads/settings (configurações da fila de downloads, enviada como PUT) ou /api/v1/system/updates/requests (uma solicitação de atualização, enviada como POST). O corpo vai ao site como está; o site verifica a revisão ou o id da solicitação, então uma alteração repetida não é aplicada duas vezes. Outros caminhos são recusados com 400.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
id	caminho	string (uuid)	sim	—
path	consulta	string	sim	corresponde a ^/api/v1/; até 2048 caracteres; A change route of the site, from a fixed list: PUT /api/v1/system/downloads/settings, POST /api/v1/system/updates/requests.

Corpo da solicitação (application/json)

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

Exemplo

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

Ler um site agora

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

Acesso: Administrador · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito

Lê o site agora em vez de esperar a próxima rodada e o retorna com o novo estado.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
id	caminho	string (uuid)	sim	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
id	string (uuid)	sim	—
name	string	sim	—
url	string	sim	—
fingerprint	string	sim	corresponde a ^[0-9a-f]{64}$; pode ser null
addedBy	string	sim	—
addedAt	string (date-time)	sim	—
seenAt	string (date-time)	sim	pode ser null
state	string	sim	um destes: pending, ok, unreachable, certificate, revoked, invalid, refused
error	string	sim	pode ser null
topology	object	sim	pode ser null
topology.collectedAt	string (date-time)	sim	—
topology.site	object	sim	—
topology.site.name	string	sim	—
topology.site.version	string	sim	—
topology.site.schema	integer	sim	pelo menos 0
topology.site.role	string	sim	um destes: api, reader
topology.health	object	sim	—
topology.health.available	boolean	sim	—
topology.health.writable	boolean	sim	—
topology.health.draining	boolean	sim	—
topology.replication	object	sim	pode ser null
topology.replication.copies	integer	sim	0–16
topology.replication.required	integer	sim	1–16
topology.replication.singleCopyUntil	string (date-time)	sim	pode ser null
topology.replication.node	string	não	até 63 caracteres
topology.replication.profile	string	não	um destes: ha-2, ha-3
topology.replication.peers	array de object	não	até 16 itens
topology.gateways	array de object	sim	até 16 itens
topology.gateways[].slot	integer	sim	pelo menos 0
topology.gateways[].active	boolean	sim	—
topology.gateways[].expiresAt	string (date-time)	sim	—
topology.mirrors	array de object	sim	até 64 itens
topology.mirrors[].repository	string	sim	—
topology.mirrors[].mode	string	sim	um destes: mirror, import
topology.mirrors[].upstream	string	sim	—
topology.mirrors[].sourceRepository	string	sim	—
topology.mirrors[].phase	string	sim	—
topology.mirrors[].errorCode	string	sim	pode ser null
topology.mirrors[].checkedAt	string (date-time)	sim	pode ser null
topology.mirrors[].syncedAt	string (date-time)	sim	pode ser null
topology.mirrors[].lagChanges	string	sim	um número inteiro em dígitos decimais, enviado como string; pode ser null
topology.mirrors[].copiedArtifacts	integer	sim	pelo menos 0
topology.mirrors[].copiedBytes	string	sim	um número inteiro em dígitos decimais, enviado como string
topology.updates	object	sim	pode ser null
topology.updates.currentVersion	string	sim	—
topology.updates.latest	string	sim	pode ser null
topology.updates.phase	string	sim	—
topology.updates.error	string	sim	pode ser null
topology.updates.automatic	boolean	sim	—
topology.updates.heartbeatAt	string (date-time)	sim	—
topology.downloads	object	sim	—
topology.downloads.strategy	string	sim	um destes: ordered, smallest-first, shared
topology.downloads.sessions	integer	sim	pelo menos 0
topology.downloads.active	integer	sim	pelo menos 0
topology.downloads.waiting	integer	sim	pelo menos 0
topology.downloads.oldestWaitSeconds	integer	sim	pelo menos 0
topology.downloads.bytesPerSecond	integer	sim	pelo menos 0

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

Exemplo

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

Criar um código de pareamento

POST /api/v1/system/fleet/pairings

Acesso: Administrador · Repetição: Não repetir automaticamente

Cria um código de uso único, válido por dez minutos, que o administrador de um controlador digita para gerenciar este site. O código é mostrado uma vez e guardado apenas como hash. Só o administrador global do site pode criá-lo.

Resposta 201

Campo	Tipo	Obrigatório	Regras
code	string	sim	corresponde a ^[0-9A-Z]{4}-[0-9A-Z]{4}-[0-9A-Z]{4}$
expiresAt	string (date-time)	sim	—
fingerprint	string	sim	corresponde a ^[0-9a-f]{64}$; pode ser null

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

Exemplo

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

Listar os controladores do site

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

Acesso: Administrador · Repetição: Pode ser repetida com segurança (leitura)

Lista os controladores que podem gerenciar este site: nome, quem os pareou, quando e quando sua chave foi usada pela última vez.

Resposta 200

Campo	Tipo	Obrigatório	Regras
items	array de object	sim	até 100 itens
items[].id	string (uuid)	sim	—
items[].name	string	sim	—
items[].pairedBy	string	sim	—
items[].pairedAt	string (date-time)	sim	—
items[].usedAt	string (date-time)	sim	pode ser null

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

Exemplo

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

Revogar um controlador

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

Acesso: Administrador · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito

Revoga um controlador: sua chave de frota é recusada na hora. Para gerenciar o site de novo, ele precisa parear com um novo código.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
id	caminho	string (uuid)	sim	—

Respostas: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

Exemplo

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

Parear com um controlador

POST /api/v1/system/fleet/enrollment

Acesso: Qualquer pessoa, sem chave · Repetição: Não repetir automaticamente

Troca uma vez um código de pareamento válido por uma chave de frota. O controlador o chama por TLS fixado na impressão digital que o administrador confirmou. A chave é retornada uma vez e alcança só as rotas de que um controlador precisa.

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
code	string	sim	até 32 caracteres
name	string	sim	1–63 caracteres

Resposta 201

Campo	Tipo	Obrigatório	Regras
key	string	sim	corresponde a ^afk_[A-Za-z0-9_-]{43}$
site	object	sim	—
site.name	string	sim	—
site.version	string	sim	—

Respostas: 201, 400, 403, 405, 413, 415, 503

Exemplo

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

Obter este site para o console da frota

GET HEAD /api/v1/system/topology

Acesso: Administrador · Repetição: Pode ser repetida com segurança (leitura)

Retorna esta instalação como um site de uma frota (ADR 0077): nome, versão, esquema e papel, se está disponível e aceita gravações, as cópias e nós de HA, os gateways de leitura pelas suas concessões, cada espelho e importação com fase, última sincronização e lagChanges (alterações da origem ainda não aplicadas), o estado do agente de atualização e a fila de downloads. Só o administrador global do site ou um controlador pareado pode lê-lo.

Resposta 200

Campo	Tipo	Obrigatório	Regras
collectedAt	string (date-time)	sim	—
site	object	sim	—
site.name	string	sim	—
site.version	string	sim	—
site.schema	integer	sim	pelo menos 0
site.role	string	sim	um destes: api, reader
health	object	sim	—
health.available	boolean	sim	—
health.writable	boolean	sim	—
health.draining	boolean	sim	—
replication	object	sim	pode ser null
replication.copies	integer	sim	0–16
replication.required	integer	sim	1–16
replication.singleCopyUntil	string (date-time)	sim	pode ser null
replication.node	string	não	até 63 caracteres
replication.profile	string	não	um destes: ha-2, ha-3
replication.peers	array de object	não	até 16 itens
replication.peers[].name	string	sim	até 63 caracteres
replication.peers[].connected	boolean	sim	—
replication.peers[].disk	string	sim	até 24 caracteres
replication.peers[].complete	boolean	sim	—
replication.peers[].witness	boolean	sim	—
gateways	array de object	sim	até 16 itens
gateways[].slot	integer	sim	pelo menos 0
gateways[].active	boolean	sim	—
gateways[].expiresAt	string (date-time)	sim	—
mirrors	array de object	sim	até 64 itens
mirrors[].repository	string	sim	—
mirrors[].mode	string	sim	um destes: mirror, import
mirrors[].upstream	string	sim	—
mirrors[].sourceRepository	string	sim	—
mirrors[].phase	string	sim	—
mirrors[].errorCode	string	sim	pode ser null
mirrors[].checkedAt	string (date-time)	sim	pode ser null
mirrors[].syncedAt	string (date-time)	sim	pode ser null
mirrors[].lagChanges	string	sim	um número inteiro em dígitos decimais, enviado como string; pode ser null
mirrors[].copiedArtifacts	integer	sim	pelo menos 0
mirrors[].copiedBytes	string	sim	um número inteiro em dígitos decimais, enviado como string
updates	object	sim	pode ser null
updates.currentVersion	string	sim	—
updates.latest	string	sim	pode ser null
updates.phase	string	sim	—
updates.error	string	sim	pode ser null
updates.automatic	boolean	sim	—
updates.heartbeatAt	string (date-time)	sim	—
downloads	object	sim	—
downloads.strategy	string	sim	um destes: ordered, smallest-first, shared
downloads.sessions	integer	sim	pelo menos 0
downloads.active	integer	sim	pelo menos 0
downloads.waiting	integer	sim	pelo menos 0
downloads.oldestWaitSeconds	integer	sim	pelo menos 0
downloads.bytesPerSecond	integer	sim	pelo menos 0

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

Exemplo

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

Ler as configurações da fila de downloads

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

Acesso: Administrador · Repetição: Pode ser repetida com segurança (leitura)

Retorna os valores alterados (overrides), o que o ambiente do servidor define (defaults) e o que a fila usa agora (effective), com a revisão a enviar ao alterar. problem diz por que as configurações salvas não servem para este servidor; a fila então funciona com os padrões.

Resposta 200

Campo	Tipo	Obrigatório	Regras
revision	integer	sim	0–9007199254740991
overrides	object	sim	—
overrides.strategy	string	não	um destes: ordered, smallest-first, shared
overrides.sessions	integer	não	1–1024
overrides.reserve	integer	não	0–1023
overrides.perPrincipal	integer	não	1–1024
overrides.weights	object	não	—
overrides.weights.interactive	integer	sim	1–1000
overrides.weights.release	integer	sim	1–1000
overrides.weights.bulk	integer	sim	1–1000
overrides.weights.background	integer	sim	1–1000
overrides.sessionMinBytes	integer	não	0–9007199254740991
overrides.idleSeconds	integer	não	1–3600
overrides.agingMinutes	integer	não	0–10080
overrides.preempt	boolean	não	—
overrides.rangesPerSession	integer	não	1–64
defaults	object	sim	—
defaults.strategy	string	sim	um destes: ordered, smallest-first, shared
defaults.sessions	integer	sim	1–1024
defaults.reserve	integer	sim	0–1023
defaults.perPrincipal	integer	sim	1–1024
defaults.weights	object	sim	—
defaults.weights.interactive	integer	sim	1–1000
defaults.weights.release	integer	sim	1–1000
defaults.weights.bulk	integer	sim	1–1000
defaults.weights.background	integer	sim	1–1000
defaults.sessionMinBytes	integer	sim	0–9007199254740991
defaults.idleSeconds	integer	sim	1–3600
defaults.agingMinutes	integer	sim	0–10080
defaults.preempt	boolean	sim	—
defaults.rangesPerSession	integer	sim	1–64
effective	object	sim	—
effective.strategy	string	sim	um destes: ordered, smallest-first, shared
effective.sessions	integer	sim	1–1024
effective.reserve	integer	sim	0–1023
effective.perPrincipal	integer	sim	1–1024
effective.weights	object	sim	—
effective.weights.interactive	integer	sim	1–1000
effective.weights.release	integer	sim	1–1000
effective.weights.bulk	integer	sim	1–1000
effective.weights.background	integer	sim	1–1000
effective.sessionMinBytes	integer	sim	0–9007199254740991
effective.idleSeconds	integer	sim	1–3600
effective.agingMinutes	integer	sim	0–10080
effective.preempt	boolean	sim	—
effective.rangesPerSession	integer	sim	1–64
admission	string	sim	um destes: sessions, per-request
updatedAt	string (date-time)	sim	pode ser null
updatedBy	string	sim	pode ser null
actor	string	sim	pode ser null
problem	string	sim	pode ser null

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

Exemplo

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

Alterar as configurações da fila de downloads

PUT /api/v1/system/downloads/settings

Acesso: Administrador · Repetição: Repetir somente com a revisão esperada (compare-and-swap)

Salva overrides sobre o ambiente do servidor e os aplica sem reiniciar: novas decisões os seguem de imediato e downloads ativos mantêm seus lugares. Os valores enviados substituem todas as alterações anteriores; {} volta ao ambiente. Configurações que não podem funcionar aqui são recusadas com 400 indicando o campo; uma expectedRevision desatualizada recebe 409. Gateways de leitura mantêm seu ambiente.

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
expectedRevision	integer	sim	0–9007199254740991
overrides	object	sim	—
overrides.strategy	string	não	um destes: ordered, smallest-first, shared
overrides.sessions	integer	não	1–1024
overrides.reserve	integer	não	0–1023
overrides.perPrincipal	integer	não	1–1024
overrides.weights	object	não	—
overrides.weights.interactive	integer	sim	1–1000
overrides.weights.release	integer	sim	1–1000
overrides.weights.bulk	integer	sim	1–1000
overrides.weights.background	integer	sim	1–1000
overrides.sessionMinBytes	integer	não	0–9007199254740991
overrides.idleSeconds	integer	não	1–3600
overrides.agingMinutes	integer	não	0–10080
overrides.preempt	boolean	não	—
overrides.rangesPerSession	integer	não	1–64

Resposta 200

Campo	Tipo	Obrigatório	Regras
revision	integer	sim	0–9007199254740991
overrides	object	sim	—
overrides.strategy	string	não	um destes: ordered, smallest-first, shared
overrides.sessions	integer	não	1–1024
overrides.reserve	integer	não	0–1023
overrides.perPrincipal	integer	não	1–1024
overrides.weights	object	não	—
overrides.weights.interactive	integer	sim	1–1000
overrides.weights.release	integer	sim	1–1000
overrides.weights.bulk	integer	sim	1–1000
overrides.weights.background	integer	sim	1–1000
overrides.sessionMinBytes	integer	não	0–9007199254740991
overrides.idleSeconds	integer	não	1–3600
overrides.agingMinutes	integer	não	0–10080
overrides.preempt	boolean	não	—
overrides.rangesPerSession	integer	não	1–64
defaults	object	sim	—
defaults.strategy	string	sim	um destes: ordered, smallest-first, shared
defaults.sessions	integer	sim	1–1024
defaults.reserve	integer	sim	0–1023
defaults.perPrincipal	integer	sim	1–1024
defaults.weights	object	sim	—
defaults.weights.interactive	integer	sim	1–1000
defaults.weights.release	integer	sim	1–1000
defaults.weights.bulk	integer	sim	1–1000
defaults.weights.background	integer	sim	1–1000
defaults.sessionMinBytes	integer	sim	0–9007199254740991
defaults.idleSeconds	integer	sim	1–3600
defaults.agingMinutes	integer	sim	0–10080
defaults.preempt	boolean	sim	—
defaults.rangesPerSession	integer	sim	1–64
effective	object	sim	—
effective.strategy	string	sim	um destes: ordered, smallest-first, shared
effective.sessions	integer	sim	1–1024
effective.reserve	integer	sim	0–1023
effective.perPrincipal	integer	sim	1–1024
effective.weights	object	sim	—
effective.weights.interactive	integer	sim	1–1000
effective.weights.release	integer	sim	1–1000
effective.weights.bulk	integer	sim	1–1000
effective.weights.background	integer	sim	1–1000
effective.sessionMinBytes	integer	sim	0–9007199254740991
effective.idleSeconds	integer	sim	1–3600
effective.agingMinutes	integer	sim	0–10080
effective.preempt	boolean	sim	—
effective.rangesPerSession	integer	sim	1–64
admission	string	sim	um destes: sessions, per-request
updatedAt	string (date-time)	sim	pode ser null
updatedBy	string	sim	pode ser null
actor	string	sim	pode ser null
problem	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/system/downloads/settings" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0,"overrides":{}}'

Ler as alterações do site

GET HEAD /api/v1/system/changes

Acesso: Administrador · Repetição: Pode ser repetida com segurança (leitura)

Retorna se o agente do site responde (agent), a solicitação pendente e as 20 mais recentes com seu estado: pending, applying, done ou failed com o motivo. Chaves de origem nunca aparecem aqui.

Resposta 200

Campo	Tipo	Obrigatório	Regras
agent	boolean	sim	—
updating	boolean	sim	—
blocked	string	sim	um destes: expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; pode ser null
pending	object	sim	pode ser null
pending.id	string (uuid)	sim	—
pending.kind	string	sim	um destes: mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy
pending.actor	string	sim	até 200 caracteres
pending.requestedAt	string (date-time)	sim	—
recent	array de object	sim	até 20 itens
recent[].id	string (uuid)	sim	—
recent[].digest	string	sim	corresponde a ^[0-9a-f]{64}$
recent[].kind	string	sim	um destes: mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy
recent[].state	string	sim	um destes: pending, applying, done, failed
recent[].error	string	sim	um destes: expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; pode ser null
recent[].actor	string	sim	até 200 caracteres
recent[].requestedAt	string (date-time)	sim	—
recent[].finishedAt	string (date-time)	sim	pode ser null

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

Exemplo

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

Enfileirar uma alteração do site

POST /api/v1/system/changes

Acesso: Administrador · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito

Enfileira uma alteração para o agente do site, que a aplica em até um minuto com as verificações e a reversão de arkvory configure e cluster-*: conectar um espelho ou uma importação, substituir sua chave de origem, desconectar espelhos, trocar o nó HA ativo (nome do nó digitado duas vezes) ou decidir gravações com uma cópia. id é escolhido pelo cliente; repeti-lo não enfileira a alteração de novo. key é a chave de origem apenas de mirror-attach e mirror-key: vai ao agente em um arquivo 0600 próprio e nunca é devolvida. 202 significa enfileirado, não aplicado.

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
id	string (uuid)	sim	—
change	object	sim	—
change.kind	string	sim	um destes: mirror-attach
change.repository	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$
change.upstream	string	sim	até 255 caracteres
change.sourceRepository	string	sim	corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$
change.stages	array de string	não	1–16 itens; cada item: corresponde a ^[a-z0-9][a-z0-9_.-]{0,31}$; pode ser null
change.repositories	array de string	sim	1–64 itens; cada item: corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$
change.node	string	sim	corresponde a ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$
change.confirm	string	sim	corresponde a ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$
change.until	string (date-time)	sim	pode ser null
change.reason	string	sim	1–200 caracteres
key	string	não	16–4000 caracteres

Resposta 202

Campo	Tipo	Obrigatório	Regras
id	string (uuid)	sim	—

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

Exemplo

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>"}}'

Acompanhar o feed de alterações de um repositório

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

Acesso: Permissão no repositório: artifact.list; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)

Retorna, em ordem de confirmação (commit), até limit alterações (1–100, padrão 100) após a sequência after (padrão 0): ação, artefato e, para caminhos de arquivo e estágios, o caminho ou o estágio em detail; os atores são omitidos, portanto o acesso de listagem basta. head é a sequência mais recente do repositório e next é o cursor da página seguinte, ou null quando a página alcançou o head. Um espelho armazena a última sequência aplicada e consulta a partir dela.

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; Sequence cursor, default 0
limit	consulta	integer	não	1–100

Resposta 200

Campo	Tipo	Obrigatório	Regras
items	array de object	sim	—
items[].sequence	string	sim	um número inteiro em dígitos decimais, enviado como string
items[].action	string	sim	—
items[].artifactId	string (uuid)	sim	—
items[].detail	string	sim	pode ser null
head	string	sim	um número inteiro em dígitos decimais, enviado como string
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/changes" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Criar um link de download

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

Acesso: Permissão no repositório: content.read; chaves em arquivo: read · Repetição: Não repetir automaticamente

Retorna um token secreto, uma url relativa à origem da API e expiresAt para usar downloadArtifact apenas deste artefato, sem chave; ttlSeconds define a duração (de 60 segundos a um dia, padrão uma hora). O token é exibido somente nesta resposta e não pode ser revogado: ele deixa de funcionar quando expira ou quando o artefato é excluído, e os downloads feitos com ele contam nos limites de transferência do criador. Um chamador pode ter 1000 links ativos (507 token_limit), e um link de download não pode criar outros links.

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	—

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
ttlSeconds	integer	não	60–86400; padrão 3600

Resposta 201

Campo	Tipo	Obrigatório	Regras
token	string	sim	corresponde a ^dtl_[A-Za-z0-9_-]{43}$
url	string	sim	—
expiresAt	string (date-time)	sim	—

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

Exemplo

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