API

Tudo o que você ajusta no painel para um site é um documento só: modo, faixas de nota de robô, regras do firewall, limites de requisições, portões, sala de espera, cabeçalhos e política. Com a chave da conta você lê esse documento, muda e grava de volta. Assim as regras de um site podem viver no seu repositório, passar por revisão e ser aplicadas a partir de um pipeline. A API funciona em todos os planos.

A chave da conta

Uma chave por conta, para todos os sites dela. Crie em Conta › Chave da API. Ela aparece uma vez, então guarde na hora. Gerar uma chave nova faz a antiga parar de valer em até um minuto, então atualize os seus scripts antes. Veja Conta, planos e segurança.

Toda chamada leva duas coisas:

a chave, como Authorization: Bearer your_api_key;
o id do site, no cabeçalho X-Tenant-ID ou como ?tenant_id= no endereço.

Cada endereço IP pode fazer 60 chamadas por minuto. Assistentes de IA usam a mesma chave pelo MCP.

Ler as regras

curl -H "Authorization: Bearer $QLYNE_API_KEY" -H "X-Tenant-ID: your_site_id" \
  "https://app.qlyne.com/api/protection?format=yaml" > qlyne.yaml

GET /api/protection devolve JSON por padrão. Peça YAML com ?format=yaml ou Accept: application/yaml. O YAML põe um item por linha, então uma mudança se lê bem num diff.

Gravar as regras

# confere sem salvar
curl -X PUT -H "Authorization: Bearer $QLYNE_API_KEY" -H "X-Tenant-ID: your_site_id" \
  -H "Content-Type: application/yaml" --data-binary @qlyne.yaml \
  "https://app.qlyne.com/api/protection?dry_run=1"
# aplica: a mesma chamada sem ?dry_run=1

PUT /api/protection aceita JSON ou YAML, pelo Content-Type, até 256 KB. Ele troca as regras do site:

uma seção que falta no documento volta ao padrão;
uma lista no documento substitui a lista inteira;
uma configuração desconhecida é erro, então um erro de digitação não passa calado.

Com ?dry_run=1 o Qlyne confere o documento e não salva nada. A resposta é 200 com valid, saved e protection, as regras como seriam salvas. Sem ele, o conector recebe as regras novas em até um minuto.

Num pipeline, rode a chamada com ?dry_run=1 nos pull requests e a de verdade no merge. O painel confere com as mesmas regras, então um documento que a API aceita é um que a tela aceita.

Campos principais

Campo	O que ajusta	Página
`mode`	`observe` ou `enforce`, para o site inteiro	Eventos e relatórios
`under_attack`	Modo sob ataque, um desafio em toda página	Bot Management
`challenge`	Rotas desafiadas, dificuldade, quanto tempo dura a liberação	Bot Management
`bot_score`	Nota de robô ligada ou não, e o que fazer em cada faixa	Bot Management
`block_ai`, `trap`, `tor`, `reputation`	Robôs de IA, armadilha de scanner, saídas do Tor, reputação compartilhada	Bot Management
`waf`, `rules`, `ip`, `rate_limits`	Regras gerenciadas, as suas regras, listas de IP, limites de requisições	WAF & Firewall
`login`, `forms`	Proteção de login e de formulários	Account Protection
`gates`	Portões do Access	Access
`queue_routes`	Rotas que passam pela sala de espera	Waiting Room
`headers`, `csp`, `page_cache`, `consent`	Cabeçalhos de segurança, Content Security Policy, cache de página, banner de consentimento	Page Shield
`signals`	Se o conector manda os cabeçalhos `Qlyne-*` ao seu app	Sinais para o seu app

Um site no Free aceita os campos pagos, mas o conector não os aplica: veja Planos. As senhas dos portões nunca voltam no documento. Ele leva só um hash, então o documento que você lê pode ser mandado de volta do jeito que está.

Métricas

GET /api/metrics, com a mesma chave e o mesmo site, devolve as métricas Prometheus só da sua conta: decisões por ação, tamanho das salas de espera e o resto. Aponte o seu Prometheus ou Grafana para ele. Quando o servidor do Qlyne não responde, a chamada devolve 503 com uma linha de texto; tente de novo em um minuto.

Invalidar o cache de página

Com o cache de página no proxy do Qlyne ou no hospedado, você invalida pelo endereço do seu próprio site. Esta chamada usa o segredo do conector, não a chave da conta, então mantenha no seu servidor:

curl -X POST -H "Authorization: Bearer your_connector_secret" \
  -H "Content-Type: application/json" -d '{"paths": ["/blog/"]}' \
  "https://example.com/__qlyne/purge"

O corpo aceita {"all": true}, {"paths": [...]} (por prefixo) ou {"tags": [...]}. A resposta é {"purged": n}, quantas cópias saíram. Uma chamada sem o segredo certo recebe 404. As tags e o botão do painel estão em Invalidação.

Erros

Os erros voltam em JSON. O campo error traz um código estável; decida por ele, porque o texto ao lado pode mudar.

HTTP	`error`	Quando
400	`TENANT_REQUIRED`	Falta o id do site.
400	`INVALID_BODY`	O corpo não é JSON nem YAML válido, ou não é um objeto. `message` diz o que falhou.
401	`UNAUTHORIZED`	A chave falta ou está errada, ou o site não é desta conta.
403	`TENANT_BLOCKED`	O site está bloqueado ou inativo.
413	`TOO_LARGE`	O documento passa de 256 KB.
422	`INVALID_RULES`	Um campo falhou. `errors` liga cada campo à mensagem dele, como `challenge.routes` ou `rules.0.conditions.1.values`.

Mais de 60 chamadas num minuto do mesmo endereço IP recebem 429; espere o minuto virar.

Sinais para o seu app

O conector também conta ao seu app o que viu em cada pedido nos cabeçalhos Qlyne-*, como Qlyne-Bot-Score e Qlyne-Verified-Bot. O seu código lê esses cabeçalhos como qualquer outro. A lista inteira está em Sinais para o seu app.