Skip to content
Botscent

Flask

Add the server half of Botscent to a Flask app and check the install.

Add the server half of Botscent to a Flask app. The server half runs as a Flask extension and puts the request's own verdict on flask.g.botscent. For the page half, see A script tag, React, Vue or the page for the framework your site uses.

Before you start

You need:

  • A Flask app
  • Python 3.11 or later

1. Install the package

Install botscent from PyPI.

Terminal
pip install botscent

With uv or poetry, use uv add botscent or poetry add botscent.

2. Add the server half

In app.py, pass the app to Botscent.

app.py
from flask import Flask

from botscent.flask import Botscent

app = Flask(__name__)
Botscent(app)

Every view now gets the request's own verdict on flask.g.botscent.

If you use an application factory, call Botscent().init_app(app) in the factory.

By default, the extension does not send the verdict to the page. Flask runs at the origin, and an origin cannot see whether a CDN in front of it stores HTML. The transport=True argument turns the sending on: Botscent(app, transport=True). For the details, see From the server to the page.

Warning: Do not set transport=True unless no shared cache stores your HTML. If a cache stores an agent's page and ignores Cache-Control: no-store, a person can get the agent's Server-Timing entry. If you are not sure, keep the default.

3. Add the page half

The server half reads only what each request declares. The page half finds agents that operate a browser, from inside the page. The page half comes from the npm package botscent.

If Flask renders your HTML, add <script defer src="/botscent.js"></script> to each template. Serve node_modules/botscent/dist/botscent.js at /botscent.js from your own origin. If a frontend framework renders your pages, add the page half there instead. The Quickstart lists every framework.

4. Read the verdict

In a view, read g.botscent.

app.py
from flask import Flask, g, jsonify

from botscent.flask import Botscent

app = Flask(__name__)
Botscent(app)


@app.route("/verdict")
def verdict():
    return jsonify(g.botscent)

A request from curl to /verdict gets a verdict with type set to agent and agent_name set to curl.

To give an agent access, use botscent.is_verified(g.botscent). Use no other field for access. See The trust model.

5. Check the install

Start the app. Then run the check against one of its pages.

Terminal
npx botscent check http://localhost:5000/

The page-script check prints pass, and the check exits with code 0. The server-half check prints unknown, because the transport is off at an origin. If a check fails, see Verify your install.

Next steps