Serve - Baml — ContextQMD

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]

<Tip> If you're actively developing, you can use the `dev` command to include hot-reload functionality: ``` baml-cli dev [OPTIONS] ```

See more </Tip>

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

bash

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

bash

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:
bash
```
curl http://localhost:2024/_debug/ping
```

Call a function:

bash

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

bash

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.