docs: draft build for versioning

docs/README.md

@@ -39,3 +39,63 @@ $ GIT_USER=<Your GitHub username> yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+
+## Docusaurus Versioning
+
+The versioning configuration is found in `docusaurus.config.js`.
+
+The version key `'current'` is a special Docusaurus keyword that refers to the work-in-progress docs. You can't change this key, but you can customize the `label`.
+
+Versioning example for release version 1.8.x:
+
+1. Before release, the `current` version contains work-in-progress docs that are ahead of version `1.7.x`. The `current` label should already be set to `1.8.x` (updated when you began working on the 1.8.x docset).
+2. When ready to release 1.8.x, create a branch and run `yarn docusaurus docs:version 1.8.0` to snapshot the current docs. Use the full version number like `1.8.0` for the command, even though the label displays `1.8.x`.
+3. After creating a new version, update `docusaurus.config.js`:
+
+```javascript
+docs: {
+  lastVersion: '1.8.0', // Make 1.8.0 the latest version (use full version number)
+  versions: {
+    current: {
+      label: '1.9.x', // Work-in-progress version (will become next release)
+      path: 'next',
+    },
+    '1.8.0': {
+      label: '1.8.x', // Label shows .x notation
+      path: '1.8.0',
+    },
+    '1.7.0': {
+      label: '1.7.x', // Label shows .x notation
+      path: '1.7.0',
+    },
+  },
+  onlyIncludeVersions: ['current', '1.8.0', '1.7.0'], // Include all versions
+},
+```
+
+4. Test the deployment locally:
+
+```bash
+yarn build
+yarn serve
+```
+
+5. Create a pull request to main, and merge to create your new release.
+6. To create version 1.9.x, repeat the process: update the `current` label to `1.9.x` when you begin working on it, then when ready to release, run `yarn docusaurus docs:version 1.9.0`, update `docusaurus.config.js` with labels using `.x` notation, and merge to main.
+
+- `current` = always the work-in-progress docs from `main` branch (ahead of all releases)
+  - The version key must be `'current'` (Docusaurus keyword), but you can customize the displayed `label`
+- `lastVersion` = the most recent released version (shown as "latest" in the UI).
+
+See the [Docusaurus docs](https://docusaurus.io/docs/versioning) for more info.
+
+### Disable versioning
+
+1. Remove the versions configuration from `docusaurus.config.js`.
+2. Delete the `docs/versioned_docs/` and `docs/versioned_sidebars/` directories.
+3. Delete `docs/versions.json`.
+
+### References
+
+- [Official Docusaurus Versioning Documentation](https://docusaurus.io/docs/versioning)
+- [Docusaurus Versioning Best Practices](https://docusaurus.io/docs/versioning#versioning-best-practices)

docs/docusaurus.config.js

@@ -105,6 +105,18 @@ const config = {
           routeBasePath: "/", // Serve the docs at the site's root
           sidebarPath: require.resolve("./sidebars.js"), // Use sidebars.js file
           sidebarCollapsed: true,
+          // Versioning configuration
+          lastVersion: '1.7.0',
+          versions: {
+            current: {
+              label: '1.8.x', // Work-in-progress version (will become next release)
+              path: 'next',
+            },
+            '1.7.0': {
+              label: '1.7.x',
+            },
+          },
+          onlyIncludeVersions: ['current', '1.7.0'], // Include both versions
           beforeDefaultRemarkPlugins: [
             [
               remarkCodeHike,
@@ -168,6 +180,7 @@ const config = {
     [
       "@docusaurus/plugin-client-redirects",
       {
+        // Docusaurus automatically resolves redirects to the version set by lastVersion
         redirects: [
           {
             to: "/",
@@ -407,6 +420,10 @@ const config = {
           srcDark: "img/lf-docs-dark.svg",
         },
         items: [
+          {
+            type: 'docsVersionDropdown',
+            position: 'right',
+          },
           // right
           {
             position: "right",

docs/versioned_docs/version-1.7.0/API-Reference/api-build.mdx

@@ -0,0 +1,153 @@
+---
+title: Build endpoints
+slug: /api-build
+---
+
+:::info
+The `/build` endpoints are used by Langflow's frontend visual editor code.
+These endpoints are part of the internal Langflow codebase.
+
+Don't use these endpoints to run flows in applications that use your Langflow flows.
+To run flows in your apps, see [Flow trigger endpoints](/api-flows-run).
+:::
+
+The `/build` endpoints support Langflow's frontend code for building flows in the Langflow 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 Langflow 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 \
+      "$LANGFLOW_URL/api/v1/build/$FLOW_ID/flow" \
+      -H "accept: application/json" \
+      -H "Content-Type: application/json" \
+      -H "x-api-key: $LANGFLOW_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 \
+      "$LANGFLOW_URL/api/v1/build/123e4567-e89b-12d3-a456-426614174000/events" \
+      -H "accept: application/json" \
+      -H "x-api-key: $LANGFLOW_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 \
+  "$LANGFLOW_URL/api/v1/build/123e4567-e89b-12d3-a456-426614174000/events?stream=false" \
+  -H "accept: application/json" \
+  -H "x-api-key: $LANGFLOW_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 [Langflow JSON files](/concepts-flows-import#langflow-json-file-contents) |
+| stop_component_id | string | Optional. ID of the component where the execution should stop. Component `id` values can be found in [Langflow JSON files](/concepts-flows-import#langflow-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 \
+  "$LANGFLOW_URL/api/v1/build/$FLOW_ID/flow" \
+  -H "accept: application/json" \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $LANGFLOW_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 Langflow database.
+This is useful for running flows without having to pass custom values through the visual editor.
+
+```shell
+curl -X POST \
+  "$LANGFLOW_URL/api/v1/build/$FLOW_ID/flow" \
+  -H "accept: application/json" \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $LANGFLOW_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)