API reference: geo-blocking

List geo-blocking policies

GET /api/geo

Needs a Viewer or Admin key.

Replies

Status	Meaning	Body
200	OK	list of `GeoBlockPolicy`

Reply fields

Field	Type	Description
`id`	string	The policy's ID: a single word with no spaces, underscores or quotes, chosen when the policy was created. Always present.
`countries`	list of string	The countries the policy covers, as two-letter ISO codes (stored in upper case). At least one. Always present.
`protocol`	`GeoProtocol`	Which traffic a firewall policy covers: Any, Tcp or Udp. Only used by firewall policies. Always present. One of `Any`, `Tcp`, `Udp`.
`ports`	list of integer	The ports a firewall policy covers, from 1 to 65535. Empty means all ports, which needs protocol Any; a list needs Tcp or Udp. Not used by engine policies. Always present.
`mode`	`GeoMode`	Audit records what the policy would have done without blocking anything; Enforce blocks. Always present. One of `Audit`, `Enforce`.
`layer`	`GeoLayer`	Where the policy is enforced: Firewall drops the traffic at the network layer on any port; DataPlane blocks web requests in the engine. Default Firewall. Always present. One of `Firewall`, `DataPlane`.
`selector`	`GeoSelector`	Block refuses the listed countries; Allow admits only the listed countries and refuses everyone else. Allow needs layer DataPlane. Default Block. Always present. One of `Block`, `Allow`.
`response`	`GeoResponse`	How an engine policy answers: Deny refuses with 403 Forbidden; Challenge gives visitors from the listed countries the browser check (on an Allow policy, requests from elsewhere are refused with 429). Not used by firewall policies. Default Deny. Always present. One of `Deny`, `Challenge`.
`updatedBy`	string	Who last saved the policy. Null if not recorded.
`updatedAt`	date-time	When the policy was last saved. Always present.
`letCertificateChecksThrough`	boolean	For a firewall Block policy: leave ports 80 and 443 to the engine, which blocks the countries there but lets certificate checks through, so certificate issuing and renewal keep working. Default false. Always present.

Let search engines through geo blocking

PUT /api/geo/search-engines

Needs an Admin key.

On by default. The crawlers of Google, Bing, Apple and DuckDuckGo are recognised by the address ranges those search engines publish, and are not blocked by any country policy, so the sites stay in search results. Turn it off to block them like any other visitor from a blocked country.

Request body: GeoSearchEnginesUpdate

Field	Type	Description
`letThrough`	boolean	True to let the crawlers of Google, Bing, Apple and DuckDuckGo through every geo policy (the default), false to block them like any other visitor from a blocked country.

Replies

Status	Meaning	Body
200	OK	`SearchEnginesState`

Reply fields

Field	Type	Description
`letThrough`	boolean	Whether search-engine crawlers are now let through. Always present.

Turn geo-blocking on or off

PUT /api/geo/settings

Needs an Admin key.

The master switch. When it is off no policy is enforced.

Request body: GeoSubsystemUpdate

Field	Type	Description
`enabled`	boolean	True to turn geo-blocking on, false to turn it off. While off no policy is enforced.

Replies

Status	Meaning	Body
200	OK	`SwitchState`

Reply fields

Field	Type	Description
`enabled`	boolean	Whether the switch is now on. Always present.

Get one geo-blocking policy

GET /api/geo/{id}

Needs a Viewer or Admin key.

Parameters

Name	In	Type	Notes
`id`	path	string	Required.

Replies

Status	Meaning	Body
200	OK	`GeoBlockPolicy`
404	Not Found	none

Reply fields

Field	Type	Description
`id`	string	The policy's ID: a single word with no spaces, underscores or quotes, chosen when the policy was created. Always present.
`countries`	list of string	The countries the policy covers, as two-letter ISO codes (stored in upper case). At least one. Always present.
`protocol`	`GeoProtocol`	Which traffic a firewall policy covers: Any, Tcp or Udp. Only used by firewall policies. Always present. One of `Any`, `Tcp`, `Udp`.
`ports`	list of integer	The ports a firewall policy covers, from 1 to 65535. Empty means all ports, which needs protocol Any; a list needs Tcp or Udp. Not used by engine policies. Always present.
`mode`	`GeoMode`	Audit records what the policy would have done without blocking anything; Enforce blocks. Always present. One of `Audit`, `Enforce`.
`layer`	`GeoLayer`	Where the policy is enforced: Firewall drops the traffic at the network layer on any port; DataPlane blocks web requests in the engine. Default Firewall. Always present. One of `Firewall`, `DataPlane`.
`selector`	`GeoSelector`	Block refuses the listed countries; Allow admits only the listed countries and refuses everyone else. Allow needs layer DataPlane. Default Block. Always present. One of `Block`, `Allow`.
`response`	`GeoResponse`	How an engine policy answers: Deny refuses with 403 Forbidden; Challenge gives visitors from the listed countries the browser check (on an Allow policy, requests from elsewhere are refused with 429). Not used by firewall policies. Default Deny. Always present. One of `Deny`, `Challenge`.
`updatedBy`	string	Who last saved the policy. Null if not recorded.
`updatedAt`	date-time	When the policy was last saved. Always present.
`letCertificateChecksThrough`	boolean	For a firewall Block policy: leave ports 80 and 443 to the engine, which blocks the countries there but lets certificate checks through, so certificate issuing and renewal keep working. Default false. Always present.

Create or change a geo-blocking policy

PUT /api/geo/{id}

Needs an Admin key.

countries are two-letter ISO codes. mode Audit only records matching traffic; Enforce blocks it. Set letCertificateChecksThrough so certificate renewals keep working.

Parameters

Name	In	Type	Notes
`id`	path	string	Required.

Request body: GeoPolicyUpdate

Field	Type	Description
`countries`	list of string	The countries the policy covers, as two-letter ISO codes (stored in upper case). At least one. Required.
`protocol`	`GeoProtocol`	Which traffic a firewall policy covers: Any, Tcp or Udp. Only used by firewall policies. Required. One of `Any`, `Tcp`, `Udp`.
`ports`	list of integer	The ports a firewall policy covers, from 1 to 65535. Empty means all ports, which needs protocol Any; a list needs Tcp or Udp. Not used by engine policies. Optional.
`mode`	`GeoMode`	Audit records what the policy would have done without blocking anything; Enforce blocks. Required. One of `Audit`, `Enforce`.
`layer`	`GeoLayer`	Where the policy is enforced: Firewall drops the traffic at the network layer on any port; DataPlane blocks web requests in the engine. Default Firewall. Required. One of `Firewall`, `DataPlane`.
`selector`	`GeoSelector`	Block refuses the listed countries; Allow admits only the listed countries and refuses everyone else. Allow needs layer DataPlane. Default Block. Required. One of `Block`, `Allow`.
`response`	`GeoResponse`	How an engine policy answers: Deny refuses with 403 Forbidden; Challenge gives visitors from the listed countries the browser check (on an Allow policy, requests from elsewhere are refused with 429). Not used by firewall policies. Default Deny. Required. One of `Deny`, `Challenge`.
`letCertificateChecksThrough`	boolean	For a firewall Block policy: leave ports 80 and 443 to the engine, which blocks the countries there but lets certificate checks through, so certificate issuing and renewal keep working. Default false.

Replies

Status	Meaning	Body
200	OK	`GeoBlockPolicy`
400	Bad Request	`ApiError`

Reply fields

Field	Type	Description
`id`	string	The policy's ID: a single word with no spaces, underscores or quotes, chosen when the policy was created. Always present.
`countries`	list of string	The countries the policy covers, as two-letter ISO codes (stored in upper case). At least one. Always present.
`protocol`	`GeoProtocol`	Which traffic a firewall policy covers: Any, Tcp or Udp. Only used by firewall policies. Always present. One of `Any`, `Tcp`, `Udp`.
`ports`	list of integer	The ports a firewall policy covers, from 1 to 65535. Empty means all ports, which needs protocol Any; a list needs Tcp or Udp. Not used by engine policies. Always present.
`mode`	`GeoMode`	Audit records what the policy would have done without blocking anything; Enforce blocks. Always present. One of `Audit`, `Enforce`.
`layer`	`GeoLayer`	Where the policy is enforced: Firewall drops the traffic at the network layer on any port; DataPlane blocks web requests in the engine. Default Firewall. Always present. One of `Firewall`, `DataPlane`.
`selector`	`GeoSelector`	Block refuses the listed countries; Allow admits only the listed countries and refuses everyone else. Allow needs layer DataPlane. Default Block. Always present. One of `Block`, `Allow`.
`response`	`GeoResponse`	How an engine policy answers: Deny refuses with 403 Forbidden; Challenge gives visitors from the listed countries the browser check (on an Allow policy, requests from elsewhere are refused with 429). Not used by firewall policies. Default Deny. Always present. One of `Deny`, `Challenge`.
`updatedBy`	string	Who last saved the policy. Null if not recorded.
`updatedAt`	date-time	When the policy was last saved. Always present.
`letCertificateChecksThrough`	boolean	For a firewall Block policy: leave ports 80 and 443 to the engine, which blocks the countries there but lets certificate checks through, so certificate issuing and renewal keep working. Default false. Always present.

Delete a geo-blocking policy

DELETE /api/geo/{id}

Needs an Admin key.

Parameters

Name	In	Type	Notes
`id`	path	string	Required.

Replies

Status	Meaning	Body
204	No Content	none
404	Not Found	none

Updated 2026-11-02Something unclear or missing? Tell us.