Files
skills/public/modal-web-endpoints.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

719 lines
26 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>modal-web-endpoints</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/modal-web-endpoints.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/modal-web-endpoints">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/modal-web-endpoints.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>modal-web-endpoints</h1><p class="lede">Creating HTTP APIs on Modal</p><h1>Modal Web Endpoints</h1>
<p><strong>Use this skill when:</strong></p>
<ul><li>Creating HTTP APIs on Modal</li><li>Building REST endpoints for ML models</li><li>Integrating FastAPI with Modal functions</li><li>Serving web applications from Modal</li><li>Creating webhooks and API integrations</li></ul>
<h2>Basic Web Endpoints</h2>
<h3>Simple HTTP Endpoint</h3>
<p>Create HTTP endpoints with <code>@app.function()</code></p>
<pre><code class="lang-python">import modal
app = modal.App(&quot;web-app&quot;)
@app.function()
@modal.web_endpoint()
def hello():
return &quot;Hello, World!&quot;
# Access at: https://&lt;username&gt;--web-app-hello.modal.run</code></pre>
<h3>With Path Parameters</h3>
<p>Handle URL parameters:</p>
<pre><code class="lang-python">@app.function()
@modal.web_endpoint()
def greet(name: str):
return f&quot;Hello, {name}!&quot;
# GET /greet?name=Alice
# Returns: &quot;Hello, Alice!&quot;</code></pre>
<h3>Method-Specific Endpoints</h3>
<p>Specify HTTP methods:</p>
<pre><code class="lang-python">@app.function()
@modal.web_endpoint(method=&quot;POST&quot;)
def create_item(item: dict):
# Process item
return {&quot;id&quot;: 123, &quot;status&quot;: &quot;created&quot;}
@app.function()
@modal.web_endpoint(method=&quot;GET&quot;)
def get_item(item_id: int):
return {&quot;id&quot;: item_id, &quot;data&quot;: &quot;...&quot;}</code></pre>
<h2>FastAPI Integration</h2>
<h3>FastAPI App</h3>
<p>Build full REST APIs with FastAPI:</p>
<pre><code class="lang-python">from fastapi import FastAPI
from fastapi.responses import JSONResponse
from pydantic import BaseModel
web_app = FastAPI()
class PredictionRequest(BaseModel):
text: str
max_length: int = 100
class PredictionResponse(BaseModel):
result: str
confidence: float
@web_app.post(&quot;/predict&quot;, response_model=PredictionResponse)
def predict(request: PredictionRequest):
# ML inference logic
result = run_model(request.text, request.max_length)
return PredictionResponse(
result=result,
confidence=0.95
)
@web_app.get(&quot;/health&quot;)
def health():
return {&quot;status&quot;: &quot;healthy&quot;}
# Mount FastAPI app
@app.function()
@modal.asgi_app()
def fastapi_app():
return web_app</code></pre>
<h3>With GPU Model</h3>
<p>Serve ML models via HTTP:</p>
<pre><code class="lang-python">from fastapi import FastAPI
from pydantic import BaseModel
web_app = FastAPI()
class GenerateRequest(BaseModel):
prompt: str
max_tokens: int = 100
temperature: float = 0.7
class GenerateResponse(BaseModel):
text: str
tokens_generated: int
image = modal.Image.debian_slim().uv_pip_install(
&quot;torch==2.1.0&quot;,
&quot;transformers==4.35.0&quot;,
&quot;fastapi==0.104.1&quot;
)
@app.cls(gpu=&quot;l40s&quot;, image=image)
class ModelAPI:
@modal.enter()
def load_model(self):
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
print(&quot;Loading model...&quot;)
self.tokenizer = AutoTokenizer.from_pretrained(&quot;gpt2&quot;)
self.model = AutoModelForCausalLM.from_pretrained(
&quot;gpt2&quot;,
torch_dtype=torch.float16,
device_map=&quot;auto&quot;
)
print(&quot;Model loaded&quot;)
@modal.method()
def generate(
self,
prompt: str,
max_tokens: int,
temperature: float
) -&gt; dict:
import torch
inputs = self.tokenizer(prompt, return_tensors=&quot;pt&quot;).to(&quot;cuda&quot;)
with torch.no_grad():
outputs = self.model.generate(
**inputs,
max_new_tokens=max_tokens,
temperature=temperature,
do_sample=True
)
text = self.tokenizer.decode(outputs[0], skip_special_tokens=True)
return {
&quot;text&quot;: text,
&quot;tokens_generated&quot;: len(outputs[0]) - len(inputs.input_ids[0])
}
@modal.asgi_app()
def web(self):
@web_app.post(&quot;/generate&quot;, response_model=GenerateResponse)
def generate_endpoint(request: GenerateRequest):
result = self.generate(
request.prompt,
request.max_tokens,
request.temperature
)
return GenerateResponse(**result)
@web_app.get(&quot;/health&quot;)
def health():
return {&quot;status&quot;: &quot;ready&quot;}
return web_app</code></pre>
<h2>Request Handling</h2>
<h3>JSON Requests</h3>
<p>Handle JSON payloads:</p>
<pre><code class="lang-python">from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
from typing import List
web_app = FastAPI()
class BatchRequest(BaseModel):
texts: List[str] = Field(..., min_items=1, max_items=100)
model: str = &quot;default&quot;
@web_app.post(&quot;/batch&quot;)
def batch_process(request: BatchRequest):
results = []
for text in request.texts:
result = process(text, model=request.model)
results.append(result)
return {&quot;results&quot;: results, &quot;count&quot;: len(results)}
@app.function()
@modal.asgi_app()
def api():
return web_app</code></pre>
<h3>File Uploads</h3>
<p>Accept file uploads:</p>
<pre><code class="lang-python">from fastapi import FastAPI, File, UploadFile
from fastapi.responses import JSONResponse
import io
web_app = FastAPI()
@web_app.post(&quot;/upload/image&quot;)
async def upload_image(file: UploadFile = File(...)):
# Read file content
contents = await file.read()
# Process image
result = process_image(contents)
return JSONResponse({
&quot;filename&quot;: file.filename,
&quot;size&quot;: len(contents),
&quot;result&quot;: result
})
@web_app.post(&quot;/upload/csv&quot;)
async def upload_csv(file: UploadFile = File(...)):
import pandas as pd
contents = await file.read()
df = pd.read_csv(io.BytesIO(contents))
return {
&quot;rows&quot;: len(df),
&quot;columns&quot;: list(df.columns)
}
@app.function(image=image_with_pandas)
@modal.asgi_app()
def api():
return web_app</code></pre>
<h3>Response Types</h3>
<p>Return various response types:</p>
<pre><code class="lang-python">from fastapi import FastAPI
from fastapi.responses import (
JSONResponse,
PlainTextResponse,
StreamingResponse,
FileResponse
)
web_app = FastAPI()
@web_app.get(&quot;/json&quot;)
def json_response():
return {&quot;status&quot;: &quot;ok&quot;, &quot;data&quot;: [1, 2, 3]}
@web_app.get(&quot;/text&quot;, response_class=PlainTextResponse)
def text_response():
return &quot;Plain text response&quot;
@web_app.get(&quot;/stream&quot;)
def streaming_response():
def generate():
for i in range(100):
yield f&quot;Line {i}\n&quot;
return StreamingResponse(
generate(),
media_type=&quot;text/plain&quot;
)
@web_app.get(&quot;/download&quot;)
def file_download():
# Serve file from volume
return FileResponse(
&quot;/data/report.pdf&quot;,
filename=&quot;report.pdf&quot;,
media_type=&quot;application/pdf&quot;
)
@app.function()
@modal.asgi_app()
def api():
return web_app</code></pre>
<h2>Authentication</h2>
<h3>API Key Authentication</h3>
<p>Implement API key auth:</p>
<pre><code class="lang-python">from fastapi import FastAPI, HTTPException, Header
from typing import Optional
web_app = FastAPI()
# Store in Modal secrets
VALID_API_KEYS = {&quot;key123&quot;, &quot;key456&quot;}
def verify_api_key(x_api_key: str = Header(...)):
if x_api_key not in VALID_API_KEYS:
raise HTTPException(status_code=401, detail=&quot;Invalid API key&quot;)
return x_api_key
@web_app.post(&quot;/protected&quot;)
def protected_endpoint(
data: dict,
api_key: str = Depends(verify_api_key)
):
return {&quot;status&quot;: &quot;authorized&quot;, &quot;data&quot;: data}
@app.function()
@modal.asgi_app()
def api():
return web_app</code></pre>
<h3>Bearer Token</h3>
<p>Use bearer tokens:</p>
<pre><code class="lang-python">from fastapi import FastAPI, HTTPException, Depends
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
web_app = FastAPI()
security = HTTPBearer()
def verify_token(
credentials: HTTPAuthorizationCredentials = Depends(security)
):
token = credentials.credentials
# Validate token (check against database, JWT, etc.)
if not is_valid_token(token):
raise HTTPException(status_code=401, detail=&quot;Invalid token&quot;)
return token
@web_app.post(&quot;/inference&quot;)
def inference(
request: dict,
token: str = Depends(verify_token)
):
return run_inference(request)
@app.function()
@modal.asgi_app()
def api():
return web_app</code></pre>
<h2>CORS Configuration</h2>
<h3>Enable CORS</h3>
<p>Allow cross-origin requests:</p>
<pre><code class="lang-python">from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
web_app = FastAPI()
# Configure CORS
web_app.add_middleware(
CORSMiddleware,
allow_origins=[&quot;https://example.com&quot;], # Specific origins
# allow_origins=[&quot;*&quot;], # Allow all (development only)
allow_credentials=True,
allow_methods=[&quot;*&quot;],
allow_headers=[&quot;*&quot;],
)
@web_app.get(&quot;/data&quot;)
def get_data():
return {&quot;data&quot;: [1, 2, 3]}
@app.function()
@modal.asgi_app()
def api():
return web_app</code></pre>
<h2>Webhooks</h2>
<h3>Receive Webhooks</h3>
<p>Handle incoming webhooks:</p>
<pre><code class="lang-python">from fastapi import FastAPI, Request
import hmac
import hashlib
web_app = FastAPI()
def verify_signature(payload: bytes, signature: str, secret: str) -&gt; bool:
expected = hmac.new(
secret.encode(),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)
@web_app.post(&quot;/webhook/github&quot;)
async def github_webhook(request: Request):
signature = request.headers.get(&quot;X-Hub-Signature-256&quot;, &quot;&quot;)
payload = await request.body()
if not verify_signature(payload, signature, WEBHOOK_SECRET):
raise HTTPException(status_code=401, detail=&quot;Invalid signature&quot;)
data = await request.json()
# Process webhook
process_github_event(data)
return {&quot;status&quot;: &quot;received&quot;}
@app.function()
@modal.asgi_app()
def api():
return web_app</code></pre>
<h2>Error Handling</h2>
<h3>Custom Error Responses</h3>
<p>Handle errors gracefully:</p>
<pre><code class="lang-python">from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse
web_app = FastAPI()
class ModelError(Exception):
def __init__(self, message: str):
self.message = message
@web_app.exception_handler(ModelError)
async def model_error_handler(request: Request, exc: ModelError):
return JSONResponse(
status_code=500,
content={&quot;error&quot;: &quot;Model error&quot;, &quot;detail&quot;: exc.message}
)
@web_app.post(&quot;/predict&quot;)
def predict(text: str):
try:
result = run_model(text)
return {&quot;result&quot;: result}
except ValueError as e:
raise HTTPException(status_code=400, detail=str(e))
except Exception as e:
raise ModelError(str(e))
@app.function()
@modal.asgi_app()
def api():
return web_app</code></pre>
<h2>Rate Limiting</h2>
<h3>Simple Rate Limiting</h3>
<p>Implement basic rate limiting:</p>
<pre><code class="lang-python">from fastapi import FastAPI, HTTPException, Request
from collections import defaultdict
from datetime import datetime, timedelta
web_app = FastAPI()
# In-memory rate limit tracker
request_counts = defaultdict(list)
RATE_LIMIT = 100 # requests per minute
def check_rate_limit(client_ip: str):
now = datetime.now()
minute_ago = now - timedelta(minutes=1)
# Clean old requests
request_counts[client_ip] = [
t for t in request_counts[client_ip]
if t &gt; minute_ago
]
if len(request_counts[client_ip]) &gt;= RATE_LIMIT:
raise HTTPException(status_code=429, detail=&quot;Rate limit exceeded&quot;)
request_counts[client_ip].append(now)
@web_app.post(&quot;/api/endpoint&quot;)
def endpoint(request: Request, data: dict):
check_rate_limit(request.client.host)
return process(data)
@app.function()
@modal.asgi_app()
def api():
return web_app</code></pre>
<h2>Testing Web Endpoints</h2>
<h3>Local Testing</h3>
<p>Test endpoints locally:</p>
<pre><code class="lang-python"># test_api.py
from fastapi.testclient import TestClient
def test_endpoint():
client = TestClient(web_app)
response = client.post(&quot;/predict&quot;, json={&quot;text&quot;: &quot;test&quot;})
assert response.status_code == 200
assert &quot;result&quot; in response.json()</code></pre>
<h2>Anti-Patterns to Avoid</h2>
<p><strong>DON&#x27;T load models on every request:</strong></p>
<pre><code class="lang-python"># ❌ BAD
@web_app.post(&quot;/predict&quot;)
def predict(text: str):
model = load_model() # Slow!
return model(text)
# ✅ GOOD - Use class with @enter
@app.cls(gpu=&quot;l40s&quot;)
class API:
@modal.enter()
def load(self):
self.model = load_model()
@modal.asgi_app()
def web(self):
@web_app.post(&quot;/predict&quot;)
def predict(text: str):
return self.model(text)
return web_app</code></pre>
<p><strong>DON&#x27;T expose endpoints without authentication:</strong></p>
<pre><code class="lang-python"># ❌ BAD - No auth on expensive endpoint
@web_app.post(&quot;/expensive-operation&quot;)
def expensive(data: dict):
return run_expensive_gpu_task(data)
# ✅ GOOD
@web_app.post(&quot;/expensive-operation&quot;)
def expensive(
data: dict,
token: str = Depends(verify_token)
):
return run_expensive_gpu_task(data)</code></pre>
<h2>Related Skills</h2>
<ul><li><strong>modal-functions-basics.md</strong> - Basic Modal patterns</li><li><strong>modal-gpu-workloads.md</strong> - Serving GPU models</li><li><strong>modal-volumes-secrets.md</strong> - Managing secrets for auth</li><li><strong>modal-scheduling.md</strong> - Background processing for webhooks</li></ul>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/modal-web-endpoints.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>