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]

See more

Options

OptionDescriptionDefault
--from <PATH>Path to the baml_src directory./baml_src
--port <PORT>Port to expose BAML on2024
--no-version-checkGenerate baml_client without checking for version mismatchfalse

Description

The serve command performs the following actions:

  1. Exposes BAML functions as HTTP endpoints on the specified port.
  2. 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:

Authentication

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

Set the BAML_PASSWORD environment variable to enable authentication.

Examples

  1. Start the server with default settings:

    baml-cli serve --preview
  2. 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:

  1. Check if the server is running:

    $curl http://localhost:2024/_debug/ping
  2. 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"}'
  3. Access the API documentation: Open http://localhost:2024/docs in your web browser.