REST API

Onde no portal: Referência da API em https://<your-domain>/apidoc (pública) e chaves de API em /api-keys. Onde no admin: Customers › API keys (/customers/apikeys) lista as chaves criadas pelos clientes.

O que faz

Todas as ações que um cliente pode realizar no portal — listar e controlar VMs, ler faturas, gerenciar chaves SSH, Kubernetes, armazenamento e tickets de suporte — estão disponíveis por meio de uma API REST versionada em https://<your-domain>/v1/. Os clientes a chamam de scripts e CI com uma API key com escopo definido. A mesma API alimenta a cmp command-line tool e o MCP server, e a referência é gerada a partir da instalação em execução, listando sempre exatamente os recursos que você ativou.

Requisitos

Item	Requisito
Endereço HTTPS público	A API é servida no seu domínio principal (e no domínio próprio de cada revendedor).
Uma chave de API	Criada pelo cliente no portal; consulte API keys.
Dependências	Nenhum. Os endpoints de um módulo que você não ativou (por exemplo, Kubernetes ou Object Storage) ficam ocultos na referência e são recusados.

Preparar a infraestrutura

Nada para instalar. Se houver um proxy reverso na frente do NexCMP, encaminhe /v1/, /mcp, /cli/ e /apidoc para o painel (a configuração do nginx do instalador já faz isso).

Conectar no NexCMP

A referência interativa

Abra https://cloud.example.com/apidoc (substitua o host pelo seu domínio; os clientes de um revendedor veem a referência no domínio do revendedor, com o nome dele). Ela possui documentação de endpoints com exemplos de solicitação e resposta em curl, cmp CLI, JavaScript, Python e Go, uma caixa de pesquisa (Ctrl ou Cmd + K) e um painel Try it. O Try it envia solicitações apenas para o mesmo site, com uma chave colada pelo visitante (mantida na sessão do navegador); ele é somente leitura por padrão, e chamadas de gravação ou pagas exigem um comando extra e confirmação.

Downloads e documentos legíveis por máquina

Todos são públicos, não exigem chave e são gerados por site:

URL	Conteúdo
/apidoc	Referência interativa.
/v1/public/openapi.json	Documento OpenAPI 3.1.
/v1/public/openapi.yaml	O mesmo, em YAML.
/v1/public/postman.json	Coleção do Postman.
/v1/public/insomnia.json	Exportação do Insomnia.
/v1/public/api.md	A referência como um único arquivo Markdown.
/v1/public/api-catalog	JSON leve: marca, URL base, prefixo de chave, cada escopo e cada endpoint com método, caminho, escopo e se ele precisa de um Idempotency-Key.

curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40
curl -sO https://cloud.example.com/v1/public/openapi.yaml

No Postman, escolha Import › Link e cole https://cloud.example.com/v1/public/postman.json. A página de referência também oferece clientes de API em arquivo único para JavaScript e Python.

Autenticação

Envie a chave no cabeçalho Authorization:

curl -s https://cloud.example.com/v1/billing/wallet \
  -H "Authorization: Bearer vk_XXXX"

• As chaves de cliente começam com vk_. As chaves são vinculadas ao site: uma chave criada em cloud.example.com não funciona no domínio de um revendedor.
• Tokens de sessão do navegador (pt_...) são apenas para o portal; use uma chave para automação.
• Os escopos da chave decidem o que ela pode chamar; um escopo ausente responde com HTTP 403 scope_required. Consulte API keys.
• Verifique uma chave com GET /v1/apikeys/self: ele retorna o nome da chave chamadora, escopos, validade e o limite restante de taxa (qualquer chave pode chamá-lo).

Exemplos

# List virtual machines
curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX"

# Start one (needs vm:write)
curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \
  -H "Authorization: Bearer vk_XXXX"

# Create a VM (paid: needs vm:create and an Idempotency-Key)
curl -s -X POST https://cloud.example.com/v1/vm \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @vm.json

Obtenha os campos exatos de requisição de cada operação em /apidoc.

Erros

Cada erro é um JSON com um code estável e uma message legível por humanos:

{"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}}

HTTP	code Típico	Significado
401	unauthenticated, key_invalid, key_revoked, key_expired, key_ip_denied, site_mismatch, api_keys_disabled	Chave ausente ou desconhecida, revogada, expirada, IP do chamador fora da lista de permissões da chave, chave de outro site ou chaves de API desativadas.
403	scope_required, endpoint_not_public, account_blocked, quota_exceeded, impersonate_forbidden	A chave não tem o escopo; o endpoint não está disponível para chaves; a conta está bloqueada; uma quota foi atingida; ação não permitida em uma sessão impersonada.
404	not_found	Não encontrado — também retornado para recursos que pertencem a outra pessoa.
422	invalid_argument	Erro de validação (campo nomeado na resposta).
429	rate_limited	Muitas solicitações; aguarde por Retry-After.
503	maintenance	O modo de manutenção está ativado: leituras funcionam, gravações são recusadas.

Limites de taxa

Limite	Padrão
Por chave	120 requisições por minuto
Por conta (todas as chaves juntas)	300 requisições por minuto

Cada resposta carrega X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; um 429 adiciona Retry-After.

Idempotência

Comandos que custam dinheiro ou não podem ser repetidos (criar, alterar plano, comprar, excluir ...) exigem um cabeçalho Idempotency-Key (qualquer string de até 200 caracteres; um UUID funciona bem). Envie a mesma chave novamente após um tempo limite e o servidor retornará o resultado original (com Idempotency-Replayed: 1) em vez de repetir a operação. Reutilizar uma chave para um comando diferente responde com 422; uma requisição ainda emandamento responde com 409/Retry-After. Sem o cabeçalho, uma chamada paga é recusada.

Verificar

1. Crie uma chave com o escopo vm:read no portal (API keys › Create key).

2. Execute:

   curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX"

   Você obtém o HTTP 200 e os cabeçalhos de limite de taxa.

3. curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" lista as VMs da conta. No portal, a coluna Last used da chave e o Key usage log mostram as chamadas.

Limites e notas

• Nunca disponíveis para uma chave: recarregar, sacar, alterar cartões ou recarga automática, alterar senha, e-mail ou 2FA, excluir a conta, criar, editar ou revogar outras chaves. Essas ações exigem uma sessão de navegador iniciada.
• Módulos ocultos: a referência e o documento OpenAPI listam apenas os recursos habilitados naquele site.
• Tamanho de resposta e paginação: os endpoints de listagem são paginados (page, per_page); leia o documento OpenAPI para cada endpoint.
• Tempo e dinheiro: os valores monetários estão em centavos de USD, a menos que o nome do campo diga o contrário.
• Admin API: o console de administração tem sua própria página System › Admin › API e chaves de administrador (ofw_...) para a administração; elas são separadas da API de clientes descrita aqui.
• Controle de versão: o prefixo de caminho /v1 é estável; novos campos podem ser adicionados às respostas.

Resolução de problemas

Sintoma	Causa	Correção
401 em uma chave nova	Chave de outro domínio, expirada ou digitada com espaços	Crie a chave no domínio que você chama; verifique o cabeçalho Authorization: Bearer vk_....
403 scope_required	Escopo ausente	Edite a chave no portal e adicione o escopo.
401 key_ip_denied ou site_mismatch	Chave restrita a outros IPs ("allowed IPs") ou criada em outro domínio	Adicione o IP do seu servidor aos IPs permitidos da chave ou chame o domínio onde a chave foi criada.
404 em uma VM existente	A VM pertence a outra conta	Use uma chave do proprietário.
400/422 solicitando Idempotency-Key	Operação paga sem o cabeçalho	Adicione Idempotency-Key: <uuid>.
429	Acima do limite	Aguarde; use Retry-After.
/apidoc mostra menos do que o esperado	Módulo desativado	Ative o módulo em License & updates.