Developer docs / AI Fabric tutorials
Simple web endpoint
- Web endpoint
Sometimes you don't want a batch job or a notebook: you want a URL. Something you can curl, point a frontend at, or hand to a webhook. AI Fabric web endpoints turn an ordinary Python function into exactly that: an HTTPS endpoint with no web framework, no server process, and no scaling config to babysit.
In this tutorial you'll deploy two tiny endpoints (one that greets a caller by name and a health-check ping) and call them over HTTP. Along the way you'll see how AI Fabric turns a function's return value into a JSON response.
Before you start
Make sure the AI Fabric CLI is installed and authenticated (blade setup). No GPU is needed here, since plain JSON handlers run happily on CPU.
Create the app
Create hello_web.py. Every function needs a container image, so we set a default image on the app to avoid repeating it on each function. fabric/base is the lightweight Python catalog image, ideal for handlers with no heavy dependencies:
import bladekit
app = bladekit.app("hello-web", image="fabric/base")Write your first endpoint
Stack two decorators on a function: @app.function makes it an AI Fabric function, and @app.web_endpoint exposes it over HTTP. The handler receives the parsed request body as its first argument (a dict), and whatever dict it returns becomes the JSON response:
@app.web_endpoint(methods=["POST", "GET"])
@app.function(timeout=30)
def hello(item: dict) -> dict:
name = item.get("name", "world")
return {"message": f"Hello, {name}! From AI Fabric."}A web handler always takes the payload as its first argument, even when it ignores it. For a GET with no body you receive {}.
Add a health check
Endpoints are functions, so a second one is another pair of decorators. Add a read-only ping you can wire to an uptime check:
@app.web_endpoint(methods=["GET"])
@app.function(timeout=30)
def ping(item: dict) -> dict:
return {"ok": True, "platform": "Shadow AI Fabric"}Deploy it
Deploy the app to get a stable HTTPS URL:
blade deploy hello_web.pyAI Fabric prints a base URL for the deployment. Each function is reachable at <URL>/<function-name>, so /hello and /ping. Endpoints are private by default, which is why the calls below carry your AI Fabric token as a bearer credential.
Call your endpoints
POST a name to hello:
curl -X POST <URL>/hello -H 'Authorization: Bearer <FABRIC_TOKEN>' -d '{"name": "Alice"}'{"message": "Hello, Alice! From AI Fabric."}And hit the health check with a plain GET:
curl <URL>/ping -H 'Authorization: Bearer <FABRIC_TOKEN>'{"ok": true, "platform": "Shadow AI Fabric"}That's a production web API in a dozen lines. Functions with @app.web_endpoint scale from zero automatically: when no one is calling they idle down and cost nothing, and when traffic arrives AI Fabric spins up replicas to meet it.
Take it for a spin
Everything above in one file, ready to run.
import bladekit
# Every function needs an image. A default image on the App applies to all of
# them: "fabric/base" is the lightweight Python catalog image (no extra deps
# needed for plain JSON handlers).
app = bladekit.app("hello-web", image="fabric/base")
@app.web_endpoint(methods=["POST", "GET"])
@app.function(timeout=30)
def hello(item: dict) -> dict:
name = item.get("name", "world")
return {"message": f"Hello, {name}! From AI Fabric."}
# A web_endpoint handler always receives the request payload as its first
# argument (parsed JSON body, or {} for a GET with no body), even if unused.
# Note: returning a plain dict sends it as the JSON body, EXCEPT when the dict
# looks like a response envelope (keys "status"/"headers"/"body"/"json"), since AI Fabric
# then treats it as {status, headers, body}. So avoid "status" as a data key.
@app.web_endpoint(methods=["GET"])
@app.function(timeout=30)
def ping(item: dict) -> dict:
return {"ok": True, "platform": "Shadow AI Fabric"}Concepts used: Endpoint, Deployment, Scale-to-zero