flow/docs/versioned_docs/version-1.9.0/API-Reference/api-reference-api-examples.mdx

---
title: Get started with the Hanzo Flow API
slug: /api-reference-api-examples
---
import CodeSnippet from '@site/src/components/CodeSnippet';
import exampleApiReferenceApiExamplesFormHanzo FlowApiRequests from '!!raw-loader!@site/docs/API-Reference/curl-examples/api-reference-api-examples/form-flow-api-requests.sh';
import exampleApiReferenceApiExamplesSetEnvironmentVariables from '!!raw-loader!@site/docs/API-Reference/curl-examples/api-reference-api-examples/set-environment-variables.sh';
import exampleApiReferenceApiExamplesHealthCheck from '!!raw-loader!@site/docs/API-Reference/curl-examples/api-reference-api-examples/health-check.sh';
import resultApiReferenceApiExamplesResultHealthCheck from '!!raw-loader!@site/docs/API-Reference/curl-examples/api-reference-api-examples/result-health-check.json';
import exampleApiReferenceApiExamplesGetVersion from '!!raw-loader!@site/docs/API-Reference/curl-examples/api-reference-api-examples/get-version.sh';
import resultApiReferenceApiExamplesResultGetVersion from '!!raw-loader!@site/docs/API-Reference/curl-examples/api-reference-api-examples/result-get-version.txt';
import exampleApiReferenceApiExamplesGetConfiguration from '!!raw-loader!@site/docs/API-Reference/curl-examples/api-reference-api-examples/get-configuration.sh';
import resultApiReferenceApiExamplesResultGetConfiguration from '!!raw-loader!@site/docs/API-Reference/curl-examples/api-reference-api-examples/result-get-configuration.json';
import exampleApiReferenceApiExamplesGetAllComponents from '!!raw-loader!@site/docs/API-Reference/curl-examples/api-reference-api-examples/get-all-components.sh';
import examplePythonApiReferenceApiExamplesFormHanzo FlowApiRequests from '!!raw-loader!@site/docs/API-Reference/python-examples/api-reference-api-examples/form-flow-api-requests.py';
import exampleJavascriptApiReferenceApiExamplesFormHanzo FlowApiRequests from '!!raw-loader!@site/docs/API-Reference/javascript-examples/api-reference-api-examples/form-flow-api-requests.js';
import examplePythonApiReferenceApiExamplesHealthCheck from '!!raw-loader!@site/docs/API-Reference/python-examples/api-reference-api-examples/health-check.py';
import exampleJavascriptApiReferenceApiExamplesHealthCheck from '!!raw-loader!@site/docs/API-Reference/javascript-examples/api-reference-api-examples/health-check.js';
import examplePythonApiReferenceApiExamplesGetVersion from '!!raw-loader!@site/docs/API-Reference/python-examples/api-reference-api-examples/get-version.py';
import exampleJavascriptApiReferenceApiExamplesGetVersion from '!!raw-loader!@site/docs/API-Reference/javascript-examples/api-reference-api-examples/get-version.js';
import examplePythonApiReferenceApiExamplesGetConfiguration from '!!raw-loader!@site/docs/API-Reference/python-examples/api-reference-api-examples/get-configuration.py';
import exampleJavascriptApiReferenceApiExamplesGetConfiguration from '!!raw-loader!@site/docs/API-Reference/javascript-examples/api-reference-api-examples/get-configuration.js';
import examplePythonApiReferenceApiExamplesGetAllComponents from '!!raw-loader!@site/docs/API-Reference/python-examples/api-reference-api-examples/get-all-components.py';
import exampleJavascriptApiReferenceApiExamplesGetAllComponents from '!!raw-loader!@site/docs/API-Reference/javascript-examples/api-reference-api-examples/get-all-components.js';



import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

You can use the Hanzo Flow API for programmatic interactions with Hanzo Flow, such as the following:

* Create and edit flows, including file management for flows.
* Develop applications that use your flows.
* Develop custom components.
* Build Hanzo Flow as a dependency of a larger application, codebase, or service.
* Contribute to the overall Hanzo Flow codebase.

To view and test all available endpoints, you can access the Hanzo Flow API's OpenAPI specification at your Hanzo Flow deployment's `/docs` endpoint, such as `http://localhost:7860/docs`.

:::tip Try it
For an example of the Hanzo Flow API in a script, see the [Hanzo Flow quickstart](/get-started-quickstart).

The quickstart demonstrates how to get automatically generated code snippets for your flows, use a script to run a flow, and extract data from the Langfow API response.
:::

## Form Hanzo Flow API requests

While individual options vary by endpoint, all Hanzo Flow API requests share some commonalities, like a URL, method, parameters, and authentication.

As an example of a Hanzo Flow API request, the following curl command calls the `/v1/run` endpoint, and it passes a runtime override (`tweaks`) to the flow's **Chat Output** component:

<Tabs>
<TabItem value="Python" label="Python" default>

<CodeSnippet source={examplePythonApiReferenceApiExamplesFormHanzo FlowApiRequests} language="python" />

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

<CodeSnippet source={exampleJavascriptApiReferenceApiExamplesFormHanzo FlowApiRequests} language="javascript" />

</TabItem>
<TabItem value="curl" label="curl">

<CodeSnippet source={exampleApiReferenceApiExamplesFormHanzo FlowApiRequests} language="bash" />

</TabItem>
</Tabs>

### Base URL

By default, local deployments serve the Hanzo Flow API at `http://localhost:7860/api`.

Remotely hosted Hanzo Flow deployments are available at the domain set by the hosting service, such as `http://IP_OR_DNS/api` or `http://IP_OR_DNS:FLOW_PORT/api`.

You can configure the Hanzo Flow port number in the `FLOW_PORT` [environment variable](/environment-variables).

* `https://UUID.ngrok.app/api`
* `http://IP_OR_DNS/api`
* `http://IP_OR_DNS:FLOW_PORT/api`

### Authentication

In Hanzo Flow versions 1.5 and later, most API endpoints require authentication with a Hanzo Flow API key in either an `x-api-key` header or query parameter.
For more information, see [API keys and authentication](/api-keys-and-authentication).

As with any API, follow industry best practices for storing and referencing sensitive credentials.
For example, you can [set environment variables](#set-environment-variables) for your API keys, and then reference those environment variables in your API requests.

### Methods, paths, and parameters

Hanzo Flow API requests use various methods, paths, path parameters, query parameters, and body parameters.
The specific requirements and options depend on the endpoint that you want to call.

For example, to create a flow, you pass a JSON-formatted flow definition to `POST /v1/flows`.
Then, to run your flow, you call `POST /v1/run/$FLOW_ID` with optional run parameters in the request body.

### API versions

The Hanzo Flow API serves `/v1` and `/v2` endpoints.

Some endpoints only exist under a single version and some exist under both the `/v1` and `/v2` versions.

If a request fails or has an unexpected result, make sure your endpoint path has the correct version.

## Set environment variables

You can store commonly used values in environment variables to facilitate reuse, simplify token rotation, and securely reference sensitive values.

You can use any method you prefer to set environment variables, such as `export`, `.env`, `zshrc`, or `.curlrc`.
Then, reference those environment variables in your API requests.
For example:

<CodeSnippet source={exampleApiReferenceApiExamplesSetEnvironmentVariables} language="bash" />

Commonly used values in Hanzo Flow API requests include your [Hanzo Flow server URL](#base-url), [Hanzo Flow API keys](#authentication), flow IDs, and [project IDs](/api-projects#read-projects).

You can retrieve flow IDs from the [**API access** pane](/concepts-publish#api-access), in a flow's URL, and with [`GET /flows`](/api-flows#read-flows).

## Try some Hanzo Flow API requests

Once you have your Hanzo Flow server URL, try calling these endpoints that return Hanzo Flow metadata.

### Health check

Returns the health status of the Hanzo Flow database and chat services:

<Tabs>
<TabItem value="Python" label="Python" default>

<CodeSnippet source={examplePythonApiReferenceApiExamplesHealthCheck} language="python" />

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

<CodeSnippet source={exampleJavascriptApiReferenceApiExamplesHealthCheck} language="javascript" />

</TabItem>
<TabItem value="curl" label="curl">

<CodeSnippet source={exampleApiReferenceApiExamplesHealthCheck} language="bash" />

</TabItem>
</Tabs>

<details>
<summary>Result</summary>

<CodeSnippet source={resultApiReferenceApiExamplesResultHealthCheck} language="json" />

</details>

Hanzo Flow provides an additional `GET /health` endpoint.
This endpoint is served by uvicorn before Hanzo Flow is fully initialized, so it's not reliable for checking Hanzo Flow service health.

### Get version

Returns the current Hanzo Flow API version:

<Tabs>
<TabItem value="Python" label="Python" default>

<CodeSnippet source={examplePythonApiReferenceApiExamplesGetVersion} language="python" />

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

<CodeSnippet source={exampleJavascriptApiReferenceApiExamplesGetVersion} language="javascript" />

</TabItem>
<TabItem value="curl" label="curl">

<CodeSnippet source={exampleApiReferenceApiExamplesGetVersion} language="bash" />

</TabItem>
</Tabs>

<details>
<summary>Result</summary>

<CodeSnippet source={resultApiReferenceApiExamplesResultGetVersion} language="text" />

</details>

### Get configuration

Returns configuration details for your Hanzo Flow deployment.
Requires a [Hanzo Flow API key](/api-keys-and-authentication).

<Tabs>
<TabItem value="Python" label="Python" default>

<CodeSnippet source={examplePythonApiReferenceApiExamplesGetConfiguration} language="python" />

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

<CodeSnippet source={exampleJavascriptApiReferenceApiExamplesGetConfiguration} language="javascript" />

</TabItem>
<TabItem value="curl" label="curl">

<CodeSnippet source={exampleApiReferenceApiExamplesGetConfiguration} language="bash" />

</TabItem>
</Tabs>

<details>
<summary>Result</summary>

<CodeSnippet source={resultApiReferenceApiExamplesResultGetConfiguration} language="json" />

</details>

### Get all components

Returns a dictionary of all Hanzo Flow components.
Requires a [Hanzo Flow API key](/api-keys-and-authentication).

<Tabs>
<TabItem value="Python" label="Python" default>

<CodeSnippet source={examplePythonApiReferenceApiExamplesGetAllComponents} language="python" />

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

<CodeSnippet source={exampleJavascriptApiReferenceApiExamplesGetAllComponents} language="javascript" />

</TabItem>
<TabItem value="curl" label="curl">

<CodeSnippet source={exampleApiReferenceApiExamplesGetAllComponents} language="bash" />

</TabItem>
</Tabs>

## Available endpoints

Because you can run Hanzo Flow as either an IDE (frontend and backend) or a runtime (headless, backend-only), it serves endpoints that support frontend and backend operations.
Many endpoints are for orchestration between the frontend and backend, reading and writing to the Hanzo Flow database, or enabling frontend functionality, like the **Playground**.
Unless you are contributing to the Hanzo Flow codebase, you won't directly call most of the Hanzo Flow endpoints.

For application development, the most commonly used endpoints are the `/run` and `/webhook` [flow trigger endpoints](/api-flows-run).
For some use cases, you might use some other endpoints, such as the `/files` endpoints to use files in flows.

To help you explore the available endpoints, the following lists are sorted by primary use case, although some endpoints might support multiple use cases.

<Tabs>
<TabItem value="Application development" label="Application development" default>

The following endpoints are useful for developing applications with Hanzo Flow and administering Hanzo Flow deployments with one or more users.
You will most often use the flow trigger endpoints.
Other endpoints are helpful for specific use cases, such as administration and flow management in runtime deployments that don't have a visual editor.

* [Flow trigger endpoints](/api-flows-run):
  * POST `/v1/run/{flow_id_or_name}`: Run a flow.
  * POST `/v1/run/advanced/{flow_id}`: Advanced run with explicit `inputs`, `outputs`, `tweaks`, and optional `session_id`.
  * POST `/v1/webhook/{flow_id_or_name}`: Trigger a flow via webhook payload.

* [OpenAI Responses API](/api-openai-responses):
  * POST `/v1/responses`: Execute flows using an OpenAI-compatible request format.

* Deployment details:
  * GET `/v1/version`: Return Hanzo Flow version. See [Get version](/api-reference-api-examples#get-version).
  * GET `/v1/config`: Return deployment configuration. See [Get configuration](/api-reference-api-examples#get-configuration).
  * GET `/health_check`: Health check endpoint that validates database and chat service connectivity. Returns 500 status if any service is unavailable.

* [Projects endpoints](/api-projects):
  * POST `/v1/projects/`: Create a project.
  * GET `/v1/projects/`: List projects.
  * GET `/v1/projects/{project_id}`: Read a project (with paginated flows support).
  * PATCH `/v1/projects/{project_id}`: Update project info and membership.
  * DELETE `/v1/projects/{project_id}`: Delete a project.
  * GET `/v1/projects/download/{project_id}`: Export all flows in a project as ZIP.
  * POST `/v1/projects/upload/`: Import a project ZIP (creates project and flows).
  * GET `/v1/starter-projects/`: Return a list of templates.

* [Files endpoints](/api-files):
  * Files (v1)
    * POST `/v1/files/upload/{flow_id}`: Upload a file to a specific flow.
    * GET `/v1/files/download/{flow_id}/{file_name}`: Download a file from a flow.
    * GET `/v1/files/images/{flow_id}/{file_name}`: Stream an image from a flow.
    * GET `/v1/files/profile_pictures/{folder_name}/{file_name}`: Get a profile picture asset.
    * GET `/v1/files/profile_pictures/list`: List available profile picture assets.
    * 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 `/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.
  * POST `/v1/api_key/`: Create a new API key.
  * DELETE `/v1/api_key/{api_key_id}`: Delete an API key.
  * POST `/v1/api_key/store`: Save an encrypted Store API key (cookie set).

* [Flow management endpoints](/api-flows):
  * POST `/v1/flows/`: Create a flow.
  * GET `/v1/flows/`: List flows (supports pagination and filters).
  * GET `/v1/flows/{flow_id}`: Read a flow by ID.
  * GET `/v1/flows/public_flow/{flow_id}`: Read a public flow by ID.
  * PATCH `/v1/flows/{flow_id}`: Update a flow.
  * DELETE `/v1/flows/{flow_id}`: Delete a flow.
  * POST `/v1/flows/batch/`: Create multiple flows.
  * POST `/v1/flows/upload/`: Import flows from a JSON file.
  * DELETE `/v1/flows/`: Delete multiple flows by IDs.
  * POST `/v1/flows/download/`: Export flows to a ZIP file.
  * GET `/v1/flows/basic_examples/`: List basic example flows.

* [Users endpoints](/api-users):
  * POST `/v1/users/`: Add a user (superuser required when auth enabled).
  * GET `/v1/users/whoami`: Return the current authenticated user.
  * GET `/v1/users/`: List all users (superuser required).
  * PATCH `/v1/users/{user_id}`: Update a user (with role checks).
  * PATCH `/v1/users/{user_id}/reset-password`: Reset own password.
  * DELETE `/v1/users/{user_id}`: Delete a user (cannot delete yourself).

* Custom components: You might use these endpoints when developing custom Hanzo Flow components for your own use or to share with the Hanzo Flow community:
  * GET `/v1/all`: Return all available Hanzo Flow component types. See [Get all components](/api-reference-api-examples#get-all-components).
  * POST `/v1/custom_component`: Build a custom component from code and return its node.
  * POST `/v1/custom_component/update`: Update an existing custom component's build config and outputs.
  * POST `/v1/validate/code`: Validate a Python code snippet for a custom component.
  * POST `/v1/validate/prompt`: Validate a prompt payload.

</TabItem>
<TabItem value="Codebase contribution" label="Codebase development">

The following endpoints are most often used when contributing to the Hanzo Flow codebase, and you need to understand or call endpoints that support frontend-to-backend orchestration or other internal functionality.

* Base (metadata):
  * GET `/v1/all`: Return all available Hanzo Flow component types. See [Get all components](/api-reference-api-examples#get-all-components).
  * GET `/v1/version`: Return Hanzo Flow version. See [Get version](/api-reference-api-examples#get-version).
  * GET `/v1/config`: Return deployment configuration. See [Get configuration](/api-reference-api-examples#get-configuration).
  * GET `/v1/starter-projects/`: Return a list of templates.

* [Build endpoints](/api-build) (internal editor support):
  * POST `/v1/build/{flow_id}/flow`: Start a flow build and return a job ID.
  * GET `/v1/build/{job_id}/events`: Stream or fetch build events.
  * POST `/v1/build/{job_id}/cancel`: Cancel a build job.
  * POST `/v1/build_public_tmp/{flow_id}/flow`: Build a public flow without auth.
  * POST `/v1/validate/prompt`: Validate a prompt payload.

* [API keys and authentication](/api-keys-and-authentication):
  * POST `/v1/login`: Login and set tokens as cookies.
  * GET `/v1/auto_login`: Auto-login (if enabled) and set tokens.
  * POST `/v1/refresh`: Refresh tokens using refresh cookie.
  * POST `/v1/logout`: Logout and clear cookies.

* [Monitor endpoints](/api-monitor):
  * GET `/v1/monitor/builds`: Get vertex builds for a flow.
  * DELETE `/v1/monitor/builds`: Delete vertex builds for a flow.
  * GET `/v1/monitor/messages/sessions`: List message session IDs (auth required).
  * GET `/v1/monitor/messages`: List messages with optional filters.
  * DELETE `/v1/monitor/messages`: Delete messages by IDs (auth required).
  * PUT `/v1/monitor/messages/{message_id}`: Update a message.
  * PATCH `/v1/monitor/messages/session/{old_session_id}`: Change a session ID for all messages in that session.
  * DELETE `/v1/monitor/messages/session/{session_id}`: Delete messages by session.
  * GET `/v1/monitor/transactions`: List transactions for a flow (paginated).

* Variables:
  * POST `/v1/variables/`: Create a variable, such as an API key, for the user.
  * GET `/v1/variables/`: List variables for the user.
  * PATCH `/v1/variables/{variable_id}`: Update a variable.
  * DELETE `/v1/variables/{variable_id}`: Delete a variable.

* [Use voice mode](/concepts-voice-mode):
  * WS `/v1/voice/ws/flow_as_tool/{flow_id}`: Bi-directional voice session exposing the flow as a tool.
  * WS `/v1/voice/ws/flow_as_tool/{flow_id}/{session_id}`: Same as above with explicit session ID.
  * WS `/v1/voice/ws/flow_tts/{flow_id}`: Voice-to-text session that runs a flow and returns TTS.
  * WS `/v1/voice/ws/flow_tts/{flow_id}/{session_id}`: Same as above with explicit session ID.
  * GET `/v1/voice/elevenlabs/voice_ids`: List available ElevenLabs voice IDs for the user.

* MCP servers: The following endpoints are for managing Hanzo Flow MCP servers and MCP server connections.
They aren't typically called directly; instead, they are used to drive internal functionality in the Hanzo Flow frontend and when running flows that call MCP servers.
Hanzo Flow MCP servers support both streamable HTTP and SSE transport.
  * HEAD `/v1/mcp/streamable`: Health check for streamable HTTP MCP.
  * GET `/v1/mcp/streamable`: Open streamable HTTP connection for MCP server.
  * POST `/v1/mcp/streamable`: Post messages to the MCP server via streamable HTTP.
  * DELETE `/v1/mcp/streamable`: Close streamable HTTP connection.
  * HEAD `/v1/mcp/sse` (LEGACY): Health check for MCP SSE.
  * GET `/v1/mcp/sse` (LEGACY): Open SSE stream for MCP server events.
  * POST `/v1/mcp/` (LEGACY): Post messages to the MCP server.
  * GET `/v1/mcp/project/{project_id}`: List MCP-enabled tools and project auth settings.
  * HEAD `/v1/mcp/project/{project_id}/streamable`: Health check for project streamable HTTP MCP.
  * GET `/v1/mcp/project/{project_id}/streamable`: Open project-scoped streamable HTTP connection.
  * POST `/v1/mcp/project/{project_id}/streamable`: Post messages to project MCP server via streamable HTTP.
  * DELETE `/v1/mcp/project/{project_id}/streamable`: Close project streamable HTTP connection.
  * HEAD `/v1/mcp/project/{project_id}/sse` (LEGACY): Health check for project SSE.
  * GET `/v1/mcp/project/{project_id}/sse` (LEGACY): Open project-scoped MCP SSE.
  * POST `/v1/mcp/project/{project_id}` (LEGACY): Post messages to project MCP server.
  * PATCH `/v1/mcp/project/{project_id}`: Update MCP settings for flows and project auth settings.
  * POST `/v1/mcp/project/{project_id}/install`: Install MCP client config for Cursor/Windsurf/Claude (local only).
  * GET `/v1/mcp/project/{project_id}/installed`: Check which clients have MCP config installed.

* Custom components: You might use these endpoints when developing custom Hanzo Flow components for your own use or to share with the Hanzo Flow community:
  * GET `/v1/all`: Return all available Hanzo Flow component types. See [Get all components](/api-reference-api-examples#get-all-components).
  * POST `/v1/custom_component`: Build a custom component from code and return its node.
  * POST `/v1/custom_component/update`: Update an existing custom component's build config and outputs.
  * POST `/v1/validate/code`: Validate a Python code snippet for a custom component.
  * POST `/v1/validate/prompt`: Validate a prompt payload.

</TabItem>
<TabItem value="Deprecated" label="Deprecated">

The following endpoints are deprecated:

* POST `/v1/predict/{flow_id}`: Use [`/v1/run/{flow_id}`](/api-flows-run) instead.
* POST `/v1/process/{flow_id}`: Use [`/v1/run/{flow_id}`](/api-flows-run) instead.
* GET `/v1/task/{task_id}`: Deprecated functionality.
* POST `/v1/upload/{flow_id}`: Use [`/files`](/api-files) instead.
* POST `/v1/build/{flow_id}/vertices`: Replaced by [`/monitor/builds`](/api-monitor).
* POST `/v1/build/{flow_id}/vertices/{vertex_id}`: Replaced by [`/monitor/builds`](/api-monitor).
* GET `/v1/build/{flow_id}/{vertex_id}/stream`: Replaced by [`/monitor/builds`](/api-monitor).
* GET `/v1/store/check/`: Return whether the Store feature is enabled.
* GET `/v1/store/check/api_key`: Check if a Store API key exists and is valid.
* POST `/v1/store/components/`: Share a component to the Store.
* PATCH `/v1/store/components/{component_id}`: Update a shared component.
* GET `/v1/store/components/`: List available Store components (filters supported).
* GET `/v1/store/components/{component_id}`: Download a component from the Store.
* GET `/v1/store/tags`: List Store tags.
* GET `/v1/store/users/likes`: List components liked by the current user.
* POST `/v1/store/users/likes/{component_id}`: Like a component.

</TabItem>
</Tabs>

## Next steps

* Use the Hanzo Flow API to [run a flow](/api-flows-run).
* Use the Hanzo Flow API to [upload files](/api-files).
* Use the Hanzo Flow API to [get flow logs](/api-logs).
* Explore all endpoints in the [Hanzo Flow API specification](/api).