Beam allows you to deploy web endpoints that can be invoked via HTTP requests. These endpoints can be used to run arbitrary code. For instance, you could perform inference using one of our GPUs, or just run a simple function that multiplies two numbers.

from beam import endpoint

@endpoint(
    cpu=1.0,
    memory=128,
)
def multiply(**inputs):
    result = inputs["x"] * 2
    return {"result": result}

Endpoints vs. Task Queues

Endpoints are RESTful APIs, designed for synchronous tasks that can complete in 180 seconds or less. For longer running tasks, you’ll want to use an asynchronous task_queue instead.

​
Launch a Preview Environment (Optional)

beam serve monitors changes in your local file system, live-reloads the remote environment as you work, and forwards remote container logs to your local shell.

Serve is great for prototyping. You can develop in a containerized cloud environment in real-time, with adjustable CPU, memory, GPU resources.

It’s also great for testing an app before deploying it. Served functions are orchestrated identically to deployments, which means you can test your Beam workflow end-to-end before deploying.

To start an ephemeral serve session, you’ll use the serve command:

beam serve [FILE.PY]:[ENTRY-POINT]

For example, to start a session for the multiply function in app.py, run:

beam serve app.py:multiply

To end the session, you can use Ctrl + C in the terminal where you started the session.

Serve sessions end automatically after 10 minutes of inactivity. The entire duration of the session is counted towards billable usage, even if the session is not receiving requests.

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.

​
Deploying the Endpoint

When you’re finished with prototyping and want to make a persistent deployment of the endpoint, enter your shell and run this command from the working directory:

beam deploy [FILE.PY]:[ENTRY-POINT]

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

The container handling the endpoint will spin down after 180 seconds of inactivity by default, or customized with the keep_warm_seconds parameter. The container will be billed for the time it is active and handling requests.

​
Calling the Endpoint

After deploying the API, you’ll be able to make a web request to hit the API with cURL or libraries of your choice.

Open another terminal window to invoke the API:

​
Example Request

curl -X POST 'https://multiply-712408b-v1.app.beam.cloud' \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Connection: keep-alive' \
-H 'Authorization: Bearer [YOUR_AUTH_TOKEN]' \
-H 'Content-Type: application/json' \
-d '{"x": 10}'

​
Example Response

{
  "result": 20
}

To send other payloads other than JSON, you can encode the data as a base64 string and include it in the JSON payload, or upload the file to a S3 bucket and mount the bucket to the endpoint.

For more detailed examples, checkout the Sending File Payloads documentation.