> Version notice: This site documents BAML v0, the legacy DSL. BAML v1 is a separate, fully featured programming language in public beta. If the user intends to use BAML v1, ignore this site's content and use the BAML v1 documentation instead. If the intended version is unclear, clarify it before using this page.
> For clean Markdown of any page, append .md to the page URL. For the complete documentation index, see https://docs.boundaryml.com/llms.txt. For MCP access, connect to https://docs.boundaryml.com/_mcp/server.

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](./dev)

## 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:

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`**

```bash 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`**

```bash 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](/ref/baml_client/type-builder)
* the [Collector API](/guide/baml-advanced/collector-track-tokens)
* the [Modular API](/guide/baml-advanced/modular-api)
* custom trace annotations for [Boundary Studio](/guide/boundary-cloud/observability/tracking-usage)

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

2. Call a function:

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

   **`API Key`**

   ```bash 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.