Convenções da API

Base URL: https://api.acquacloud.com.br. Tudo o que está documentado aqui funciona com um token de API. A lista completa de rotas está na referência.

VersionamentoCopiar o link da seção

Toda rota começa com a versão: /v1/.... Mudanças incompatíveis criam /v2/..., e a versão anterior continua disponível até ser descontinuada com aviso prévio. Campos novos em respostas não contam como mudança incompatível: ignore campos desconhecidos.

FormatoCopiar o link da seção

• JSON em UTF-8. Corpo de até 100 KB (uploads de .zip e de arquivos têm limites próprios).
• Datas em ISO 8601 com fuso (2026-10-06T22:00:00.000Z).
• IDs são UUIDv7.
• Toda resposta traz X-Request-Id. Você pode enviar o seu (8 a 64 caracteres [A-Za-z0-9_-]) para correlacionar com os seus logs.

ErrosCopiar o link da seção

Erros seguem a RFC 9457, com Content-Type: application/problem+json:

{
  "title": "Alguns campos estão inválidos.",
  "status": 400,
  "code": "validation_failed",
  "requestId": "0b9f…",
  "errors": [{ "path": "memoryMb", "message": "Mínimo: 100 MB", "code": "custom" }]
}

Baseie a lógica no campo code, que é estável. title e detail são textos para pessoas e podem mudar. Veja os códigos de erro.

Um recurso de outro workspace responde 404, não 403: a API não revela a existência de recursos aos quais você não tem acesso.

PaginaçãoCopiar o link da seção

Listas grandes usam cursor: ?limit=25&cursor=…, com a resposta { "data": [...], "nextCursor": "…" }. limit vai de 1 a 100 (padrão 25). Quando nextCursor vier null, não há mais páginas.

IdempotênciaCopiar o link da seção

Requisições POST aceitam o header Idempotency-Key (8 a 200 caracteres) para retentativas seguras:

As chaves valem por 24 horas, por token.

Limites de requisiçãoCopiar o link da seção

• 300 requisições por minuto por IP, com os headers X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.
• Ao exceder, a API responde 429 rate_limited com Retry-After.