API

Everything you set in the dashboard for a site is one document: mode, bot score bands, firewall rules, rate limits, gates, waiting room, headers and policy. With the account key you read that document, change it and write it back. The rules of a site can then live in your repository, go through review and be applied from a pipeline. The API works on every plan.

The account key

One key per account, for every site in it. Create it in Account › API key. It is shown once, so store it then. Making a new key stops the old one within a minute, so update your scripts first. See Account, plans and security.

Every call carries two things:

• the key, as Authorization: Bearer your_api_key;
• the site id, in the X-Tenant-ID header or as ?tenant_id= in the address.

Each IP address can make 60 calls a minute. AI assistants use the same key through MCP.

Read the rules

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 returns JSON by default. Ask for YAML with ?format=yaml or Accept: application/yaml. The YAML lists one item per line, so a change reads well in a diff.

Write the rules

# check without saving
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"
# apply: the same call without ?dry_run=1

PUT /api/protection takes JSON or YAML, by the Content-Type, up to 256 KB. It replaces the rules of the site:

• a section missing from the document goes back to its default;
• a list in the document replaces the whole list;
• an unknown setting is an error, so a typo does not pass silently.

With ?dry_run=1 Qlyne checks the document and saves nothing. The answer is 200 with valid, saved and protection, the rules as they would be saved. Without it, the connector picks up the new rules within a minute.

In a pipeline, run the call with ?dry_run=1 on pull requests and the real one on merge. The dashboard checks with the same rules, so a document the API accepts is one the screen accepts.

Main fields

Field	What it sets	Page
mode	observe or enforce, for the whole site	Events and reports
under_attack	Under attack mode, a challenge on every page	Bot Management
challenge	Challenged routes, difficulty, how long a pass lasts	Bot Management
bot_score	Bot score on or off, and what to do in each band	Bot Management
block_ai, trap, tor, reputation	AI crawlers, scanner trap, Tor exit nodes, shared reputation	Bot Management
waf, rules, ip, rate_limits	Managed rules, your own rules, IP lists, rate limits	WAF & Firewall
login, forms	Login protection and form protection	Account Protection
gates	Access gates	Access
queue_routes	Routes that go through the waiting room	Waiting Room
headers, csp, page_cache, consent	Security headers, Content Security Policy, page cache, consent banner	Page Shield
signals	Whether the connector sends the Qlyne-* headers to your app	Signals to your app

A Free site accepts the paid fields, but the connector does not apply them: see Plans. Gate passwords never come back in the document. It carries only a hash, so the document you read can be sent back as it is.

Metrics

GET /api/metrics, with the same key and site, returns the Prometheus metrics of your account only: decisions by action, waiting room sizes and the rest. Point your own Prometheus or Grafana at it. When the Qlyne server does not answer, the call returns 503 with a line of text; try again in a minute.

Purge the page cache

With the page cache on the Qlyne proxy or hosted, you purge it on your own site’s address. This call uses the connector secret, not the account key, so keep it on your server:

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

The body takes {"all": true}, {"paths": [...]} (by prefix) or {"tags": [...]}. The answer is {"purged": n}, the number of copies cleared. A call without the right secret gets 404. Tags and the dashboard button are under Purge.

Errors

Errors come back as JSON. The error field holds a stable code; decide on it, since the text next to it can change.

HTTP	error	When
400	TENANT_REQUIRED	The site id is missing.
400	INVALID_BODY	The body is not valid JSON or YAML, or is not an object. message says what failed.
401	UNAUTHORIZED	The key is missing or wrong, or the site is not in this account.
403	TENANT_BLOCKED	The site is blocked or inactive.
413	TOO_LARGE	The document is over 256 KB.
422	INVALID_RULES	A field failed. errors maps each field to its message, like challenge.routes or rules.0.conditions.1.values.

More than 60 calls in a minute from one IP address get 429; wait for the minute to turn.

Signals to your app

The connector also tells your app what it saw about each request in Qlyne-* headers, such as Qlyne-Bot-Score and Qlyne-Verified-Bot. Your code reads them like any other header. The full list is under Signals to your app.