API Reference

Public Package

Cloudstile: Easy-to-use Cloudflare Turnstile client.

This library provides easy-to-use synchronous and asynchronous clients for Cloudflare’s Turnstile service.

Note

For more information, visit Cloudflare Turnstile.

Example

Synchronous usage:

from cloudstile import SyncTurnstile

client = SyncTurnstile(token="your-secret-key")
response = client.validate("token-from-client")
print(response.success)

Asynchronous usage:

from cloudstile import AsyncTurnstile
import asyncio

async def main():
     client = AsyncTurnstile(token="your-secret-key")
     response = await client.validate("token-from-client")
     print(response.success)

asyncio.run(main())

License

MIT License

Copyright (c) 2024-2025 NotAussie

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

class cloudstile.AsyncTurnstile(secret: str)[source]

Bases: BaseTurnstile

Asynchronous implementation of the Cloudflare Turnstile API.

This class extends the BaseTurnstile class to provide an asynchronous method for validating Turnstile tokens using the Cloudflare Turnstile service.

Inherits from:

BaseTurnstile: The abstract base class for Turnstile validation.

async validate(token: str, ip: str | None = None, idempotency_key: str | None = None) → Response[source]

Asynchronously validate a Turnstile token against the Cloudflare service.

Sends a POST request to the Turnstile validation endpoint with the necessary parameters and returns the validation response.

Parameters:

  • token (str) – The Turnstile token to validate.

  • ip (Optional[str]) – The IP address of the user submitting the token.

  • idempotency_key (Optional[str]) – A unique key to ensure idempotent validation requests.

Returns:

The response from the Turnstile validation service.

Return type:

Response

Raises:

  • httpx.HTTPStatusError – If the request fails with a non-2xx status code.

  • httpx.RequestError – If there is an error making the request.

class cloudstile.Response(*, success: bool, hostname: str | None = None, action: str | None = None, cdata: str | None = None, metadata: ~cloudstile.models.response.MetaData = MetaData(ephemeral_id=None, result_with_testing_key=False), challenge_ts: ~datetime.datetime | None = None, error_codes: list[str] = <factory>)[source]

Bases: BaseModel

Represents the response from the Cloudflare Turnstile verification.

Variables:

  • success (bool) – Indicates whether the verification was successful.

  • hostname (Optional[str]) – The hostname of the site where the Turnstile was used.

  • action (Optional[str]) – An optional action name associated with the Turnstile request.

  • cdata (Optional[str]) – An optional custom data field.

  • metadata (MetaData) – Optional metadata related to the Turnstile response.

  • timestamp (Optional[datetime]) – The time when the challenge was solved.

  • error_codes (list[str]) – A list of error codes that may be returned in case of failure.

action: str | None

An optional action name associated with the Turnstile request.

cdata: str | None

An optional custom data field.

error_codes: list[str]

A list of error codes that may be returned in case of failure.

hostname: str | None

The hostname of the site where the Turnstile was used.

metadata: MetaData

Optional metadata related to the Turnstile response.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

success: bool

Indicates whether the verification was successful.

timestamp: datetime | None

The time when the challenge was solved.

class cloudstile.SyncTurnstile(secret: str)[source]

Bases: BaseTurnstile

Synchronous implementation of the Cloudflare Turnstile API.

This class extends the BaseTurnstile class to provide a synchronous method for validating Turnstile tokens using the Cloudflare Turnstile service.

Inherits from:

BaseTurnstile: The abstract base class for Turnstile validation.

validate(token: str, ip: str | None = None, idempotency_key: str | None = None) → Response[source]

Synchronously validate a Turnstile token against the Cloudflare service.

Sends a POST request to the Turnstile validation endpoint with the necessary parameters and returns the validation response.

Parameters:

  • token (str) – The Turnstile token to validate.

  • ip (str, optional) – The IP address of the user submitting the token.

  • idempotency_key (str, optional) – A unique key to ensure the validation request is idempotent.

Returns:

The response from the Turnstile validation service.

Return type:

Response

Raises:

  • httpx.HTTPStatusError – If the request fails with a non-2xx status code.

  • httpx.RequestError – If there is an error making the request.

Response Model

Model definitions for the Cloudflare Turnstile response.

class cloudstile.models.response.MetaData(*, ephemeral_id: str | None = None, result_with_testing_key: bool = False)[source]

Bases: BaseModel

Represents metadata associated with the Turnstile response.

Variables:

  • ephemeral_id (Optional[str]) – An optional identifier for the ephemeral session.

  • result_with_testing_key (bool) – Whether the result is from a testing key.

ephemeral_id: str | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

result_with_testing_key: bool
class cloudstile.models.response.Response(*, success: bool, hostname: str | None = None, action: str | None = None, cdata: str | None = None, metadata: ~cloudstile.models.response.MetaData = MetaData(ephemeral_id=None, result_with_testing_key=False), challenge_ts: ~datetime.datetime | None = None, error_codes: list[str] = <factory>)[source]

Bases: BaseModel

Represents the response from the Cloudflare Turnstile verification.

Variables:

  • success (bool) – Indicates whether the verification was successful.

  • hostname (Optional[str]) – The hostname of the site where the Turnstile was used.

  • action (Optional[str]) – An optional action name associated with the Turnstile request.

  • cdata (Optional[str]) – An optional custom data field.

  • metadata (MetaData) – Optional metadata related to the Turnstile response.

  • timestamp (Optional[datetime]) – The time when the challenge was solved.

  • error_codes (list[str]) – A list of error codes that may be returned in case of failure.

action: str | None

An optional action name associated with the Turnstile request.

cdata: str | None

An optional custom data field.

error_codes: list[str]

A list of error codes that may be returned in case of failure.

hostname: str | None

The hostname of the site where the Turnstile was used.

metadata: MetaData

Optional metadata related to the Turnstile response.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

success: bool

Indicates whether the verification was successful.

timestamp: datetime | None

The time when the challenge was solved.