Get started with Robility flow API

The Robility Flow API allows you to interact with Robility programmatically. You can use it to:

1. Create and manage flows, including file handling.
2. Develop applications that integrate with your flows.
3. Build and deploy custom components.
4. Use Robility Flow as part of a larger system.
5. Contribute to the Robility Flow open platform.

Quickstart Example

For a hands-on introduction, see the Robility Flow Quickstart. It demonstrates how to:

1. Retrieve auto-generated API code snippets.
2. Run a flow from a script.
3. Parse data from the Robility Flow API response.

Form Robility API Requests

While options vary by endpoint, all Robility Flow API requests follow a consistent structure—using a base URL, HTTP method, parameters, and authentication.

As an example of a Robilityflow 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:

Example: Run a Flow with curl

curl –request POST \

  –url “$ROBILITY_FLOW_SERVER_URL/api/v1/run/$FLOW_ID?stream=false” \

  –header “Content-Type: application/json” \

  –header “x-api-key: $ROBILITY_FLOW_API_KEY” \

  –data ‘{

    “input_value”: “hello world!”,

    “output_type”: “chat”,

    “input_type”: “chat”,

    “tweaks”: {

      “ChatOutput-6zcZt”: {

        “should_store_message”: true

      }

    }

  }’

Base URL

By default, local Robility Flow deployments are hosted at:

a. http://localhost:7860/api

For remote deployments, the URL will depend on your configuration. Examples:

a. https://UUID.ngrok.app/api
b. http://IP_OR_DNS/api
c. http://IP_OR_DNS:ROBILITY_FLOW_PORT/api

The port number can be configured using the ROBILITY_FLOW_PORT environment variable.

Authentication

As of Robility Flow version, most endpoints require an API key—even when AUTO_LOGIN=True. The only exceptions are MCP-related endpoints:

1. /v1/mcp
2. /v1/mcp-projects
3. /v2/mcp

To authenticate, include your Robility Flow API key via: x-api-key header or ?x-api-key=… query parameter

For more information, see 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 for your API keys and then reference those environment variables in your API requests.

Supported HTTP Methods and Parameters

Each endpoint uses different combinations of:

a. HTTP Methods (GET, POST, etc.)
b. Path and query parameters
c. JSON-formatted request bodies

Example: Create and Run a Flow

1. Create a flow:
POST /v1/flows with a flow definition in the body.

2. Run a flow:
POST /v1/run/$FLOW_ID with optional runtime parameters.

API Versions

Robility Flow supports both /v1 and /v2 endpoints. Some endpoints are exclusive to one version. If a request doesn’t behave as expected, verify that the path uses the correct version.

Setting Environment Variables

Store commonly used values in environment variables for security and convenience. Here’s an example:

# Set variables

export ROBILITY_FLOW_API_KEY=”sk-…”

export ROBILITY_FLOW_SERVER_URL=”http://localhost:7860″

export FLOW_ID=”359cd752-07ea-46f2-9d3b-a4407ef618da”

export PROJECT_ID=”1415de42-8f01-4f36-bf34-539f23e47466″

# Use them in a curl command

curl –request POST \

  –url “$ROBILITY_FLOW_SERVER_URL/api/v1/run/$FLOW_ID?stream=false” \

  –header “Content-Type: application/json” \

  –header “x-api-key: $ROBILITY_FLOW_API_KEY” \

  –data ‘{

    “input_value”: “hello world!”,

    “output_type”: “chat”,

    “input_type”: “chat”,

    “tweaks”: {

      “ChatOutput-6zcZt”: {

        “should_store_message”: true

      }

    }

  }’

Environment variables help manage:

• Server URLs
• API keys
• Flow and project IDs

Flow IDs can be retrieved from:

• The API Access pane
• The flow’s URL
• The GET /flows endpoint

Try These Useful API Requests

Get Robility Flow Version

curl -X GET \

  “$ROBILITY_FLOW_SERVER_URL/api/v1/version” \

  -H “accept: application/json” \

  -H “x-api-key: $ROBILITY_FLOW_API_KEY”

Result:

{

    “version”: “1.1”,
    “main_version”: “1.1.1”,
    “package”: “Robilityflow”

}

Get Deployment Configuration

curl -X GET \

  “$ROBILITY_FLOW_SERVER_URL/api/v1/config” \

  -H “accept: application/json” \

  -H “x-api-key: $ROBILITY_FLOW_API_KEY”

 Result:

{

  “feature_flags”: {

    “mvp_components”: false

  },

  “frontend_timeout”: 0,

  “auto_saving”: true,

  “auto_saving_interval”: 1000,

  “health_check_max_retries”: 5,

  “max_file_size_upload”: 100

}

Get All Components

curl -X GET \

  “$ROBILITY_FLOW_SERVER_URL/api/v1/all” \

  -H “accept: application/json” \

  -H “x-api-key: $ROBILITY_FLOW_API_KEY”

Available endpoints

Because you can run Robility 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 Robility flow database, or enabling frontend functionality, like the Playground. Unless you are contributing to the Robility flow codebase, you won’t directly call most of the Robility flow endpoints.

For application development, the most commonly used endpoints are the /run and /webhook flow trigger endpoints. 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.

1. Application development
2. Custom components
3. MCP servers and clients
4. Codebase development
5. Deprecated

Application development

The following endpoints are useful for developing applications with Robility flow and administering Robility 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.

1. Flow trigger endpoints:

a. POST /v1/run/{flow_id_or_name}: Run a flow.
b. POST /v1/run/advanced/{flow_id}: Advanced run with explicit inputs, outputs, tweaks, and optional session_id.
c. POST /v1/webhook/{flow_id_or_name}: Trigger a flow via webhook payload.

2. Deployment details:

a. GET /v1/version: Return Robility flow version. See Get version.
b. GET /v1/config: Return deployment configuration. See Get configuration.

3. Projects endpoints:

a. POST /v1/projects/: Create a project.
b. GET /v1/projects/: List projects.
c. GET /v1/projects/{project_id}: Read a project (with paginated flows support).
d. PATCH /v1/projects/{project_id}: Update project info and membership.
e. DELETE /v1/projects/{project_id}: Delete a project.
f. GET /v1/projects/download/{project_id}: Export all flows in a project as ZIP.
g. POST /v1/projects/upload/: Import a project ZIP (creates project and flows).
h. GET /v1/starter-projects/: Return a list of templates.

4. Files endpoints:

Files (v1)

a. POST /v1/files/upload/{flow_id}: Upload a file to a specific flow.
b. GET /v1/files/download/{flow_id}/{file_name}: Download a file from a flow.
c. GET /v1/files/images/{flow_id}/{file_name}: Stream an image from a flow.
d. GET /v1/files/profile_pictures/{folder_name}/{file_name}: Get a profile picture asset.
e. GET /v1/files/profile_pictures/list: List available profile picture assets.
f. GET /v1/files/list/{flow_id}: List files for a flow.
g. DELETE /v1/files/delete/{flow_id}/{file_name}: Delete a file from a flow.

Files (v2)

a. POST /v2/files (alias /v2/files/): Upload a file owned by the current user.
b. GET /v2/files (alias /v2/files/): List files owned by the current user.
c. DELETE /v2/files/batch/: Delete multiple files by IDs.
d. POST /v2/files/batch/: Download multiple files as a ZIP by IDs.
e. GET /v2/files/{file_id}: Download a file by ID (or return raw content internally).
f. PUT /v2/files/{file_id}: Edit a file name by ID.
g. DELETE /v2/files/{file_id}: Delete a file by ID.
h. DELETE /v2/files (alias /v2/files/): Delete all files for the current user.

5. API keys and authentication:

a. GET /v1/api_key/: List API keys for the current user.
b. POST /v1/api_key/: Create a new API key.
c. DELETE /v1/api_key/{api_key_id}: Delete an API key.
d. POST /v1/api_key/store: Save an encrypted Store API key (cookie set).

6. Flow management endpoints:

a. POST /v1/flows/: Create a flow.
b. GET /v1/flows/: List flows (supports pagination and filters).
c. GET /v1/flows/{flow_id}: Read a flow by ID.
d. GET /v1/flows/public_flow/{flow_id}: Read a public flow by ID.
e. PATCH /v1/flows/{flow_id}: Update a flow.
f. DELETE /v1/flows/{flow_id}: Delete a flow.
g. POST /v1/flows/batch/: Create multiple flows.
h. POST /v1/flows/upload/: Import flows from a JSON file.
i. DELETE /v1/flows/: Delete multiple flows by IDs.
j. POST /v1/flows/download/: Export flows to a ZIP file.
k. GET /v1/flows/basic_examples/: List basic example flows.

7. Users endpoints:

a. POST /v1/users/: Add a user (superuser required when auth enabled).
b. GET /v1/users/whoami: Return the current authenticated user.
c. GET /v1/users/: List all users (superuser required).
d. PATCH /v1/users/{user_id}: Update a user (with role checks).
e.PATCH /v1/users/{user_id}/reset-password: Reset own password.
f. DELETE /v1/users/{user_id}: Delete a user (cannot delete yourself).

Custom components

You might use these endpoints when developing custom Robility flow components for your own use or to share with the Robility flow community:

1. Develop custom components:

a. GET /v1/all: Return all available Robility flow component types. See Get all components.
b. POST /v1/custom_component: Build a custom component from code and return its node.
c. POST /v1/custom_component/update: Update an existing custom component’s build config and outputs.
d. POST /v1/validate/code: Validate a Python code snippet for a custom component.

2. Robility flow Store:

a. GET /v1/store/check/: Return whether the Store feature is enabled.
b. GET /v1/store/check/api_key: Check if a Store API key exists and is valid.
c. POST /v1/store/components/: Share a component to the Store.
d. PATCH /v1/store/components/{component_id}: Update a shared component.
e. GET /v1/store/components/: List available Store components (filters supported).
f. GET /v1/store/components/{component_id}: Download a component from the Store.
g. GET /v1/store/tags: List Store tags.
h. GET /v1/store/users/likes: List components liked by the current user.
i. POST /v1/store/users/likes/{component_id}: Like a component.

MCP Serves and clients

The following endpoints are for managing Robility flow  MCP servers, both Robility flow -hosted MCP servers and external MCP server connections:

1. MCP (global):

a. HEAD /v1/mcp/sse: Health check for MCP SSE.
b. GET /v1/mcp/sse: Open SSE stream for MCP server events.
c. POST /v1/mcp/: Post messages to the MCP server.

2. MCP (project-specific):

a. GET /v1/mcp/project/{project_id}: List MCP-enabled tools and project auth settings.
b. HEAD /v1/mcp/project/{project_id}/sse: Health check for project SSE.
c. GET /v1/mcp/project/{project_id}/sse: Open project-scoped MCP SSE.
d. POST /v1/mcp/project/{project_id}: Post messages to project MCP server.
e. POST /v1/mcp/project/{project_id}/ (trailing slash): Same as above.
f. PATCH /v1/mcp/project/{project_id}: Update MCP settings for flows and project auth settings.
g. POST /v1/mcp/project/{project_id}/install: Install MCP client config for Cursor/Windsurf/Claude (local only).
h. GET /v1/mcp/project/{project_id}/installed: Check which clients have MCP config installed.

Code base development

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

1. Base (metadata):

a. GET /v1/all: Return all available Robility flow component types. See Get all components.
b. GET /v1/version: Return Robility flow version. See Get version.
c. GET /v1/config: Return deployment configuration. See Get configuration.
d. GET /v1/starter-projects/: Return a list of templates.

2. Build endpoints (internal editor support):

a. POST /v1/build/{flow_id}/flow: Start a flow build and return a job ID.
b. GET /v1/build/{job_id}/events: Stream or fetch build events.
c. POST /v1/build/{job_id}/cancel: Cancel a build job.
d. POST /v1/build_public_tmp/{flow_id}/flow: Build a public flow without auth.
e. POST /v1/validate/prompt: Validate a prompt payload.

3. API keys and authentication:

a. POST /v1/login: Login and set tokens as cookies.
b. GET /v1/auto_login: Auto-login (if enabled) and set tokens.
c. POST /v1/refresh: Refresh tokens using refresh cookie.
d. POST /v1/logout: Logout and clear cookies.

4. Monitor endpoints:

a. GET /v1/monitor/builds: Get vertex builds for a flow.
b. DELETE /v1/monitor/builds: Delete vertex builds for a flow.
c. GET /v1/monitor/messages/sessions: List message session IDs (auth required).
d. GET /v1/monitor/messages: List messages with optional filters.
e. DELETE /v1/monitor/messages: Delete messages by IDs (auth required).
f. PUT /v1/monitor/messages/{message_id}: Update a message.
g. PATCH /v1/monitor/messages/session/{old_session_id}: Change a session ID for all messages in that session.
h. DELETE /v1/monitor/messages/session/{session_id}: Delete messages by session.
i. GET /v1/monitor/transactions: List transactions for a flow (paginated).

5. Variables:

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

6. Use voice mode:

a. WS /v1/voice/ws/flow_as_tool/{flow_id}: Bi-directional voice session exposing the flow as a tool.
b. WS /v1/voice/ws/flow_as_tool/{flow_id}/{session_id}: Same as above with explicit session ID.
c. WS /v1/voice/ws/flow_tts/{flow_id}: Voice-to-text session that runs a flow and returns TTS.
d. WS /v1/voice/ws/flow_tts/{flow_id}/{session_id}: Same as above with explicit session ID.
e. GET /v1/voice/elevenlabs/voice_ids: List available ElevenLabs voice IDs for the user.

Deprecated

The following endpoints are deprecated:

a. POST /v1/predict/{flow_id}: Use /v1/run/{flow_id} instead.
b. POST /v1/process/{flow_id}: Use /v1/run/{flow_id} instead.
c. GET /v1/task/{task_id}: Deprecated functionality.
d. POST /v1/upload/{flow_id}: Use /files instead.
e. POST /v1/build/{flow_id}/vertices: Replaced by /monitor/builds.
f. POST /v1/build/{flow_id}/vertices/{vertex_id}: Replaced by /monitor/builds.
g. GET /v1/build/{flow_id}/{vertex_id}/stream: Replaced by /monitor/builds.