Beam apps can be deployed using the rest_api decorator.

from beam import App, Volume, Output

app = App(
        Volume(name="files", path="./files"),

def handler():
runtimeNoThe runtime environment to execute the tasks submitted via the API. It can be a dictionary containing runtime configurations or an instance of the Runtime class. Default is None.
outputsNoA list of outputs or output configurations for handling task results. Default is [].
autoscalingNoAutoscaling configuration. If not provided, autoscaling will not be applied. Default is None.
loaderNoThe function that runs exactly once when the app is first started from cold. Default is None.
callback_urlNoA URL where task execution status updates will be sent. If provided, the system will make a single POST request to this URL with status updates for each task. Default is None.
max_pending_tasksNoThe maximum number of tasks that can be pending in the queue before rejecting new submissions to the API. Default is 100.
keep_warm_secondsNoThe duration in seconds to keep the container warm even if there are no pending tasks. Keeping the queue warm helps to reduce the latency when new tasks arrive via the API. Default is 100.

Testing your function

Beam includes a live-reloading feature that allows you to run your code on the same environment you’ll be running in production.

By default, Beam will sync all the files in your working directory to the remote container. This allows you to use the files you have locally while developing. If you want to prevent some files from getting uploaded, you can create a .beamignore.

In your shell, run beam serve This will:

  1. Spin up a container
  2. Run it on a remote server
  3. Print a cURL request to invoke the API
  4. Stream the logs to your shell

You should keep this terminal window open while developing.

(.venv) user@MacBook demo % beam serve
 i  Using cached image.
 ✓  App initialized.
 i  Uploading files...
 ✓  Container scheduled, logs will appear below.
⠴ Starting container... 5s (Estimated: 3m20s)

================= Call the API =================

curl -X POST '' \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Connection: keep-alive' \
-H 'Authorization: Basic [YOUR_AUTH_TOKEN]' \
-H 'Content-Type: application/json' \
-d '{}'

============= Logs Streamed Below ==============

INFO:     | Starting app...
INFO:     | Loading handler in ''...
INFO:     | Running loader in ''...
INFO:     | Ready for tasks.

Now, head back to your IDE, and change a line of code. Hit save.

If you look closely at the shell running beam serve, you’ll notice the server reloading with your code changes.

You’ll use this workflow anytime you’re developing an app on Beam. Trust us — it makes the development process uniquely fast and painless.

Deploying the API

To deploy the app, enter your shell and run this command from the working directory:

beam deploy

After running this command, you’ll see some logs in the console that show the progress of your deployment.

Calling the API

After deploying the API, you’ll be able to copy a cURL request to hit the API. In your app dashboard, click Call API.

Example Request

curl -X POST --compressed "" \
   -H 'Accept: */*' \
   -H 'Accept-Encoding: gzip, deflate' \
   -H 'Authorization: Basic [YOUR_AUTH_TOKEN]' \
   -H 'Connection: keep-alive' \
   -H 'Content-Type: application/json' \
   -d '{"prompt": "your prompt"}'

Example Response

  "result": {
    "prediction": "{'POSITIVE': 0.9988627433776855, 'NEGATIVE': 0.0011372779263183475}"
  "msg": "",
  "error_msg": ""

Further Reading