Guias

Primeiros passos

Tenha o hostname HTTPS do seu tenant e uma credencial com as permissões necessárias. A URL base é https://{tenant_host}/api/v1: substitua tenant_host pelo hostname do seu ambiente. O domínio deste site de documentação não é a origem da API do tenant.

Para consultar o inventário, use GET /devices com devices:read. Os caminhos mostrados na referência são relativos à URL base /api/v1. Use os IDs retornados pela API ao consultar dispositivos, execuções e arquivos; não deduza IDs por nome.

Em coleções, leia data.items e reutilize meta.next_cursor sem modificar seu valor até ele ser null. Mantenha o mesmo token, filtros e limit entre páginas. O cursor expira em 30 minutos; mudanças de permissões ou parâmetros exigem reiniciar a paginação.

Os filtros são aplicados antes da paginação. A inclusão tem um corte temporal, mas acesso atual, associação a grupos e exclusões são revistos a cada página. A coleção não oferece contagem global ou snapshot transacional entre requisições.

Autenticação e permissões

Envie a credencial apenas no cabeçalho Authorization: Bearer. Cookies do navegador não autenticam a API. A credencial é opaca, não é JWT e este esquema não é OAuth. O exemplo do cabeçalho representa somente a sintaxe; não contém um token real.

As permissões são independentes: autorizar uma operação não autoriza as demais. Confira a tabela abaixo e x-required-scope na referência. Por exemplo, backups:run não concede runs:read, backups:metadata:read ou backups:download.

O acesso combina dispositivos selecionados individualmente com os membros atuais dos grupos selecionados. Tenant, recursos, permissões, expiração e revogação são verificados novamente em cada chamada.

Revogar impede novas chamadas; não cancela trabalho já aceito. Rotacionar invalida a credencial anterior imediatamente. Não coloque credenciais em URLs, exemplos compartilhados ou registros de diagnóstico.

Authorization: Bearer <token>

Executar e acompanhar backups

Para iniciar, envie POST /devices/{identifier}/runs com backups:run, Content-Type: application/json, corpo {} e Idempotency-Key. A resposta 202 significa aceitação para processamento assíncrono, não conclusão do backup. Consulte run_href com runs:read para acompanhar a execução.

Idempotency-Key aceita 1 a 200 caracteres ASCII imprimíveis, sem espaços. Reutilize a mesma chave e corpo ao repetir a mesma solicitação. A chave é mantida por 24 horas e vinculada ao tenant, token, rota e corpo JSON normalizado. Corpo divergente gera 409.

Uma execução ativa é reutilizada. Novas solicitações externas compartilham um intervalo de 60 segundos por tenant/dispositivo. Cobrança, ciclo de vida do tenant e confiança SSH continuam condicionando a operação.

Metadados e download têm permissões separadas. Apenas execuções success com artefato e validação valid ou legacy_unverified são elegíveis. O estado legado não comprova uma avaliação consolidada de proteção.

GET /backups/{identifier}/download devolve o arquivo, sem redirecionar para storage externo. Uma falha depois do início da transferência encerra a conexão, sem inserir JSON no arquivo. A conclusão no servidor não comprova o recebimento pelo cliente. HEAD mantém a autorização e devolve cabeçalhos de attachment sem buscar o arquivo, iniciar transferência ou enviar Content-Length dependente do corpo; a existência no storage é confirmada por GET.

Erros e novas tentativas

Use error.code para decidir o tratamento, não a mensagem traduzida. Preserve correlation_id ou X-Correlation-ID para diagnóstico; esses valores não são credenciais. Consulte na referência os códigos específicos de cada operação.

401 indica credencial ausente, inválida, expirada, rotacionada ou revogada. 403 indica falta da permissão exigida; ao executar backup, também pode indicar restrição de cobrança. 404 pode indicar ausência do recurso, tenant desconhecido, recurso fora do escopo ou artefato inexistente.

409 distingue conflitos pelo código: cursor_invalid exige reiniciar a paginação; idempotency_conflict indica divergência da mesma solicitação. Restrições tenant_read_only e host_key_required também aparecem na execução. 410 indica tenant inativo ou ambiente em encerramento.

400 indica solicitação ou JSON malformado. Em 405, consulte Allow para os métodos aceitos pelo recurso, incluindo HEAD e OPTIONS onde aplicável.

422 indica parâmetros, corpo ou chave de idempotência inválidos. 413 sinaliza tamanho acima do permitido; 415 exige application/json na execução. 503 indica indisponibilidade de serviço, storage ou persistência de auditoria: a operação falha de forma fechada.

Em 429, respeite Retry-After em segundos. Para repetir a mesma criação de execução, preserve Idempotency-Key e corpo. Erros anteriores ao início de um download são JSON; após iniciar a transferência, verifique também a integridade e o recebimento do arquivo.

Limites e paginação

Os limites padrão compartilhados por janela fixa de um minuto são 30 tentativas por origem/tenant antes da autenticação, incluindo chamadas válidas; 120 requisições por token; e 600 por tenant. A configuração do backend pode alterar esses valores. O contrato da versão utilizada é a referência vigente.

limit aceita 1 a 100 itens, com padrão 50. Filtros desconhecidos, duplicados ou inválidos são rejeitados. Os filtros from e to de execuções e backups usam UTC terminado em Z; offsets numéricos não são aceitos, e to não pode preceder from.

A solicitação de execução aceita somente {} e tem limite de 16 KiB. Downloads estão sujeitos a tamanho e timeout configurados; não há um tamanho máximo universal declarado neste guia.

Permissões por operação