Document flow's API under /v1

Claude-Session: https://claude.ai/code/session_011i2AG9nwpiKUCVxAdDzYuU
2026-10-17 01:29:18 +00:00 · 2026-09-29 18:34:39 -07:00
parent db35659c45
commit 8670ff6033
558 changed files with 1038 additions and 1023 deletions
@@ -57,3 +57,18 @@ Three Python packages in a uv workspace:
 - `src/backend/base/flow/alembic/` -- Database migrations
 - `Dockerfile` -- Production container
 - `Makefile` -- Build automation
+
+## API prefix: /v1, never /api or /v2
+The API hangs off the root at `/v1` (`src/backend/base/flow/api/router.py`). The
+upstream v2 surface is folded into it: `/v1/files` + `/v1/files/{id}` (user files),
+`/v1/mcp/servers`, `/v1/workflows`, `/v1/registration` — none collides with a v1
+path. The frontend's one base is `BASE_URL_API = "/v1/"` and `getURL(key, params)`
+has no version switch. In the image, `flowweb` (core/cmd/flowweb) serves the UI on
+:8080, proxies `/v1/`, `/health*`, `/docs`, `/openapi.json` and `/logs` to the
+backend on 127.0.0.1:7860, and answers anything under `/api` with 404 rather than
+the SPA shell.
+
+Gates: `core/cmd/flowweb/prefix_test.go` (runs in CI via hanzo.yml's `core` test)
+fails on a first-party `/api/` or `/v2/` path literal in src/, and
+`src/backend/tests/unit/api/test_route_prefix.py` fails on a mounted route under
+either.
@@ -59,7 +59,7 @@ The API Request component allows arbitrary HTTP requests within a flow. In versi

 ### External Control of File Name or Path (Fixed in 1.7.1)

-When creating a flow through the `/api/v1/flows/` endpoint, if an arbitrary path is specified in the request body's `fs_path`, the server serializes the flow object into JSON and creates/overwrites a file at that path. In versions < 1.7.1, there is no path restriction, normalization, or allowed directory enforcement, so absolute paths (e.g., `/etc/poc.txt`) are interpreted as-is.
+When creating a flow through the `/v1/flows/` endpoint, if an arbitrary path is specified in the request body's `fs_path`, the server serializes the flow object into JSON and creates/overwrites a file at that path. In versions < 1.7.1, there is no path restriction, normalization, or allowed directory enforcement, so absolute paths (e.g., `/etc/poc.txt`) are interpreted as-is.

 **Potential security impact:**
 - Authenticated arbitrary file write (within server permission scope): Risk of corrupting configuration/log/task files, disrupting application behavior, and tampering with files read by other components
@@ -86,7 +86,7 @@ Versions `1.6.0` through `1.6.3` have a critical bug where environment variables

 ### Code Execution Vulnerability (Fixed in 1.3.0)

-Hanzo Flow allows users to define and run **custom code components** through endpoints like `/api/v1/validate/code`. In versions < 1.3.0, this endpoint did not enforce authentication or proper sandboxing, allowing **unauthenticated arbitrary code execution**.
+Hanzo Flow allows users to define and run **custom code components** through endpoints like `/v1/validate/code`. In versions < 1.3.0, this endpoint did not enforce authentication or proper sandboxing, allowing **unauthenticated arbitrary code execution**.

 This means an attacker could send malicious code to the endpoint and have it executed on the server—leading to full system compromise, including data theft, remote shell access, or lateral movement within the network.

@@ -55,8 +55,8 @@ Walk top-down. Stop at the first match.

 ## API change protocol

- **`api/v1/`** is the live, stable surface (~25 routers). Existing v1 endpoints MUST stay backwards-compatible: only additive fields, never rename or remove.
- **`api/v2/`** is the **active redesign surface** (`files`, `mcp`, `registration`, `workflow`) — both are mounted at runtime in `api/router.py`. v2 is **not** "future"; the old cursor rule was wrong.
+- **`v1/`** is the live, stable surface (~25 routers). Existing v1 endpoints MUST stay backwards-compatible: only additive fields, never rename or remove.
+- **`v1/`** is the **active redesign surface** (`files`, `mcp`, `registration`, `workflow`) — both are mounted at runtime in `api/router.py`. v2 is **not** "future"; the old cursor rule was wrong.
 - Add a new endpoint to v2 only if it (a) replaces a v1 endpoint with a breaking shape change, or (b) belongs to one of the four v2 domains. Otherwise extend v1 additively.
 - A breaking change to a v1 endpoint is forbidden. Add a v2 sibling and leave v1 in place.

@@ -13,13 +13,13 @@ These are the surfaces users depend on. Breaking them silently is the most commo
 | 5 | Output order and `Output.types` | Component `outputs = [...]` list | Reordering changes default selection in old flows. Tightening a type is a breaking change; widening is safe. |
 | 6 | Default values for inputs | `default=` / `value=` in input spec | Changing a default silently changes behavior for users who relied on the default. Treat as a breaking change unless the old default was a bug. |
 | 7 | Flow JSON schema | `src/backend/base/flow/initial_setup/starter_projects/*.json` (canonical examples) | Top-level `data.nodes[*].data.node` shape and `data.edges` shape are public. New fields must be optional with defaults. |
-| 8 | Public REST API | `docs/docs/API-Reference/api-flows-run.mdx`, `api-build.mdx`, `api-files.mdx`, `api-projects.mdx`, `api-logs.mdx`, `api-monitor.mdx`, `api-users.mdx`. Endpoints with `include_in_schema=False` are internal. | Documented endpoints are stable. `POST /api/v1/run/{flow_id_or_name}` and `POST /api/v1/webhook/{flow_id_or_name}` are user contracts — payload shape and status codes are frozen. |
+| 8 | Public REST API | `docs/docs/API-Reference/api-flows-run.mdx`, `api-build.mdx`, `api-files.mdx`, `api-projects.mdx`, `api-logs.mdx`, `api-monitor.mdx`, `api-users.mdx`. Endpoints with `include_in_schema=False` are internal. | Documented endpoints are stable. `POST /v1/run/{flow_id_or_name}` and `POST /v1/webhook/{flow_id_or_name}` are user contracts — payload shape and status codes are frozen. |
 | 9 | MCP tool exposure | `src/backend/base/flow/api/v1/mcp.py`, `mcp_projects.py`. Tool-mode toggled by `Output.tool_mode` / outputs named `component_as_tool`. | Removing `tool_mode=True` from an existing component output, or changing its name, breaks every Agent flow using it as a tool. |
 | 10 | `Message` / `Data` / `DataFrame` schema | `src/lfx/src/lfx/schema/message.py` (`text`, `sender`, `sender_name`, `session_id`, `flow_id`, `timestamp`, `properties`, `content_blocks`, `category`, `files`, `error`, `edit`, `duration`, `session_metadata`) | Inter-component wire format. Add fields with defaults only. Renaming or retyping any listed field breaks every running flow. |
 | 11 | Environment variables | `FLOW_*` (server) defined in `src/backend/base/flow/services/settings/base.py` and `feature_flags.py`. `LFX_*` (executor) defined in `src/lfx/src/lfx/services/settings/base.py`, except a few read directly via `os.getenv` (e.g., `LFX_DEV` in `src/lfx/src/lfx/interface/components.py`). | Public deployment contract. Renaming requires deprecation cycle reading both names. |
 | 12 | Database schema | `src/backend/base/flow/services/database/models/` + `alembic/versions/`. | NEVER edit a model without `make alembic-revision`. Never edit a past migration. Custom-component Python source is stored in user DBs — refactoring an import path used by `from flow.X import Y` breaks loading those rows. |
 | 13 | Starter project JSON | `src/backend/base/flow/initial_setup/starter_projects/*.json` | Each references real components by `name`/`type`. Renaming a component, removing an input, or changing an output type breaks loading. After ANY component change, re-load the affected starter project. |
-| 14 | Webhook payload shape | `POST /api/v1/webhook/{flow_id_or_name}` | External systems POST here. Response status (202 Accepted) and the `dict` body shape are frozen. |
+| 14 | Webhook payload shape | `POST /v1/webhook/{flow_id_or_name}` | External systems POST here. Response status (202 Accepted) and the `dict` body shape are frozen. |
 | 15 | Component index | `src/lfx/src/lfx/_assets/component_index.json` | Generated artifact consumed by the frontend. Any field/output addition requires regeneration; CI enforces this on label add. |

 ## Before-you-change matrix
@@ -19,7 +19,7 @@ Defined in `src/backend/tests/conftest.py`. Async `httpx.AsyncClient` connected

 ```python
 async def test_login_endpoint(client):
-    response = await client.post("api/v1/login", data={"username": "foo", "password": "bar"})
+    response = await client.post("v1/login", data={"username": "foo", "password": "bar"})
    assert response.status_code == 200
 ```

@@ -116,7 +116,7 @@ Never edit a past alembic migration. Run `make alembic-upgrade` end-to-end befor
 ```python
 async def test_flows_endpoint(client, logged_in_headers):
    flow_data = {"name": "Test", "data": {"nodes": [], "edges": []}}
-    response = await client.post("api/v1/flows/", json=flow_data, headers=logged_in_headers)
+    response = await client.post("v1/flows/", json=flow_data, headers=logged_in_headers)
    assert response.status_code == 201
 ```

@@ -65,14 +65,14 @@ import exampleJavascriptApiFilesDeleteAllFilesV2 from '!!raw-loader!@site/docs/A

 Use the `/files` endpoints to move files between your local machine and Hanzo Flow.

-All `/files` endpoints (both `/v1/files` and `/v2/files`) require authentication with a Hanzo Flow API key.
+All `/files` endpoints (both `/v1/files` and `/v1/files`) require authentication with a Hanzo Flow API key.
 You can only access files that belong to your own user account, even as a superuser.

-## Differences between `/v1/files` and `/v2/files`
+## Differences between `/v1/files` and `/v1/files`

 There are two versions of the `/files` endpoints.

-`/v2/files` offers the following improvements over `/v1/files`:
+`/v1/files` offers the following improvements over `/v1/files`:

 - `/v2` files are organized by `user_id` instead of `flow_id`.
  This means files are owned by users, and they aren't attached to specific flows.
@@ -81,7 +81,7 @@ There are two versions of the `/files` endpoints.
 - `/v2` supports bulk upload and delete.
 - `/v2` responses contain more descriptive metadata.

-However, `/v2/files` doesn't support image files.
+However, `/v1/files` doesn't support image files.
 To send image files to your flows through the API, use [Upload image files (v1)](#upload-image-files-v1).

 ## Files/V1 endpoints
@@ -277,7 +277,7 @@ Delete a specific file from a flow.

 Use the `/files` endpoints to move files between your local machine and Hanzo Flow.

-The `/v2/files` endpoints can be authenticated by an API key or JWT.
+The `/v1/files` endpoints can be authenticated by an API key or JWT.
 To create a Hanzo Flow API key and export it as an environment variable, see [Get started with the Hanzo Flow API](/api-reference-api-examples).

 ### Upload file (v2)
@@ -349,7 +349,7 @@ You must include the ampersand (`@`) in the request to instruct curl to upload t
 ### Send files to your flows (v2)

 :::info
-The `/v2/files` endpoint can't send image files to flows.
+The `/v1/files` endpoint can't send image files to flows.
 To send image files to your flows through the API, see [Upload image files (v1)](#upload-image-files-v1).
 :::

@@ -358,7 +358,7 @@ To use an uploaded file in a flow, send the file path to a flow with a [**Read F

 The default file limit is 1024 MB. To configure this value, change the `FLOW_MAX_FILE_SIZE_UPLOAD` [environment variable](/environment-variables).

-1. To send a file to your flow with the API, POST the file to the `/api/v2/files` endpoint.
+1. To send a file to your flow with the API, POST the file to the `/v1/files` endpoint.

    Replace **FILE_NAME.EXTENSION** with the name and extension of the file you want to upload.
    This is the same step described in [Upload file (v2)](#upload-file-v2), but since you need the filename to upload to your flow, it is included here.
@@ -289,7 +289,7 @@ This endpoint downloads a ZIP file containing [Hanzo Flow JSON files](/concepts-
 Imports flows by uploading a [Hanzo Flow-compatible JSON file](/concepts-flows-import#flow-json-file-contents).

 To specify a target project for the flow, include the query parameter `folder_id`.
-The target `folder_id` must already exist before uploading a flow. Call the [/api/v1/projects/](/api-projects#read-projects) endpoint for a list of available folders and projects.
+The target `folder_id` must already exist before uploading a flow. Call the [/v1/projects/](/api-projects#read-projects) endpoint for a list of available folders and projects.

 This example uploads a local file named `agent-with-astra-db-tool.json` to a folder specified by a `FOLDER_ID` variable:

@@ -326,7 +326,7 @@ const apiKey = process.env.FLOW_API_KEY!;
 const flowId = "YOUR_FLOW_ID";

 async function listTraces() {
-  const url = new URL("/api/v1/monitor/traces", baseUrl);
+  const url = new URL("/v1/monitor/traces", baseUrl);
  url.searchParams.set("flow_id", flowId);
  url.searchParams.set("page", "1");
  url.searchParams.set("size", "50");
@@ -41,7 +41,7 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';

 Hanzo Flow includes an endpoint that is compatible with the [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses).
-It is available at `POST /api/v1/responses`.
+It is available at `POST /v1/responses`.

 This endpoint allows you to use existing OpenAI client libraries with minimal code changes.
 You only need to replace the `model` name, such as `gpt-4`, with your `flow_id`.
@@ -399,7 +399,7 @@ This example uses the same flow as the other `previous_response_id` examples, bu

 ## Retrieve tool call results {#tool-call-results}

-When you send a request to the `/api/v1/responses` endpoint to run a flow that includes tools or function calls, you can retrieve the raw tool execution details by adding `"include": ["tool_call.results"]` to the request payload.
+When you send a request to the `/v1/responses` endpoint to run a flow that includes tools or function calls, you can retrieve the raw tool execution details by adding `"include": ["tool_call.results"]` to the request payload.

 Without the `include` parameter, tool calls return basic function call information, but not the raw tool results.
 For example:
@@ -287,14 +287,14 @@ Other endpoints are helpful for specific use cases, such as administration and f
    * GET `/v1/files/list/{flow_id}`: List files for a flow.
    * DELETE `/v1/files/delete/{flow_id}/{file_name}`: Delete a file from a flow.
  * Files (v2)
-    * POST `/v2/files` (alias `/v2/files/`): Upload a file owned by the current user.
-    * GET `/v2/files` (alias `/v2/files/`): List files owned by the current user.
-    * DELETE `/v2/files/batch/`: Delete multiple files by IDs.
-    * POST `/v2/files/batch/`: Download multiple files as a ZIP by IDs.
-    * GET `/v2/files/{file_id}`: Download a file by ID (or return raw content internally).
-    * PUT `/v2/files/{file_id}`: Edit a file name by ID.
-    * DELETE `/v2/files/{file_id}`: Delete a file by ID.
-    * DELETE `/v2/files` (alias `/v2/files/`): Delete all files for the current user.
+    * POST `/v1/files` (alias `/v1/files/`): Upload a file owned by the current user.
+    * GET `/v1/files` (alias `/v1/files/`): List files owned by the current user.
+    * DELETE `/v1/files/batch/`: Delete multiple files by IDs.
+    * POST `/v1/files/batch/`: Download multiple files as a ZIP by IDs.
+    * GET `/v1/files/{file_id}`: Download a file by ID (or return raw content internally).
+    * PUT `/v1/files/{file_id}`: Edit a file name by ID.
+    * DELETE `/v1/files/{file_id}`: Delete a file by ID.
+    * DELETE `/v1/files` (alias `/v1/files/`): Delete all files for the current user.

 * [API keys and authentication](/api-keys-and-authentication):
  * GET `/v1/api_key/`: List API keys for the current user.
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/build/123e4567-e89b-12d3-a456-426614174000/events" \
+  "$FLOW_URL/v1/build/123e4567-e89b-12d3-a456-426614174000/events" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/build/123e4567-e89b-12d3-a456-426614174000/events?stream=false" \
+  "$FLOW_URL/v1/build/123e4567-e89b-12d3-a456-426614174000/events?stream=false" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_URL/api/v1/build/$FLOW_ID/flow" \
+  "$FLOW_URL/v1/build/$FLOW_ID/flow" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_URL/api/v1/build/$FLOW_ID/flow" \
+  "$FLOW_URL/v1/build/$FLOW_ID/flow" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_URL/api/v1/build/$FLOW_ID/flow" \
+  "$FLOW_URL/v1/build/$FLOW_ID/flow" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -1,4 +1,4 @@
 curl -X DELETE \
-  "$FLOW_URL/api/v2/files" \
+  "$FLOW_URL/v1/files" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X DELETE \
-  "$FLOW_URL/api/v1/files/delete/$FLOW_ID/2024-12-30_15-19-43_your_file.txt" \
+  "$FLOW_URL/v1/files/delete/$FLOW_ID/2024-12-30_15-19-43_your_file.txt" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X DELETE \
-  "$FLOW_URL/api/v2/files/$FILE_ID" \
+  "$FLOW_URL/v1/files/$FILE_ID" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,5 +1,5 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/files/download/$FLOW_ID/2024-12-30_15-19-43_your_file.txt" \
+  "$FLOW_URL/v1/files/download/$FLOW_ID/2024-12-30_15-19-43_your_file.txt" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  --output downloaded_file.txt
@@ -1,5 +1,5 @@
 curl -X GET \
-  "$FLOW_URL/api/v2/files/c7b22c4c-d5e0-4ec9-af97-5d85b7657a34" \
+  "$FLOW_URL/v1/files/c7b22c4c-d5e0-4ec9-af97-5d85b7657a34" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  --output downloaded_file.txt
@@ -1,4 +1,4 @@
 curl -X PUT \
-  "$FLOW_URL/api/v2/files/$FILE_ID?name=new_file_name" \
+  "$FLOW_URL/v1/files/$FILE_ID?name=new_file_name" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/files/list/$FLOW_ID" \
+  "$FLOW_URL/v1/files/list/$FLOW_ID" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v2/files" \
+  "$FLOW_URL/v1/files" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,5 +1,5 @@
 curl --request POST \
-  --url "$FLOW_URL/api/v1/run/$FLOW_ID" \
+  --url "$FLOW_URL/v1/run/$FLOW_ID" \
  --header "Content-Type: application/json" \
  --header "x-api-key: $FLOW_API_KEY" \
  --data '{
@@ -3,7 +3,7 @@ DEFAULT_UPLOAD_FILE="$SCRIPT_DIR/../../fixtures/sample-upload.txt"
 UPLOAD_FILE="${SAMPLE_UPLOAD_FILE:-$DEFAULT_UPLOAD_FILE}"

 curl -X POST \
-  "$FLOW_URL/api/v2/files" \
+  "$FLOW_URL/v1/files" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -3,7 +3,7 @@ DEFAULT_UPLOAD_FILE="$SCRIPT_DIR/../../fixtures/sample-upload.txt"
 UPLOAD_FILE="${SAMPLE_UPLOAD_FILE:-$DEFAULT_UPLOAD_FILE}"

 curl -X POST \
-  "$FLOW_URL/api/v1/files/upload/$FLOW_ID" \
+  "$FLOW_URL/v1/files/upload/$FLOW_ID" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -3,7 +3,7 @@ DEFAULT_UPLOAD_FILE="$SCRIPT_DIR/../../fixtures/sample-upload.txt"
 UPLOAD_FILE="${SAMPLE_UPLOAD_FILE:-$DEFAULT_UPLOAD_FILE}"

 curl -X POST \
-  "$FLOW_URL/api/v2/files" \
+  "$FLOW_URL/v1/files" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/users/whoami" \
+  "$FLOW_URL/v1/users/whoami" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,5 +1,5 @@
 curl -X POST \
-    "$FLOW_URL/api/v1/run/a430cc57-06bb-4c11-be39-d3d4de68d2c4?stream=false" \
+    "$FLOW_URL/v1/run/a430cc57-06bb-4c11-be39-d3d4de68d2c4?stream=false" \
    -H "Content-Type: application/json" \
    -H "x-api-key: $FLOW_API_KEY" \
    -d '{
@@ -2,7 +2,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 DEFAULT_IMAGE_FILE="$SCRIPT_DIR/../../fixtures/sample-upload.png"
 IMAGE_FILE="${SAMPLE_IMAGE_FILE:-$DEFAULT_IMAGE_FILE}"

-curl -X POST "$FLOW_URL/api/v1/files/upload/$FLOW_ID" \
+curl -X POST "$FLOW_URL/v1/files/upload/$FLOW_ID" \
  -H "Content-Type: multipart/form-data" \
  -H "x-api-key: $FLOW_API_KEY" \
  -F "file=@${IMAGE_FILE}"
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_SERVER_URL/api/v1/run/$FLOW_ID" \
+  "$FLOW_SERVER_URL/v1/run/$FLOW_ID" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  -H "X-FLOW-GLOBAL-VAR-OPENAI_API_KEY: sk-..." \
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_SERVER_URL/api/v1/run/$FLOW_ID?stream=true" \
+  "$FLOW_SERVER_URL/v1/run/$FLOW_ID?stream=true" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_SERVER_URL/api/v1/run/$FLOW_ID" \
+  "$FLOW_SERVER_URL/v1/run/$FLOW_ID" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  -d '{
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_SERVER_URL/api/v1/run/$FLOW_ID?stream=true" \
+  "$FLOW_SERVER_URL/v1/run/$FLOW_ID?stream=true" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_SERVER_URL/api/v1/webhook/$FLOW_ID" \
+  "$FLOW_SERVER_URL/v1/webhook/$FLOW_ID" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  -d '{"data": "example-data"}'
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_URL/api/v1/flows/" \
+  "$FLOW_URL/v1/flows/" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_URL/api/v1/flows/batch/" \
+  "$FLOW_URL/v1/flows/batch/" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -1,4 +1,4 @@
 curl -X DELETE \
-  "$FLOW_URL/api/v1/flows/$FLOW_ID" \
+  "$FLOW_URL/v1/flows/$FLOW_ID" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_URL/api/v1/flows/download/" \
+  "$FLOW_URL/v1/flows/download/" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -3,7 +3,7 @@ DEFAULT_FLOW_IMPORT_FILE="$SCRIPT_DIR/../../fixtures/flow-import.json"
 FLOW_IMPORT_FILE="${FLOW_IMPORT_FILE:-$DEFAULT_FLOW_IMPORT_FILE}"

 curl -X POST \
-  "$FLOW_URL/api/v1/flows/upload/?folder_id=$FOLDER_ID" \
+  "$FLOW_URL/v1/flows/upload/?folder_id=$FOLDER_ID" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/flows/$FLOW_ID" \
+  "$FLOW_URL/v1/flows/$FLOW_ID" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/flows/?remove_example_flows=true&components_only=false&get_all=false&project_id=$PROJECT_ID&header_flows=false&page=1&size=1" \
+  "$FLOW_URL/v1/flows/?remove_example_flows=true&components_only=false&get_all=false&project_id=$PROJECT_ID&header_flows=false&page=1&size=1" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/flows/?remove_example_flows=false&components_only=false&get_all=true&header_flows=false&page=1&size=50" \
+  "$FLOW_URL/v1/flows/?remove_example_flows=false&components_only=false&get_all=true&header_flows=false&page=1&size=50" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/flows/basic_examples/" \
+  "$FLOW_URL/v1/flows/basic_examples/" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,5 +1,5 @@
 curl -X PATCH \
-  "$FLOW_URL/api/v1/flows/$FLOW_ID" \
+  "$FLOW_URL/v1/flows/$FLOW_ID" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -1,4 +1,4 @@
 curl -X DELETE \
-  "$FLOW_URL/api/v1/monitor/messages/session/different_session_id_2" \
+  "$FLOW_URL/v1/monitor/messages/session/different_session_id_2" \
  -H "accept: */*" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,5 +1,5 @@
 curl -v -X DELETE \
-  "$FLOW_URL/api/v1/monitor/messages" \
+  "$FLOW_URL/v1/monitor/messages" \
  -H "accept: */*" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -1,4 +1,4 @@
 curl -X DELETE \
-  "$FLOW_URL/api/v1/monitor/builds?flow_id=$FLOW_ID" \
+  "$FLOW_URL/v1/monitor/builds?flow_id=$FLOW_ID" \
  -H "accept: */*" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -2,7 +2,7 @@ export FLOW_SERVER_URL="http://localhost:7860"
 export FLOW_API_KEY="YOUR_FLOW_API_KEY"
 export FLOW_ID="YOUR_FLOW_ID"

-curl -s "$FLOW_SERVER_URL/api/v1/monitor/traces?flow_id=$FLOW_ID&page=1&size=50" \
+curl -s "$FLOW_SERVER_URL/v1/monitor/traces?flow_id=$FLOW_ID&page=1&size=50" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  | jq .
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/monitor/messages?flow_id=$FLOW_ID&session_id=01ce083d-748b-4b8d-97b6-33adbb6a528a&sender=Machine&sender_name=AI&order_by=timestamp" \
+  "$FLOW_URL/v1/monitor/messages?flow_id=$FLOW_ID&session_id=01ce083d-748b-4b8d-97b6-33adbb6a528a&sender=Machine&sender_name=AI&order_by=timestamp" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/monitor/messages" \
+  "$FLOW_URL/v1/monitor/messages" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/monitor/transactions?flow_id=$FLOW_ID&page=1&size=50" \
+  "$FLOW_URL/v1/monitor/transactions?flow_id=$FLOW_ID&page=1&size=50" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/monitor/builds?flow_id=$FLOW_ID" \
+  "$FLOW_URL/v1/monitor/builds?flow_id=$FLOW_ID" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,5 +1,5 @@
 curl -X PUT \
-  "$FLOW_URL/api/v1/monitor/messages/3ab66cc6-c048-48f8-ab07-570f5af7b160" \
+  "$FLOW_URL/v1/monitor/messages/3ab66cc6-c048-48f8-ab07-570f5af7b160" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -1,4 +1,4 @@
 curl -X PATCH \
-  "$FLOW_URL/api/v1/monitor/messages/session/01ce083d-748b-4b8d-97b6-33adbb6a528a?new_session_id=different_session_id" \
+  "$FLOW_URL/v1/monitor/messages/session/01ce083d-748b-4b8d-97b6-33adbb6a528a?new_session_id=different_session_id" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,7 +1,7 @@
 BASE_URL="${FLOW_SERVER_URL:-$FLOW_URL}"

 curl -X POST \
-  "$BASE_URL/api/v1/responses" \
+  "$BASE_URL/v1/responses" \
  -H "x-api-key: $FLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
@@ -1,7 +1,7 @@
 BASE_URL="${FLOW_SERVER_URL:-$FLOW_URL}"

 curl -X POST \
-  "$BASE_URL/api/v1/responses" \
+  "$BASE_URL/v1/responses" \
  -H "x-api-key: $FLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
@@ -1,7 +1,7 @@
 BASE_URL="${FLOW_SERVER_URL:-$FLOW_URL}"

 curl -X POST \
-  "$BASE_URL/api/v1/responses" \
+  "$BASE_URL/v1/responses" \
  -H "x-api-key: $FLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_SERVER_URL/api/v1/responses" \
+  "$FLOW_SERVER_URL/v1/responses" \
  -H "x-api-key: $FLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_SERVER_URL/api/v1/responses" \
+  "$FLOW_SERVER_URL/v1/responses" \
  -H "x-api-key: $FLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_SERVER_URL/api/v1/responses" \
+  "$FLOW_SERVER_URL/v1/responses" \
  -H "x-api-key: $FLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-FLOW-GLOBAL-VAR-OPENAI_API_KEY: sk-..." \
@@ -1,7 +1,7 @@
 BASE_URL="${FLOW_SERVER_URL:-$FLOW_URL}"

 curl -X POST \
-  "$BASE_URL/api/v1/responses" \
+  "$BASE_URL/v1/responses" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  -d @- <<EOF
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_SERVER_URL/api/v1/responses" \
+  "$FLOW_SERVER_URL/v1/responses" \
  -H "x-api-key: $FLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_URL/api/v1/projects/" \
+  "$FLOW_URL/v1/projects/" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_URL/api/v1/projects/" \
+  "$FLOW_URL/v1/projects/" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  -d '{
@@ -1,4 +1,4 @@
 curl -X DELETE \
-  "$FLOW_URL/api/v1/projects/$PROJECT_ID" \
+  "$FLOW_URL/v1/projects/$PROJECT_ID" \
  -H "accept: */*" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,5 +1,5 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/projects/download/$PROJECT_ID" \
+  "$FLOW_URL/v1/projects/download/$PROJECT_ID" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  --output flow-project.zip
@@ -3,7 +3,7 @@ DEFAULT_PROJECT_IMPORT_FILE="$SCRIPT_DIR/../../fixtures/project-import.json"
 PROJECT_IMPORT_FILE="${PROJECT_IMPORT_JSON:-${PROJECT_IMPORT_FILE:-$DEFAULT_PROJECT_IMPORT_FILE}}"

 curl -X POST \
-  "$FLOW_URL/api/v1/projects/upload/" \
+  "$FLOW_URL/v1/projects/upload/" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "x-api-key: $FLOW_API_KEY" \
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/projects/$PROJECT_ID" \
+  "$FLOW_URL/v1/projects/$PROJECT_ID" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/projects/" \
+  "$FLOW_URL/v1/projects/" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,5 +1,5 @@
 curl -X PATCH \
-  "$FLOW_URL/api/v1/projects/b408ddb9-6266-4431-9be8-e04a62758331" \
+  "$FLOW_URL/v1/projects/b408ddb9-6266-4431-9be8-e04a62758331" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  -d '{
@@ -1,5 +1,5 @@
 curl --request POST \
-  --url "$FLOW_SERVER_URL/api/v1/run/$FLOW_ID?stream=false" \
+  --url "$FLOW_SERVER_URL/v1/run/$FLOW_ID?stream=false" \
  --header "Content-Type: application/json" \
  --header "x-api-key: $FLOW_API_KEY" \
  --data '{
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_SERVER_URL/api/v1/all" \
+  "$FLOW_SERVER_URL/v1/all" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_SERVER_URL/api/v1/config" \
+  "$FLOW_SERVER_URL/v1/config" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,3 +1,3 @@
 curl -X GET \
-  "$FLOW_SERVER_URL/api/v1/version" \
+  "$FLOW_SERVER_URL/v1/version" \
  -H "accept: application/json"
@@ -6,7 +6,7 @@ export PROJECT_ID="${PROJECT_ID:-1415de42-8f01-4f36-bf34-539f23e47466}"

 # Use environment variables in API requests
 curl --request POST \
-  --url "$FLOW_SERVER_URL/api/v1/run/$FLOW_ID?stream=false" \
+  --url "$FLOW_SERVER_URL/v1/run/$FLOW_ID?stream=false" \
  --header "Content-Type: application/json" \
  --header "x-api-key: $FLOW_API_KEY" \
  --data '{
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_URL/api/v1/users/" \
+  "$FLOW_URL/v1/users/" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  -d '{
@@ -1,4 +1,4 @@
 curl -X DELETE \
-  "$FLOW_URL/api/v1/users/10c1c6a2-ab8a-4748-8700-0e4832fd5ce8" \
+  "$FLOW_URL/v1/users/10c1c6a2-ab8a-4748-8700-0e4832fd5ce8" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/users/whoami" \
+  "$FLOW_URL/v1/users/whoami" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_URL/api/v1/users/?skip=0&limit=10" \
+  "$FLOW_URL/v1/users/?skip=0&limit=10" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,5 +1,5 @@
 curl -X PATCH \
-  "$FLOW_URL/api/v1/users/10c1c6a2-ab8a-4748-8700-0e4832fd5ce8/reset-password" \
+  "$FLOW_URL/v1/users/10c1c6a2-ab8a-4748-8700-0e4832fd5ce8/reset-password" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  -d '{
@@ -1,5 +1,5 @@
 curl -X PATCH \
-  "$FLOW_URL/api/v1/users/10c1c6a2-ab8a-4748-8700-0e4832fd5ce8" \
+  "$FLOW_URL/v1/users/10c1c6a2-ab8a-4748-8700-0e4832fd5ce8" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  -d '{
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_SERVER_URL/api/v2/workflows" \
+  "$FLOW_SERVER_URL/v1/workflows" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  -d '{
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_SERVER_URL/api/v2/workflows/stop" \
+  "$FLOW_SERVER_URL/v1/workflows/stop" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  -d '{
@@ -1,4 +1,4 @@
 curl -X GET \
-  "$FLOW_SERVER_URL/api/v2/workflows?job_id=job_id_1234567890" \
+  "$FLOW_SERVER_URL/v1/workflows?job_id=job_id_1234567890" \
  -H "accept: application/json" \
  -H "x-api-key: $FLOW_API_KEY"
@@ -1,5 +1,5 @@
 curl -X POST \
-  "$FLOW_SERVER_URL/api/v2/workflows" \
+  "$FLOW_SERVER_URL/v1/workflows" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FLOW_API_KEY" \
  -d '{
@@ -1,4 +1,4 @@
-const url = `${process.env.FLOW_URL ?? ""}/api/v1/build/123e4567-e89b-12d3-a456-426614174000/events`;
+const url = `${process.env.FLOW_URL ?? ""}/v1/build/123e4567-e89b-12d3-a456-426614174000/events`;

 const options = {
  method: 'GET',
@@ -1,4 +1,4 @@
-const url = `${process.env.FLOW_URL ?? ""}/api/v1/build/123e4567-e89b-12d3-a456-426614174000/events?stream=false`;
+const url = `${process.env.FLOW_URL ?? ""}/v1/build/123e4567-e89b-12d3-a456-426614174000/events?stream=false`;

 const options = {
  method: 'GET',
@@ -1,4 +1,4 @@
-const url = `${process.env.FLOW_URL ?? ""}/api/v1/build/${process.env.FLOW_ID ?? ""}/flow`;
+const url = `${process.env.FLOW_URL ?? ""}/v1/build/${process.env.FLOW_ID ?? ""}/flow`;

 const options = {
  method: 'POST',
@@ -1,4 +1,4 @@
-const url = `${process.env.FLOW_URL ?? ""}/api/v1/build/${process.env.FLOW_ID ?? ""}/flow`;
+const url = `${process.env.FLOW_URL ?? ""}/v1/build/${process.env.FLOW_ID ?? ""}/flow`;

 const options = {
  method: 'POST',
@@ -1,4 +1,4 @@
-const url = `${process.env.FLOW_URL ?? ""}/api/v1/build/${process.env.FLOW_ID ?? ""}/flow`;
+const url = `${process.env.FLOW_URL ?? ""}/v1/build/${process.env.FLOW_ID ?? ""}/flow`;

 const options = {
  method: 'POST',
@@ -1,4 +1,4 @@
-const url = `${process.env.FLOW_URL ?? ""}/api/v2/files`;
+const url = `${process.env.FLOW_URL ?? ""}/v1/files`;

 const options = {
  method: 'DELETE',
@@ -1,4 +1,4 @@
-const url = `${process.env.FLOW_URL ?? ""}/api/v1/files/delete/${process.env.FLOW_ID ?? ""}/2024-12-30_15-19-43_your_file.txt`;
+const url = `${process.env.FLOW_URL ?? ""}/v1/files/delete/${process.env.FLOW_ID ?? ""}/2024-12-30_15-19-43_your_file.txt`;

 const options = {
  method: 'DELETE',
@@ -1,4 +1,4 @@
-const url = `${process.env.FLOW_URL ?? ""}/api/v2/files/${process.env.FILE_ID ?? ""}`;
+const url = `${process.env.FLOW_URL ?? ""}/v1/files/${process.env.FILE_ID ?? ""}`;

 const options = {
  method: 'DELETE',
@@ -1,4 +1,4 @@
-const url = `${process.env.FLOW_URL ?? ""}/api/v1/files/download/${process.env.FLOW_ID ?? ""}/2024-12-30_15-19-43_your_file.txt`;
+const url = `${process.env.FLOW_URL ?? ""}/v1/files/download/${process.env.FLOW_ID ?? ""}/2024-12-30_15-19-43_your_file.txt`;

 const options = {
  method: 'GET',
@@ -1,4 +1,4 @@
-const url = `${process.env.FLOW_URL ?? ""}/api/v2/files/c7b22c4c-d5e0-4ec9-af97-5d85b7657a34`;
+const url = `${process.env.FLOW_URL ?? ""}/v1/files/c7b22c4c-d5e0-4ec9-af97-5d85b7657a34`;

 const options = {
  method: 'GET',
@@ -1,4 +1,4 @@
-const url = `${process.env.FLOW_URL ?? ""}/api/v2/files/${process.env.FILE_ID ?? ""}?name=new_file_name`;
+const url = `${process.env.FLOW_URL ?? ""}/v1/files/${process.env.FILE_ID ?? ""}?name=new_file_name`;

 const options = {
  method: 'PUT',
@@ -1,4 +1,4 @@
-const url = `${process.env.FLOW_URL ?? ""}/api/v1/files/list/${process.env.FLOW_ID ?? ""}`;
+const url = `${process.env.FLOW_URL ?? ""}/v1/files/list/${process.env.FLOW_ID ?? ""}`;

 const options = {
  method: 'GET',
@@ -1,4 +1,4 @@
-const url = `${process.env.FLOW_URL ?? ""}/api/v2/files`;
+const url = `${process.env.FLOW_URL ?? ""}/v1/files`;

 const options = {
  method: 'GET',
@@ -1,4 +1,4 @@
-const url = `${process.env.FLOW_URL ?? ""}/api/v1/run/${process.env.FLOW_ID ?? ""}`;
+const url = `${process.env.FLOW_URL ?? ""}/v1/run/${process.env.FLOW_ID ?? ""}`;

 const options = {
  method: 'POST',
--- a/Show More
+++ b/Show More