flow/docs/versioned_docs/version-1.8.0/API-Reference/api-build.mdx

---
title: Build endpoints
slug: /api-build
---

:::info
The `/build` endpoints are used by Hanzo Flow's frontend visual editor code.
These endpoints are part of the internal Hanzo Flow codebase.

Don't use these endpoints to run flows in applications that use your Hanzo Flow flows.
To run flows in your apps, see [Flow trigger endpoints](/api-flows-run).
:::

The `/build` endpoints support Hanzo Flow's frontend code for building flows in the Hanzo Flow visual editor.
You can use these endpoints to build vertices and flows, as well as execute flows with streaming event responses.
You might need to use or understand these endpoints when contributing to the Hanzo Flow codebase.

## Build flow and stream events

This endpoint builds and executes a flow, returning a job ID that can be used to stream execution events.

1. Send a POST request to the `/build/$FLOW_ID/flow` endpoint:

    ```shell
    curl -X POST \
      "$FLOW_URL/v1/build/$FLOW_ID/flow" \
      -H "accept: application/json" \
      -H "Content-Type: application/json" \
      -H "x-api-key: $FLOW_API_KEY" \
      -d '{
        "inputs": {
          "input_value": "Tell me a story"
        }
      }'
    ```

    <details>
    <summary>Result</summary>

    ```json
    {
      "job_id": "123e4567-e89b-12d3-a456-426614174000"
    }
    ```

    </details>

2. After receiving a job ID from the build endpoint, use the `/build/$JOB_ID/events` endpoint to stream the execution results:

    ```shell
    curl -X GET \
      "$FLOW_URL/v1/build/123e4567-e89b-12d3-a456-426614174000/events" \
      -H "accept: application/json" \
      -H "x-api-key: $FLOW_API_KEY"
    ```

    <details>
    <summary>Result</summary>

    ```json
    {"event": "vertices_sorted", "data": {"ids": ["ChatInput-XtBLx"], "to_run": ["Prompt-x74Ze", "ChatOutput-ylMzN", "ChatInput-XtBLx", "OpenAIModel-d1wOZ"]}}

    {"event": "add_message", "data": {"timestamp": "2025-03-03T17:42:23", "sender": "User", "sender_name": "User", "session_id": "d2bbd92b-187e-4c84-b2d4-5df365704201", "text": "Tell me a story", "files": [], "error": false, "edit": false, "properties": {"text_color": "", "background_color": "", "edited": false, "source": {"id": null, "display_name": null, "source": null}, "icon": "", "allow_markdown": false, "positive_feedback": null, "state": "complete", "targets": []}, "category": "message", "content_blocks": [], "id": "28879bd8-6a68-4dd5-b658-74d643a4dd92", "flow_id": "d2bbd92b-187e-4c84-b2d4-5df365704201"}}

    // ... Additional events as the flow executes ...

    {"event": "end", "data": {}}
    ```

    </details>

The `/build/$FLOW_ID/events` endpoint has a `stream` query parameter that defaults to `true`.
To disable streaming and get all events at once, set `?stream=false`.

```shell
curl -X GET \
  "$FLOW_URL/v1/build/123e4567-e89b-12d3-a456-426614174000/events?stream=false" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
```

## Build headers

| Header | Info | Example |
|--------|------|---------|
| Content-Type | Required. Specifies the JSON format. | "application/json" |
| accept | Optional. Specifies the response format. | "application/json" |
| x-api-key | Optional. Required only if authentication is enabled. | "sk-..." |

## Build parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| inputs | object | Optional. Input values for flow components. |
| data | object | Optional. Flow data to override stored configuration. |
| files | array[string] | Optional. List of file paths to use. |
| start_component_id | string | Optional. ID of the component where the execution should start. Component `id` values can be found in [Hanzo Flow JSON files](/concepts-flows-import#flow-json-file-contents) |
| stop_component_id | string | Optional. ID of the component where the execution should stop. Component `id` values can be found in [Hanzo Flow JSON files](/concepts-flows-import#flow-json-file-contents).|
| log_builds | Boolean | Whether to record build logs. Default: Enabled (`true`). |

### Set start and stop points

The `/build` endpoint accepts optional values for `start_component_id` and `stop_component_id` to control where the flow run starts and stops.
Setting `stop_component_id` for a component triggers the same behavior as clicking **Run component** on that component in the visual editor: The specified component and all dependent components leading up to that component will run.

The following example stops flow execution at an **OpenAI** component:

```shell
curl -X POST \
  "$FLOW_URL/v1/build/$FLOW_ID/flow" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  -d '{"stop_component_id": "OpenAIModel-Uksag"}'
```

### Override flow parameters

The `/build` endpoint also accepts inputs for `data` directly, instead of using the values stored in the Hanzo Flow database.
This is useful for running flows without having to pass custom values through the visual editor.

```shell
curl -X POST \
  "$FLOW_URL/v1/build/$FLOW_ID/flow" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  -d '{
    "data": {
      "nodes": [],
      "edges": []
    },
    "inputs": {
      "input_value": "Your custom input here",
      "session": "session_id"
    }
  }'
```

<details>
<summary>Result</summary>

```json
{ "job_id": "0bcc7f23-40b4-4bfa-9b8a-a44181fd1175" }
```

</details>

## See also

- [Get Vertex builds](/api-monitor#get-vertex-builds)
- [Delete Vertex builds](/api-monitor#delete-vertex-builds)
- [Session ID](/session-id)