Endpoints, ASGI, and realtime

api_demo.py

from lazycloud import App
from pydantic import BaseModel

app = App("api_demo")


class WordCount(BaseModel):
    words: int


@app.endpoint(name="count_words", route="/word-count", methods=["POST"])
def count_words(text: str) -> WordCount:
    return WordCount(words=len(text.split()))

uv run lazycloud deploy api_demo:count_words
curl --fail --show-error "<endpoint-url>" \
  -H "Authorization: Bearer $LAZYCLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Run Python on LazyCloud"}'

The deploy prints the URL, and the response is {"words": 4}. LazyCloud maps the JSON request body to the function’s arguments and sends the returned model as JSON; the model also becomes the response schema that typed client packages use. route defaults to / and methods to GET and POST. The token is an access token. Before deploying, the same file previews with lazycloud serve.

Choose the kind

You have	Use
A Python function that answers HTTP requests	`@app.endpoint`
A FastAPI or Starlette app with several routes	`app.asgi(...)`
A WebSocket message handler	`@app.realtime`

Call it from Python

The decorated function is also the client:

from api_demo import count_words

response = count_words.request("Run Python on LazyCloud")
print(response.status_code, response.json())

request() uses your lazycloud login sign-in and goes to a running preview or the deployment. See Where a call goes.

Serve an existing FastAPI app

app.asgi(...) wraps an existing FastAPI or Starlette app. FastAPI needs to be installed locally too, with uv add fastapi, because the CLI imports the file:

from fastapi import FastAPI
from lazycloud import App, Image

app = App("web_app")
api = FastAPI()


@api.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}


service = app.asgi(
    name="service",
    image=Image().add_python_packages(["fastapi"]),
)(api)

uv run lazycloud deploy web_app:service

The container imports the app by its module-level name, so assign it to a variable such as api before wrapping it. An app built inline in the app.asgi(...)(...) call fails at import. request() sends a full request to a route:

from web_app import service

response = service.request(method="GET", path="/health", target="deployed")
print(response.json())

It takes method, path, json, data, headers, and params. An exported client gives each route a typed method instead. ASGI apps take the endpoint options, with concurrent_requests for concurrency and keep_warm_seconds for keep_warm.

Stream or hold a WebSocket

@app.realtime turns a function into a WebSocket handler, and an ASGI app can stream a response; see Streaming.

Require a token

All three require Authorization: Bearer <token> with an access token for the workspace, and the Python clients send your sign-in. authorized=False makes the URL public, leaving access control to your code.

Handle more requests at once

An endpoint starts as one process handling one request at a time. Three settings raise that:

from lazycloud import Autoscaler


@app.endpoint(
    name="word-count-scaled",
    cpu=2,
    workers=2,
    concurrency=8,
    autoscaler=Autoscaler(max_containers=8, tasks_per_container=16),
)
def count_words_scaled(text: str) -> WordCount:
    return WordCount(words=len(text.split()))

Two workers of eight requests make 16 per container, and the autoscaler adds a container per 16 in flight, up to 8. Past max_pending_tasks, 100 by default, requests get 429. Scaling covers choosing the numbers. checkpoint_enabled=True lets new containers restore a warmed worker instead of rerunning on_start.

Serve from your own domain

On Team and Business plans, domain="api.example.com" serves any of the three from a hostname you own. See Custom domains.

Take it offline

uv run lazycloud deployment stop count_words
uv run lazycloud deployment delete count_words

stop takes it offline and keeps the definition, and delete removes it, as does --prune once it’s gone from the code.

Set what every workload shares

Images, resources, and scaling.

Getting started

Core concepts

CLI reference

Examples

Account