This is the Python code behind Integrate SurveyJS with Python, as a FastAPI application you can run example by example. Each example of that page has a page here that runs the real SurveyJS component against these routes, with a short "Try this" list, a live request log, a "What the server stored" panel and the code that just ran. SurveyJS has no backend of its own, so treat these as starting points for your own app.
- SurveyJS demos: app.demos.surveyjs.io
- Backend integration examples on the SurveyJS website: surveyjs.io/backend-integration/examples
- The same examples for other platforms: PHP (Laravel), ASP.NET Core, Node.js (Express), Python (Django), Next.js, Java (Spring Boot)
There is no hosted catalog for this repository yet.
You need Python 3.14 or later. Docker runs the SurveyJS service for the four Run Server-Side Workflows examples, and Node.js 22 or later is only for the browser tests and the CSS build (see Prerequisites).
git clone https://github.com/surveyjs/surveyjs-python-fastapi.git
cd surveyjs-python-fastapi
py -3.15 -m venv .venv # or: python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements-dev.txt
python serve.py # http://127.0.0.1:8000git clone https://github.com/surveyjs/surveyjs-python-fastapi.git
cd surveyjs-python-fastapi
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
python serve.py # http://127.0.0.1:8000python serve.py creates and seeds storage/database.sqlite on its first start. While you work on the code, run python serve.py --reload: uvicorn restarts the app when a file changes. FastAPI developers often type fastapi dev or uvicorn app.main:app instead; both work, but they skip the port check and the build line below.
- Fill Forms Together and Edit Forms Together use WebSocket relays that run inside the app, on its port (
/ws/rooms/<id>and/ws/forms/<id>). There is nothing else to start. - Run Server-Side Workflows (validate, lint, PDF, extract) call the SurveyJS service, SurveyJS Server. Start it with
docker compose up -d surveyjs(it listens onhttp://localhost:3010), setVALIDATE_RESPONSES=trueandLINT_DEFINITIONS=trueinsettings.envto switch Validate Responses and Lint JSON Schemas on, then restart the app. Extract Responses from Documents also needs an AI provider for the service (SURVEYJS_AI_PROVIDERinsettings.env, its key in.env, which you copy from.env.example). - The tests:
python -m pytest: a few seconds, no browser, no network, no service (it is mocked); warnings are errors.python -m scripts.contract: the shared contract test against a fresh database (SERVICE=onwith the service running;--smokefor the smoke test;--steps save-response,dashboardfor some examples).npm ci,npx playwright install chromiumonce, thennpm run test:browser: the shared Playwright specs.python -m scripts.check --complete: the manifest, the regions,shared/and the pins.
python serve.py checks that nothing answers on the port first, then prints the folder it serves and its <branch>@<commit>:
Serving C:\src\surveyjs-python-fastapi (main@4a96b83) on http://127.0.0.1:8000
- Python 3.14 or later (3.15 recommended).
serve.py, the scripts and the tests stop at once on an older one: "Python 3.14 or newer is required (this is 3.13.5)". A missing package shows up as pip's own error atpip install -r requirements.txt. - Docker for the SurveyJS service (
docker compose up -d surveyjs). Without it, the four Run Server-Side Workflows examples answer503"SurveyJS service is not running at http://localhost:3010", and everything else works. - Node.js 22 or later, only for the browser tests and the CSS build.
npm cion an older Node stops with npm's ownEBADENGINEerror (enginesinpackage.json,engine-strictin.npmrc). Running the app never needs Node.
On Windows:
-
Install Python 3.14 or 3.15 from python.org, with
py install 3.15(the Python install manager), or withwinget install Python.Python.3.15. -
pythonmay be the Microsoft Store stub (…\WindowsApps\python.exe), which opens the Store instead of running.py -3.15 -m venv .venvavoids it; inside the activated venv,pythonis the venv's. -
If PowerShell refuses to run
Activate.ps1, allow local scripts once:Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. -
After installing Python or Node, restart your editor, not only its terminal: VS Code's terminals inherit VS Code's environment. To refresh the current PowerShell terminal instead:
$env:Path = [Environment]::GetEnvironmentVariable('Path','Machine') + ';' + [Environment]::GetEnvironmentVariable('Path','User') py --list
-
Don't install
fastapi[standard]oruvicorn[standard]on Python 3.15 for Windows: their extras pull in PyYAML, which has no wheel for it yet and fails to build.requirements.txtpinsuvicornandwebsocketswithout extras, so--reloaduses uvicorn's own file watcher. -
Set a variable for one run like this, or put it in
settings.env:$env:APP_PORT=8001; python serve.py
APP_PORT=8001 python serve.py
On Windows, uvicorn reports a busy port only after the app has started up (and seeded the database), and a second server can bind a port another server listens on while the first keeps answering. So serve.py connects to the port first and stops with "Port 8000 is already in use. Another copy of this app (another checkout or branch?) may be running. Stop it, or set APP_PORT."
Ctrl+C in the terminal (with --reload, the reloader and its worker stop together), then docker compose down for the service. To find a server left running in another terminal or checkout:
Get-NetTCPConnection -LocalPort 8000 -State Listen | Select-Object OwningProcess
Stop-Process -Id <OwningProcess>lsof -i :8000
kill <PID>- Check the branch out in its own folder, with
git worktree add ../surveyjs-python-fastapi-pr <branch>(for a pull request,git fetch origin pull/<number>/head:pr-<number>first) or a second clone. Each checkout has its own.venv,.envandstorage/. - Run one checkout on the default port at a time: stop the other one first, or start the second with
APP_PORT=8001(PowerShell:$env:APP_PORT=8001; python serve.py). - The SurveyJS service is shared:
docker-compose.ymlnames its projectsurveyjs-python, so every checkout manages the same container. - The page says which checkout answered: "Running
<branch>@<commit>" under the catalog's footer buttons and at the end of every example's Description panel.
docker compose up --build # http://127.0.0.1:8000, with the SurveyJS service next to itThe image (Dockerfile) is python:3.15.2-slim with pip install -r requirements.txt (no dev dependencies), runs as a non-root user, and starts with python serve.py. Its environment sets APP_HOST=0.0.0.0, DATA_DIR=/app/storage and FORWARDED_ALLOW_IPS=*; real environment variables win over settings.env, which the image includes. .env isn't copied into the image: docker compose passes the private keys in. It creates and seeds the database on its first start. Its one volume, /app/storage, holds the database, the uploads, the visitor sandboxes and the relay snapshots. Logs go to stderr (docker compose logs app). GET /up answers 200 {"status": "ok"} without touching the database.
One process, many visitors. The image runs one uvicorn worker, on purpose: the relay rooms, the countries cache and the demo's AI counter live in the process's memory, and a second worker would split a room in two. Concurrency comes from async I/O: an extraction that waits up to 120 seconds for the service is an await on the shared httpx2.AsyncClient, so other visitors are served meanwhile, and the def handlers run in FastAPI's thread pool. To scale out to several processes or hosts, move the rooms to a shared store (Redis pub/sub, for example) first; that is out of scope here.
On Windows, Docker Compose 5 can't build a service from a git URL (failed to evaluate path "https://github.com/…"), which the surveyjs service is: it hands the URL to the builder as a file path. Let Compose print the build and give it to the builder yourself, then start without building:
docker compose build --print | docker buildx bake -f -
docker compose up -d --no-buildLinux and macOS (and CI) build with docker compose up --build as above.
serve.py runs uvicorn with proxy_headers=True, trusting X-Forwarded-For and X-Forwarded-Proto from the addresses in FORWARDED_ALLOW_IPS: 127.0.0.1 by default, * in the image. Behind a TLS proxy, the pages' absolute URLs and the relays' wss:// URLs then use the scheme the visitor sees, and the demo's Secure cookies work. In your own production, set FORWARDED_ALLOW_IPS to the proxy's addresses and don't publish the app's port. The relays are on the app's own host and port, so the proxy needs no extra route, only WebSocket upgrades passed through on /ws/. For Traefik, next to your entry point and TLS labels:
services:
app:
labels:
- traefik.http.routers.surveyjs.rule=Host(`example.com`)
- traefik.http.services.surveyjs.loadbalancer.server.port=8000Traefik passes WebSocket upgrades on by default; nginx needs proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade"; on /ws/. RELAY_URL and EDIT_RELAY_URL are only needed when /ws/ is served from another origin. The SurveyJS service stays internal (expose: ["3000"]): only the app calls it.
app/settings.py defines one Settings(BaseSettings) (pydantic-settings), read once at startup from the environment and two files; handlers get it through the SettingsDep dependency, and no other module reads os.environ. settings.env is committed and holds every setting except the private keys. .env is git-ignored and holds only the private keys: SURVEYJS_LICENSE_KEY, AI_API_KEY, OPENAI_API_KEY and ANTHROPIC_API_KEY (copy .env.example to it). Variables set in the environment win, then .env, then settings.env. Switches accept 1, true, on or yes.
| Variable | Default | What it does |
|---|---|---|
APP_PORT, APP_HOST |
8000, 127.0.0.1 |
Where the app listens. |
DATA_DIR |
storage |
The database, uploads, sandboxes and relay snapshots. |
SURVEYJS_SERVICE_URL |
http://localhost:3010 |
The SurveyJS service (docker compose up -d surveyjs). In Compose, the app uses http://surveyjs:3000. |
VALIDATE_RESPONSES |
false |
Validate Responses: app/routes/validate_response.py replaces app/routes/save_response.py. |
LINT_DEFINITIONS |
false |
Lint JSON Schemas: app/routes/lint_definition.py replaces app/routes/creator_load_save.py. |
SURVEYJS_AI_PROVIDER, SURVEYJS_AI_MODEL, SURVEYJS_OLLAMA_BASE_URL, OPENAI_API_KEY, ANTHROPIC_API_KEY |
empty | Extract Responses from Documents: Compose passes them to the service as AI_PROVIDER, AI_MODEL and OLLAMA_BASE_URL (openai, anthropic or ollama). The app reads them only for the page's banner. |
AI_BASE_URL, AI_API_KEY, AI_MODEL |
OpenAI, empty, gpt-4o-mini |
Translate with AI: any OpenAI-compatible /chat/completions endpoint. Without a key, /api/translate answers 501. |
SURVEYJS_LICENSE_KEY |
empty | Calls setLicenseKey() on every page. Without it, the commercial components show a licence banner. The service at its pinned revision ignores it, so server PDFs carry the SurveyJS alert banner. |
RELAY_URL, EDIT_RELAY_URL |
empty | The relays' origin when a proxy serves /ws/ elsewhere, for example wss://example.com. Empty: the page's own origin. |
DEMO_MODE |
false |
The hosted demo's visitor sandboxes (below). |
SURVEYJS_BUILD |
from git | The <branch>@<commit> the pages show as "Running …". Deploys set it themselves. |
SURVEYJS_DOCS, SURVEYJS_GITHUB |
the Python docs page, this repository | Where the pages link. |
FORWARDED_ALLOW_IPS |
127.0.0.1 |
The proxies uvicorn trusts for X-Forwarded-* (see Behind a proxy). |
Each example is two or three files you can read on their own. The full explanation is in the docs.
app/routes/<snake_slug>.py: the example's routes, the server code the docs show, as oneAPIRouter.app/main.pyincludes the routers in the docs' order, and picksvalidate_response.pyorsave_response.py, andlint_definition.pyorcreator_load_save.py, by the switches.fill_together.pyandedit_together.pyare the two relays, as@router.websocketroutes; their rooms are inapp/relay/.shared/client/<slug>.js: the example's client code, a plain ES module, the same file on every platform.templates/examples/<slug>.html: the example's page (Jinja): its description, the "Try this" list and the component.app/integration/: small helpers some routes call, so the code the docs show stays about SurveyJS. They aren't demo code:stored_json.py: theJsonBodydependency,dumps(),insert_response()andput()(see below).surveyjs_service.py:SurveyJsService.post()with its timeouts, the 503 and 504 when the service doesn't answer, and the logging.ai_translation.py: the call to your OpenAI-compatible provider.http.py,ttl_cache.py,file_type.py: the shared HTTP client, the countries cache, and file types by their first bytes.
app/db.py(theDbdependency: one SQLite connection per request),app/auth.py(get_current_user,can(),can_read_file()) andapp/settings.py.
To copy an example, copy its router module and the helpers it imports. The code the docs show is cut from these files between # region sjs:<slug>.server and # endregion (and // #region sjs:<slug>.client in the client modules). surveyjs-integration.json lists every example's files and regions; python -m scripts.check verifies them. SQLAlchemy or SQLModel with a JSON column works just as well as sqlite3; the examples use plain parameterized SQL so that a response stays visibly one JSON document.
shared/ holds what every platform repository uses byte for byte: the client modules, the form definitions, samples and seed data, the page UI (shared/ui/), and the contract, smoke and browser tests. It is a copy of surveyjs-php-laravel's shared/ at the commit in shared/UPSTREAM; python -m scripts.check compares it with shared/SHA256SUMS. Don't edit it here: send a fix to that repository, then copy shared/ again. .gitattributes keeps it in LF on Windows checkouts too, or every hash would fail.
The text in an example's Description panel is the description block of templates/examples/<slug>.html. It can hold several paragraphs, links and other markup:
{% block description %}
<p>Your custom description.</p>
<p>More details with <strong>formatting</strong>.</p>
{% endblock %}The "Try this" list is the try block; the layout is templates/layouts/example.html. The catalog cards use need from surveyjs-integration.json for their "Use when" text. After editing a template, rebuild the stylesheet (see Front end) if you used a Tailwind class no other template uses.
A response, a definition, saved progress and variable presets are each one JSON document, stored as text and returned as stored.
- A raw body, not a Pydantic model. FastAPI developers reach for a model (
data: dict), but a model answers422 {detail}for a non-object, drops the keys it doesn't declare, and may coerce values. The storing handlers takebody: JsonBodyinstead (app/integration/stored_json.py):json.loads(await request.body()), which keeps every key,{},[{}],None,"", whitespace inside strings and1.0. A comment in each handler says why. Translate with AI stores nothing, so it reads a model. NaNis refused. Python'sjson.loadsacceptsNaN,Infinityand-Infinity; JSON doesn't, soJsonBodyrejects them with400 { "error": "The request body is not valid JSON" }, like any other body that isn't JSON.ensure_ascii=False.dumps()stores"naïve — 東京"as it is, not as\uescapes, with compact separators;1.0stays1.0.- Dates are strings.
created_atis ISO 8601 UTC without fractions (2026-11-16T12:00:00Z, written withstrftime), so the dashboard's date filters are string comparisons.isoformat()would write+00:00and microseconds. - Under
/api, every error is{ "error": … }, also FastAPI's own (app/errors.py): a router's 404 and 405 (withAllow), and a bad query parameter (limit=abc) as400.
FastAPI runs def handlers in its thread pool and async def handlers on the event loop. Here:
- Handlers that only touch SQLite are
def. A handler that takesJsonBodyis stilldef: the dependency reads the body on the event loop, then the handler runs in the pool. - Handlers that wait on the network (the SurveyJS service, the AI provider, restcountries.com) or read a form (the uploads) are
async def, and use the sharedhttpx2.AsyncClient. Never use a blocking HTTP client in anasync def: one extraction would stall every visitor. - The short SQLite reads and writes that those
async defhandlers make go through the same synchronous helpers; they take a millisecond. The fill relay's save runs in the thread pool (run_in_threadpool), under the room's lock.
Locally, everyone shares one SQLite database, storage/database.sqlite (delete storage/ to start over).
On a hosted demo (DEMO_MODE=true), each visitor gets a private copy of the seeded database and uploads folder, chosen by a demo_sid cookie, and kept until it has been unused for 24 hours (an hourly task in the app, app/demo/pruner.py). The "Open a second window" link in Fill Forms Together and Edit Forms Together carries that id (?join=), so whoever opens it works in the same copy and the same relay rooms. The demo also caps uploads at 5 MB and the AI examples at 20 calls per visitor per day, counted in this process. None of this is in the example code.
- The pages are Jinja templates (
templates/) through FastAPI'sJinja2Templates, autoescaped. Each page diffs against its Blade source in the reference repository in template syntax only, with the Tailwind class strings unchanged. Inline JSON (the page config,window.FORM_DEFINITION,window.FORM_VARIABLES) goes through Jinja'stojson, which escapes<,>and&, so a</script>in a definition can't end the script; no value from the database is ever| safe. - The site stylesheet is Tailwind CSS v4 without Preflight:
styles/site.cssimportstailwindcss/theme.css(static),tailwindcss/utilities.cssandshared/ui/theme.css.npm run cssbuilds it intostatic/css/site.csswith@tailwindcss/cli. The output is committed, so running the app never needs Node; CI rebuilds it and fails on a difference. The Tailwind standalone binary builds the same file without Node:tailwindcss -i styles/site.css -o static/css/site.css --minify. - The client code is the shared ES modules in
shared/client/andshared/ui/, loaded unchanged with<script type="module">and an import map (app/frontend.py). No Python package carries SurveyJS's browser builds, so every specifier points to unpkg: the SurveyJS packages at the version inshared/surveyjs-version.json(fesm/*.mjs), andchart.js,@kurkle/color,lodash-esand highlight.js at pinned versions. There is no bundler. - To self-host them, copy each package's
fesm/files (and the CSS the pages load) intostatic/vendor/<package>@<version>/and pointUNPKGinapp/frontend.pyat/static/vendor. Don't mix the script-tag builds (survey.core.jsand friends) with the ES modules on one page: they would load SurveyJS twice. - Python reads MIME types from the Windows registry, where
.jsor.mjscan betext/plain, and browsers refuse to run a module served that way.app/main.pyregisterstext/javascript(and the SVG, font and CSS types) before mountingshared/andstatic/. - The forms use the SurveyJS Tailwind adapter (
survey-core/themes/adapters/tailwind4.css). No page callsapplyTheme(): its inline styles would override the adapter.
The routers only use the request, the database and the response, so they port in a few lines. Save Responses as a Flask view, reading the raw body for the same reason:
@app.post("/api/responses")
def save_response():
body = json.loads(request.get_data()) # not request.get_json(): the same raw body, parsed once
if not isinstance(body, dict) or "formId" not in body or "data" not in body:
return jsonify(error="Expected { formId, data }"), 400
created_at = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
cursor = db.execute("INSERT INTO responses (form_id, data, created_at) VALUES (?, ?, ?)",
(body["formId"], json.dumps(body["data"], ensure_ascii=False), created_at))
return jsonify(id=cursor.lastrowid), 201Only the request and response wrappers change. Django has its own SurveyJS example repository: surveyjs-python-django.
These examples must not be used as a real service as they are. They don't cover authentication, authorization, user management, access levels and other security aspects of a real survey service. The places where real checks go are marked:
can(user, "edit-forms")andcan_read_file(user, file)inapp/auth.py: who may save definitions and presets, and who may read an uploaded file.get_current_userinapp/auth.py: the demo version reads ademo_usercookie; your app reads its session there, or uses anOAuth2PasswordBearer/ JWT dependency. The relays take the same dependency.
When you copy an example into your app, leave out the demo-only code: the app/demo/ folder (and its lines in app/main.py), app/pages.py, app/frontend.py, app/relay/room_key.py's sandbox keys, templates/, shared/ui/ (the page frame, its tabs and highlighting, the fonts and site images) and shared/client/host.js (its mountSurvey() is one line: renderSurvey(survey, element) from survey-js-ui).
The code in this repository is available under the MIT licence.
The examples use SurveyJS Form Library, which is MIT-licensed as well. The examples marked "Commercial" in the Licence column above also use SurveyJS Survey Creator, Dashboard or PDF Generator, which are commercial products. You can integrate them and evaluate their functionality without a licence. Production use requires a developer licence for each developer who works with the SurveyJS APIs or implements the integration. See the SurveyJS Licensing FAQ and the End-User License Agreement.