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:

hello_web.py
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:

Python
@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:

Python
@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:

Terminal
blade deploy hello_web.py

AI 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:

Terminal
curl -X POST <URL>/hello -H 'Authorization: Bearer <FABRIC_TOKEN>' -d '{"name": "Alice"}'

Output
{"message": "Hello, Alice! From AI Fabric."}

And hit the health check with a plain GET:

Terminal
curl <URL>/ping -H 'Authorization: Bearer <FABRIC_TOKEN>'

Output
{"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.

hello_web.py
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

Contact the team

Loading the form…