API Routes

Files under pages/api/ are API endpoints. They are plain Python files (not .pyxl) that handle HTTP requests and return JSON or other responses.

Basic API route#

Create pages/api/hello.py. An API module exports an endpoint callable that receives the Starlette Request and returns a response:

from starlette.requests import Request
from starlette.responses import JSONResponse

async def endpoint(request: Request) -> JSONResponse:
    return JSONResponse({"message": "Hello, world!"})

endpoint handles every HTTP method bound to the route. This responds to GET /api/hello:

curl http://localhost:8000/api/hello
# {"message": "Hello, world!"}

HTTP methods#

endpoint receives every method bound to the route. Branch on request.method to handle more than one:

from starlette.requests import Request
from starlette.responses import JSONResponse

async def endpoint(request: Request) -> JSONResponse:
    if request.method in ("GET", "HEAD"):
        users = await fetch_all_users()
        return JSONResponse({"users": users})

    if request.method == "POST":
        body = await request.json()
        user = await create_user(body["name"], body["email"])
        return JSONResponse({"user": user}, status_code=201)

    return JSONResponse({"error": "Method not allowed"}, status_code=405)

Handle HEAD wherever you handle GET. RFC 9110 defines HEAD as identical to GET without a response body, and it is what curl -I, uptime monitors, health probers and link checkers send. Pyxle deliberately lets HEAD through to your handler whenever the route accepts GET — so if your own branch only tests == "GET", the request falls past it to your 405, and the route you advertise as a GET endpoint refuses half the clients that would use it. The server strips the body from a HEAD response for you; returning the full JSONResponse is correct.

For multi-method endpoints with automatic 405 Method Not Allowed handling, use an HTTPEndpoint class (below) — Starlette dispatches each request to the matching get/post/… method and rejects the rest. A class-based endpoint gets the HEAD behaviour above for free: Starlette dispatches HEAD to get unless you define a head method.

Using HTTPEndpoint classes#

For more structure, use Starlette's HTTPEndpoint:

from starlette.endpoints import HTTPEndpoint
from starlette.requests import Request
from starlette.responses import JSONResponse

class Users(HTTPEndpoint):
    async def get(self, request: Request) -> JSONResponse:
        return JSONResponse({"users": []})

    async def post(self, request: Request) -> JSONResponse:
        body = await request.json()
        return JSONResponse({"created": True}, status_code=201)

Sync endpoints and blocking calls#

endpoint can also be a plain synchronous function. Pyxle dispatches sync endpoints through Starlette's threadpool, so a blocking body — a database driver, a sync SDK — occupies a worker thread instead of freezing the event loop:

import sqlite3
import threading

from starlette.requests import Request
from starlette.responses import JSONResponse

_local = threading.local()

def _db() -> sqlite3.Connection:
    # One persistent connection per worker thread: avoids paying the
    # connect/teardown cost (and SQLite WAL churn) on every request.
    conn = getattr(_local, "conn", None)
    if conn is None:
        conn = _local.conn = sqlite3.connect("app.db")
        conn.row_factory = sqlite3.Row
    return conn

def endpoint(request: Request) -> JSONResponse:
    row = _db().execute("SELECT * FROM items WHERE id = ?", (1,)).fetchone()
    return JSONResponse(dict(row) if row else {"error": "not found"})

The same applies to sync get/post/… methods on HTTPEndpoint classes — Starlette threadpools those natively.

Inside an async def endpoint, never call blocking libraries directly — that stalls every request on the worker's event loop. Either make the endpoint sync (above) or wrap the call:

import asyncio

async def endpoint(request: Request) -> JSONResponse:
    rows = await asyncio.to_thread(blocking_query, "SELECT ...")
    return JSONResponse({"rows": rows})

For sub-millisecond calls the sync-endpoint form is usually faster — one threadpool hop per request instead of a hop per wrapped call.

Note: route hooks (and the default API policies) wrap function endpoints. HTTPEndpoint classes are dispatched natively by Starlette and bypass route hooks — the same rationale as WebSocket routes.

WebSocket endpoints#

Since 0.3.0, an API module can export async def websocket(ws) to register a WebSocket handler at the same path. The file can export both endpoint (HTTP) and websocket — they bind to the same URL and Pyxle dispatches based on the protocol of the incoming request.

# pages/api/chat.py
from starlette.websockets import WebSocket

async def websocket(ws: WebSocket) -> None:
    await ws.accept()
    try:
        while True:
            message = await ws.receive_text()
            await ws.send_text(f"echo: {message}")
    except Exception:
        # Client disconnected or socket closed; nothing to clean up.
        pass

Client side:

const socket = new WebSocket(`ws://${location.host}/api/chat`);
socket.onmessage = (event) => console.log(event.data);
socket.onopen = () => socket.send('hello');

You can also export a Starlette WebSocketEndpoint subclass for multi-method dispatch:

from starlette.endpoints import WebSocketEndpoint

class websocket(WebSocketEndpoint):
    encoding = "text"

    async def on_connect(self, ws): await ws.accept()
    async def on_receive(self, ws, data): await ws.send_text(f"echo: {data}")
    async def on_disconnect(self, ws, close_code): pass

Notes:

• WebSocket handlers run outside the HTTP route-hooks pipeline — hooks wrap request-to-response callables and the WS lifecycle doesn't match that shape. Authenticate, rate-limit, and log inside the handler body.
• CSRF doesn't apply to WebSocket upgrades. Enforce your own origin / session checks in on_connect before await ws.accept().

Dynamic API routes#

Use the same bracket syntax as page routes:

pages/api/users/[id].py  -->  /api/users/:id

Where API routes can live#

An api directory can sit anywhere under pages/, not only at the top. A .py file is an endpoint whenever the URL it maps to has an api segment:

pages/api/health.py                     -->  /api/health
pages/s/[slug]/api/v2/summary.json.py   -->  /s/:slug/api/v2/summary.json

The second form is what a compatibility API needs — a shape another vendor's clients already expect, served per tenant. The path is derived from the file path in full, so dynamic segments and a file extension in the URL both work.

Everywhere else, .py files are ignored by routing. That is deliberate: it lets you colocate helpers with the pages that use them without publishing them by accident.

pages/s/[slug]/queries.py   -->  not a route, importable by neighbours

An api directory holds no pages#

A directory named api is server ground, all the way through. One rule decides everything about it, so you can predict all of it from the name:

So a .pyxl page inside one is reported when your project is scanned, by pyxle dev and pyxle build alike:

A directory named 'api' holds endpoints, not pages, but this page sits inside one:
  pages/docs/api/overview.pyxl
An 'api' directory is server ground throughout: its .py files serve URLs, its
client assets (.jsx, .css, .json) are never shipped to the browser, and links to
its URLs are never client-side navigations — so a page there loads without the
components beside it. Rename the directory (for example 'reference/' or
'api-docs/'), or move the page out of it.

Rename the directory — pages/docs/reference/overview.pyxl — and the page and the components beside it work as they do anywhere else.

Only directories count, as everywhere else in this rule: pages/api.pyxl is an ordinary page serving /api.

A page URL may still contain api

The reserved thing is the directory, not the URL shape. A dynamic route fills its segments in from the request, so pages/docs/[...slug].pyxl serves /docs/api/config and pages/s/[slug]/index.pyxl serves /s/api — both are ordinary pages and both render normally.

What such a page gives up is the client router. It reads the rule off the URL, where a page is indistinguishable from an endpoint, and resolves the ambiguity towards safety: a link to an api path is never prefetched on hover — a prefetch would issue a GET at what may be your endpoint, from a mouse movement — and a click performs an ordinary navigation rather than a client-side one. The page loads the way it would with JavaScript disabled. The same rule governs the .md renditions in AI accessibility: links to api paths are left pointing at the endpoint.

Private modules inside an api directory#

Inside an api directory the same colocation is available, marked the way Python already marks it: a leading underscore means private. A file or directory whose name starts with _ is never a route.

pages/api/orders.py            -->  /api/orders
pages/api/_shared.py           -->  not a route
pages/api/__init__.py          -->  not a route
pages/api/_internal/db.py      -->  not a route (the whole directory is private)

A private module is an ordinary Python module — import it from the endpoints beside it exactly as you would any other module in your project:

# pages/api/_shared.py
DEFAULT_LIMIT = 50

def serialise(order):
    return {"id": order.id, "total": order.total}

# pages/api/orders.py
from starlette.responses import JSONResponse

from pages.api._shared import DEFAULT_LIMIT, serialise

async def endpoint(request):
    orders = await fetch_orders(limit=DEFAULT_LIMIT)
    return JSONResponse({"orders": [serialise(order) for order in orders]})

Only the segments at or below the api directory are read this way. Above it the path is a URL, where an underscore is just a character: pages/_admin/api/health.py still serves /_admin/api/health.

Private modules are not routes, so nothing compiles them — pyxle build copies them into dist/ instead, and they deploy with the endpoints that import them (what to ship).

Under pyxle dev they still hot-reload. Saving one prints

✅ Reloaded pages/api/_shared.py in 9 ms

— "reloaded" rather than "rebuilt", because nothing was compiled: the module is dropped from Python's import cache and every endpoint that imports it is re-imported, so the next request runs your new code. If the endpoint cannot be imported afterwards (the helper has a syntax error, or the name it exports was renamed), the previous route table keeps serving and the terminal says so; fix the file and save again.

The rule applies to .py modules in an api directory, not to pages: a .pyxl file named with a leading underscore is a normal route.

A route may end in an extension the browser reads as an asset — .js, .css, .json — and it is still your endpoint. pages/api/embed.js.py serves /api/embed.js, which is how an embeddable widget is usually shipped:

# pages/api/embed.js.py
from starlette.responses import Response

async def endpoint(request):
    return Response(
        "console.log('hello from your app');",
        media_type="application/javascript; charset=utf-8",
        headers={"access-control-allow-origin": "*"},
    )

from starlette.requests import Request
from starlette.responses import JSONResponse

async def endpoint(request: Request) -> JSONResponse:
    user_id = request.path_params["id"]
    user = await fetch_user(user_id)
    if user is None:
        return JSONResponse({"error": "Not found"}, status_code=404)
    return JSONResponse({"user": user})

Reading request bodies#

async def endpoint(request: Request) -> JSONResponse:
    # JSON body
    body = await request.json()

    # Form data
    form = await request.form()

    # Raw body
    raw = await request.body()

    return JSONResponse({"received": True})

Error responses#

Return appropriate HTTP status codes:

async def endpoint(request: Request) -> JSONResponse:
    api_key = request.headers.get("x-api-key")
    if not api_key:
        return JSONResponse({"error": "Missing API key"}, status_code=401)

    data = await fetch_data(api_key)
    if data is None:
        return JSONResponse({"error": "Not found"}, status_code=404)

    return JSONResponse({"data": data})

API routes vs server actions#

¹ CSRF runs app-wide, so a state-changing API request (POST/PUT/PATCH/DELETE) must carry the double-submit token by default — same as any other route. A public webhook or third-party integration that can't send the token must list its path prefix in csrf.exemptPaths. Safe methods (GET/HEAD/OPTIONS) are never checked.

Next steps#

• Add middleware to your routes: Middleware
• Protect routes with CSRF: Security