Routing¶
Nine kinds of route. Seven never enter the Python interpreter at request time; Python handlers and behaviours do. Flows are covered in Orchestration and behaviours in Behaviours; this page covers the rest.
Choosing between them is the main design decision in a WebCortex app, so this page covers each one and when to reach for it.
Static¶
A constant response, serialised once at boot.
app.static("GET", "/health/ready", {"ready": True})
app.static("GET", "/version", {"version": "1.2.3"}, status=200)
Use for: readiness probes, feature flags, service discovery, anything that does not change between deploys.
Query¶
Binds a route directly to SQL. The fastest kind of route with real data.
app.query(
"GET", "/tickets/by-status/{status}",
"SELECT * FROM tickets WHERE status = ? ORDER BY priority DESC",
params=["status"],
returns="many",
tool=True,
tool_name="tickets_by_status",
scopes=["read"],
)
params names the values bound to each ?, in order. Each is resolved
from the path, then the query string, then the JSON body — so a caller (or a
model) can supply them wherever is natural.
With no input_schema=, the route advertises one derived from params (since
2.9; before, MCP clients, OpenAPI and agents saw an empty object): one property
per name, @principal left out, required when it is a {name} in the path,
typed from a resource field of the same name when the SQL names that resource's
table, otherwise a string (or any JSON value in a POST, PUT or PATCH
body). The description defaults to summary, else the first line of the SQL.
An explicit input_schema= still wins.
returns controls the shape:
| Value | Response |
|---|---|
"many" |
JSON array of row objects |
"one" |
Single object, or 404 when nothing matches |
"affected" |
{"affected": n, "last_insert_id": m}; m is null unless the statement inserted a row |
Parameters are data, never syntax
Values are always bound, never interpolated. ?limit=1 OR 1=1 reaches
SQLite as the string "1 OR 1=1" bound to a LIMIT — a type error, which
returns 400 and is the proof that parameterisation held.
The SQL text itself must come from your source, never from a request.
Resource¶
Generates a full CRUD surface. The Django-admin-scale shortcut, except the endpoints are executed by Rust rather than an ORM.
app.resource(
"tickets",
fields={"id": int, "subject": str, "body": str, "priority": int},
tools=True,
read_scopes=["read"],
write_scopes=["write"],
)
Five routes, five tools, zero interpreter involvement:
| Method | Path | Tool name | Guarded by |
|---|---|---|---|
| GET | /tickets |
list_tickets |
read_scopes |
| GET | /tickets/{id} |
get_tickets |
read_scopes |
| POST | /tickets |
create_tickets |
write_scopes |
| PUT | /tickets/{id} |
update_tickets |
write_scopes |
| DELETE | /tickets/{id} |
delete_tickets |
write_scopes |
What the generated routes accept¶
Each route advertises an input schema, and since 2.9 a body that breaks it is
refused with 422 (WC206, naming the field) before any SQL runs: a missing
required field, a key the resource does not declare, or a value of the wrong
type. POST needs every field except a generated integer key. PUT replaces
the whole row, so it needs every writable field too; there is no partial
update (PATCH) yet, so send the row back with your change:
GET /tickets is newest first (by primary key, descending). limit defaults
to 50 and is clamped to 1–1000; offset defaults to 0 and is never negative.
A bool field reads back as true/false, not SQLite's 1/0.
Options¶
| Argument | Default | Notes |
|---|---|---|
table |
name |
Underlying table, if it differs |
primary_key |
"id" |
Must appear in fields |
tools |
False |
Expose all five as agent tools |
read_scopes |
— | Guards list + get |
write_scopes |
— | Guards create + update + delete |
scopes |
— | Shorthand setting both |
create_table |
True |
Emit CREATE TABLE IF NOT EXISTS |
Split reads from writes
Reads and writes almost never warrant the same scope. Setting only scopes
gives an agent that can read your data the ability to delete it. Leaving all
three unset makes the resource fully public — webcortex security reports
that, and webcortex dev warns on boot.
Schema handling¶
create_table=True emits CREATE TABLE IF NOT EXISTS and nothing more.
$ webcortex sql
CREATE TABLE IF NOT EXISTS tickets (
id INTEGER PRIMARY KEY AUTOINCREMENT,
subject TEXT,
body TEXT,
priority INTEGER
);
There is deliberately no auto-migration. Silently issuing ALTER TABLE
because a Python dict changed is how frameworks destroy production data.
Migrations must be versioned, reviewable, and explicit.
Python handlers¶
For logic that is not expressible as data.
@app.get("/tickets/{id}/summary", tool=True, scopes=["read"])
def summarize(id: int, style: str = "short") -> dict:
"""Summarise a ticket."""
if style not in ("short", "long"):
raise HTTPError(422, "style must be 'short' or 'long'")
return {"id": id, "style": style, "summary": f"Ticket #{id}"}
Decorators: @app.get, @app.post, @app.put, @app.patch, @app.delete,
or @app.route(method, path).
Two handler styles¶
@app.get("/tickets/{id}")
def get_ticket(id: int, verbose: bool = False) -> dict:
return {"id": id, "verbose": verbose}
Parameters are bound by name and converted to their annotations. The signature becomes the tool schema, so an agent gets a precise contract for free.
A conversion is not a validation. A value that cannot be converted reaches
the handler unchanged: /tickets/abc calls get_ticket with
id == "abc", and verbose=maybe arrives as the string "maybe". The
same holds for a dataclass body parameter: a body with a key the class does
not declare, or without a required field, arrives as the raw dict, and a
field that cannot be converted keeps the value that was sent. Check what you
rely on, raise HTTPError(422, ...) when it is wrong, and never put a
parameter into SQL, a shell command or a file path on the strength of its
annotation. A model's tool call is bound the same way, so the same applies
when an agent is the caller.
from webcortex import Request
@app.post("/webhook")
def webhook(req: Request) -> dict:
signature = req.headers.get("x-signature", "")
payload = req.json()
return {"received": len(req.body)}
Name the parameter req or request, or annotate it Request. Use when
you need headers, the raw body, or the caller's identity.
The Request object¶
| Member | Type | Notes |
|---|---|---|
req.method |
str |
|
req.path |
str |
|
req.params |
dict |
Path parameters |
req.query |
dict |
Query string; a repeated key keeps its last value |
req.query_list(name) |
list[str] |
Every value of a query key, in order (?tag=a&tag=b) |
req.headers |
dict |
Lower-cased keys |
req.body |
bytes |
Raw |
req.json() |
Any |
Parsed and cached. A body that is not JSON, or (since 2.9) is nested too deeply to parse, raises a ValueError that answers 400 WC205 if you let it propagate |
req.user |
dict |
{id, authenticated, scopes} |
req.scopes |
list |
Convenience |
req.get(name, default) |
Any |
Path → query → body |
Returning¶
return {"ok": True} # 200 JSON
return None # 204 No Content
return Response({"created": 1}, status=201) # explicit status
return Response(body, headers={"x-trace": "abc"})
raise HTTPError(404, "not found") # clean error response
Dataclasses, Pydantic models, and anything with model_dump/dict/_asdict
serialise automatically.
Exceptions are safe by default
An unhandled exception is logged in full and returns a bare
{"error": {"status": 500, "message": "internal error"}}. Tracebacks are
never sent to clients — they disclose file paths, dependency versions, and
code structure. Set WEBCORTEX_DEBUG_ERRORS=1 to see them in responses
during development.
Async handlers¶
Async handlers run on worker threads each owning an event loop; sync handlers go to a separate thread pool so a blocking call cannot stall a shared loop.
Pages¶
Server-rendered HTML, rendered in Rust with a Jinja2-compatible engine.
Every template also receives:
{{ request.path }} {{ request.params }} {{ request.query }}
{{ user.id }} {{ user.authenticated }} {{ user.scopes }}
.html, .htm, .xhtml, .xml and .svg templates autoescape (also as
page.html.j2), and since 2.9 the template's extension also sets the response's
content type, so a .txt or .json page is no longer served as HTML. Template
inheritance,
{% extends %}, {% block %}, and filters all work. See
Frontend.
Static files¶
Serves a directory with ETags and conditional 304 responses. The path gets a
wildcard segment automatically if you omit one.
Refused by the runtime: path traversal in any encoding (double-encoded,
overlong UTF-8, ..;/, NUL truncation), symlinks pointing outside the root, and
dotfiles — so a stray .env or .git under a static root cannot leak.
Since 2.9 static files are streamed from disk rather than read into memory whole, with the same ETags and traversal checks.
Proxy¶
The gateway primitive.
app.upstream("billing", base_url="https://api.billing.internal",
bearer_env="BILLING_TOKEN", timeout_ms=8000)
app.proxy("GET", "/billing/invoices/{id}",
upstream="billing", rewrite="/v2/invoices/{id}",
tool=True, scopes=["billing:read"])
Credentials are named, not embedded — bearer_env is resolved from the
environment at boot, so the manifest stays safe to log and diff.
The proxy forwards only content-type and accept. It never forwards the
caller's Authorization header: the upstream sees your credentials, not
whatever the client happened to send.
Redirects are relayed, never followed. Since 2.9 a 3xx from the upstream goes
back to the caller with its Location header (rewritten when it points inside
the upstream's base_url), and the proxy sends no Referer. Following it would
have sent your upstream credentials to whatever host the redirect named.
Path parameters are attacker-controlled
A parameter containing .. or / is rejected with 400 before the
request is issued, checked raw and after double percent-decoding. Without
this, GET /billing/.. reached / on the upstream — turning a narrow proxy
into a general request-forgery primitive against an internal service.
Agent¶
app.agent("assistant", model="claude-opus-5",
tools=["list_tickets"], scopes=["read"],
expose_scopes=["read"], expose_at="/ask")
See Agents.
Cross-cutting options¶
Every route-declaring function accepts:
| Option | Default | Purpose |
|---|---|---|
tool |
False |
Expose as an agent tool |
tool_name |
derived | Override the generated name |
scopes |
() |
Scopes required to reach it at all |
approval |
"never" |
"required" gates agent, behaviour and MCP calls (not a direct HTTP call) |
read_only |
by method | MCP hint |
idempotent |
by method | MCP hint |
summary |
docstring |
Derived tool names¶
Omit tool_name and it is generated from method and path:
| Route | Tool name |
|---|---|
GET /users |
get_users |
POST /users |
create_users |
GET /users/{id} |
get_users_by_id |
DELETE /a/b/{c} |
delete_a_b_by_c |
Two routes claiming the same name is a boot error, not an ambiguous tool call.
How a request path is matched¶
A request path is normalised before it is matched (since 2.9): percent-encoded
unreserved characters are decoded and hex is upper-cased, so /p%69ng is
/ping, and a route with a non-ASCII literal segment (/café/{n}) answers
whether the client sends raw UTF-8, %C3%A9 or %c3%a9. %2F, %5C and
%25 stay encoded, so an encoded separator never splits a segment, and a
parameter is decoded exactly once: /echo/%4%31 binds "%41", the single
decoding of what was sent (2.9.0 decoded it again to "A", so %2%45%2%45
reached a handler as ..). A parameter that is not UTF-8 once decoded
(/echo/%FF) reaches the handler exactly as the client sent it, escapes and
case included. Query values are different: an undecodable byte there becomes
U+FFFD.