serve

The serve command starts a BAML-over-HTTP API server that exposes your BAML functions via HTTP endpoints. This feature allows you to interact with your BAML functions through a RESTful API interface.

Usage

baml-cli serve [OPTIONS]

If you’re actively developing, you can use the dev command to include hot-reload functionality:

baml-cli dev [OPTIONS]

Options

Option	Description	Default
`--from <PATH>`	Path to the `baml_src` directory	`./baml_src`
`--port <PORT>`	Port to expose BAML on	`2024`
`--no-version-check`	Generate `baml_client` without checking for version mismatch	`false`

Description

The serve command performs the following actions:

Exposes BAML functions as HTTP endpoints on the specified port.
Provides authentication middleware for secure access.

Endpoints

POST /call/:function_name: Call a BAML function

curl

$ curl \
>   -X POST \
>   "http://localhost:2024/call/MyFunctionName" \
>   -H "Content-Type: application/json" \
>   -d '{"arg1": "value1", "arg2": "value2"}'

POST /stream/:function_name: Stream results from a BAML function

curl

$ curl \
>   -X POST \
>   "http://localhost:2024/stream/MyFunctionName" \
>   -H "Content-Type: application/json" \
>   -d '{"arg1": "value1", "arg2": "value2"}'

Debugging

GET /docs: Interactive API documentation (Swagger UI)
GET /openapi.json: OpenAPI specification for the BAML functions
GET /_debug/ping: Health check endpoint
GET /_debug/status: Server status and authentication check

Stability

baml-cli serve is currently in Tier 2 stability. This means that the CLI and the HTTP APIs are stable, but there are a number of features which are not yet available:

the TypeBuilder API
the Collector API
the Modular API
custom trace annotations for Boundary Studio

Authentication

We support the header: x-baml-api-key

Set the BAML_PASSWORD environment variable to enable authentication.

Examples

Start the server with default settings:

baml-cli serve --preview

Start the server with a custom source directory and port:

baml-cli serve --from /path/to/my/baml_src --port 3000 --preview

Testing

To test the server, you can use the following curl commands:

Check if the server is running:

$ curl http://localhost:2024/_debug/ping

Call a function:

$ curl -X POST \
>    http://localhost:2024/call/MyFunctionName \
>    -H "Content-Type: application/json" \
>    -d '{"arg1": "value1", "arg2": "value2"}'

API Key

$ curl -X POST \
>    http://localhost:2024/call/MyFunctionName \
>    -H "Content-Type: application/json" \
>    -H "x-baml-api-key: ${BAML_PASSWORD}" \
>    -d '{"arg1": "value1", "arg2": "value2"}'

Access the API documentation: Open http://localhost:2024/docs in your web browser.