FlowDot API Reference - Developer Documentation

TL;DR - Quick Start:

Base URL: https://flowdot.ai/api/mcp/v1
Authentication: Bearer token in Authorization header
Get Token: Dashboard → Settings → MCP Tokens
Format: All requests return JSON responses

The FlowDot API is a RESTful API that lets you integrate workflows, custom nodes, and apps into your own applications. Use this reference to explore all available endpoints, authentication methods, and error handling.

107

Endpoints

16

Authentication

All API requests require a Bearer token. Generate tokens in your dashboard under Settings → MCP Tokens.

Request Header

Authorization: Bearer fd_mcp_xxxxxxxxxxxxx

Example Request

curl -X GET "https://flowdot.ai/api/mcp/v1/workflows" \
  -H "Authorization: Bearer fd_mcp_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Base URL

All API requests should be made to:

Production

https://flowdot.ai/api/mcp/v1

Authentication

POST

/api/auth/register

Create a new user account. Sends a verification email upon successful registrati...

▼

Create a new user account. Sends a verification email upon successful registration.

Example

curl -X POST https://flowdot.ai/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "securepassword123",
    "password_confirmation": "securepassword123"
  }'

Response

{
  "success": true,
  "message": "User registered successfully. Please check your email to verify your account.",
  "data": {
    "user": {
      "id": 123,
      "name": "John Doe",
      "email": "john@example.com",
      "avatar": null,
      "email_verified_at": null,
      "created_at": "2024-12-03T10:00:00.000000Z"
    },
    "token": "1|abcdef123456..."
  }
}

POST

/api/auth/register

Create a new user account with email and password.

▼

Create a new user account with email and password.

POST

/api/auth/login

Authenticate with email and password to receive a Bearer token for subsequent AP...

▼

Authenticate with email and password to receive a Bearer token for subsequent API requests.

Example

curl -X POST https://flowdot.ai/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "securepassword123"
  }'

Response

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": 123,
      "name": "John Doe",
      "email": "john@example.com"
    },
    "token": "1|abcdef123456..."
  }
}

POST

/api/auth/login

Authenticate user and receive access token.

▼

Authenticate user and receive access token.

GET

/api/auth/profile

Retrieve the authenticated user's profile information.

▼

Retrieve the authenticated user's profile information.

Authentication

Required - Include Bearer token in Authorization header.

Example

curl https://flowdot.ai/api/auth/profile \
  -H "Authorization: Bearer YOUR_TOKEN"

POST

/api/auth/logout

Invalidate current authentication token.

▼

Invalidate current authentication token.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/auth/profile

Retrieve authenticated user's profile information.

▼

Retrieve authenticated user's profile information.

Authentication

Required - Include Bearer token in Authorization header.

PUT

/api/auth/profile

Update authenticated user's profile information.

▼

Update authenticated user's profile information.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/auth/two-factor/enable

Generate 2FA secret and QR code for authenticator app setup.

▼

Generate 2FA secret and QR code for authenticator app setup.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/auth/two-factor/confirm

Verify 2FA setup with code from authenticator app.

▼

Verify 2FA setup with code from authenticator app.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/auth/two-factor/verify

Complete login by verifying 2FA code.

▼

Complete login by verifying 2FA code.

POST

/api/auth/two-factor/disable

Turn off 2FA for the account.

▼

Turn off 2FA for the account.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/cli/auth/initiate

Start the CLI device authorization flow. Returns an auth URL for the user to vis...

▼

Start the CLI device authorization flow. Returns an auth URL for the user to visit and confirm in their browser.

Example

flowdot auth login

# This will:
# 1. Call POST /api/cli/auth/initiate
# 2. Open the auth_url in your browser
# 3. Poll /api/cli/auth/verify until confirmed
# 4. Save the token securely in your system keychain

GET

/api/cli/auth/verify/{authToken}

Poll this endpoint to check if the user has confirmed the CLI authentication in...

▼

Poll this endpoint to check if the user has confirmed the CLI authentication in their browser.

Workflows

GET

/api/hub/workflows

Get all workflows owned by the authenticated user with optional pagination and f...

▼

Get all workflows owned by the authenticated user with optional pagination and filtering.

Authentication

Required - Include Bearer token in Authorization header.

Example

curl "https://flowdot.ai/api/hub/workflows?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "hash": "wf_abc123",
        "title": "My AI Workflow",
        "description": "Processes documents with GPT-4",
        "is_public": false,
        "created_at": "2024-12-03T10:00:00.000000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "hasNext": true
    }
  }
}

GET

/api/mcp/v1/workflows

Get all workflows for the authenticated user.

▼

Get all workflows for the authenticated user.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/hub/workflows/{id}

Retrieve a specific workflow by ID or hash. Public workflows can be accessed wit...

▼

Retrieve a specific workflow by ID or hash. Public workflows can be accessed without authentication.

Example

# Public workflow (no auth needed)
curl https://flowdot.ai/api/hub/workflows/wf_abc123

# Private workflow (auth required)
curl https://flowdot.ai/api/hub/workflows/wf_private123 \
  -H "Authorization: Bearer YOUR_TOKEN"

GET

/api/mcp/v1/workflows/{hash}

Get a specific workflow by hash.

▼

Get a specific workflow by hash.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/hub/workflows

Create a new workflow with nodes, edges, and configuration.

▼

Create a new workflow with nodes, edges, and configuration.

Authentication

Required - Include Bearer token in Authorization header.

Example

curl -X POST https://flowdot.ai/api/hub/workflows \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Document Processor",
    "description": "Analyzes documents with AI",
    "nodes": [...],
    "edges": [...],
    "is_public": false
  }'

POST

/api/mcp/v1/workflows

Create a new workflow.

▼

Create a new workflow.

Authentication

Required - Include Bearer token in Authorization header.

PUT

/api/hub/workflows/{id}

Update an existing workflow. Only the owner can update.

▼

Update an existing workflow. Only the owner can update.

Authentication

Required - Include Bearer token in Authorization header.

PUT

/api/mcp/v1/workflows/{hash}

Update an existing workflow.

▼

Update an existing workflow.

Authentication

Required - Include Bearer token in Authorization header.

DELETE

/api/hub/workflows/{id}

Delete a workflow. This action cannot be undone.

▼

Delete a workflow. This action cannot be undone.

Authentication

Required - Include Bearer token in Authorization header.

DELETE

/api/mcp/v1/workflows/{hash}

Delete a workflow.

▼

Delete a workflow.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/workflows/{hash}/execute

Execute a workflow with provided inputs.

▼

Execute a workflow with provided inputs.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/workflows/node-types

Get all available workflow node types.

▼

Get all available workflow node types.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/workflows/{hash}/duplicate

Create a copy of an existing workflow.

▼

Create a copy of an existing workflow.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/hub/workflows/{id}/execute-async

Execute a workflow asynchronously. Returns immediately with an execution ID for...

▼

Execute a workflow asynchronously. Returns immediately with an execution ID for status polling.

Authentication

Required - Include Bearer token in Authorization header.

Example

curl -X POST https://flowdot.ai/api/hub/workflows/wf_abc123/execute-async \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "document_url": "https://example.com/doc.pdf"
    }
  }'

Response

{
  "success": true,
  "data": {
    "execution_id": "exec_xyz789",
    "status": "queued"
  }
}

GET

/api/hub/workflows/public

Browse public workflows shared by the community.

▼

Browse public workflows shared by the community.

POST

/api/hub/workflows/{id}/vote

Upvote or downvote a public workflow.

▼

Upvote or downvote a public workflow.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/hub/favorites/{id}/toggle

Add or remove a workflow from your favorites.

▼

Add or remove a workflow from your favorites.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/hub/workflows/{id}/export-json

Export workflow definition as a portable JSON file.

▼

Export workflow definition as a portable JSON file.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/hub/workflows/{id}/export/python

Export workflow as executable Python code.

▼

Export workflow as executable Python code.

Authentication

Required - Include Bearer token in Authorization header.

Executions

GET

/api/hub/workflows/executions/{executionId}/status

Check the status of an async workflow execution.

▼

Check the status of an async workflow execution.

Authentication

Required - Include Bearer token in Authorization header.

Example

curl https://flowdot.ai/api/hub/workflows/executions/exec_xyz789/status \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "data": {
    "status": "completed",
    "progress": 100,
    "result": {
      "output": "Document analysis complete...",
      "summary": "..."
    }
  }
}

GET

/api/mcp/v1/executions/{id}

Get the status of a workflow execution.

▼

Get the status of a workflow execution.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/hub/user-executions

Get all workflow executions for the authenticated user.

▼

Get all workflow executions for the authenticated user.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/executions/{id}/stop

Stop a running workflow execution.

▼

Stop a running workflow execution.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/hub/executions/workflow/{workflowId}

Get execution history for a specific workflow.

▼

Get execution history for a specific workflow.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/workflows/{hash}/executions

Get execution history for a workflow.

▼

Get execution history for a workflow.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/executions/{id}/details

Get detailed execution data including node outputs.

▼

Get detailed execution data including node outputs.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/executions/{id}/pending-approvals

Get nodes waiting for human approval in an execution.

▼

Get nodes waiting for human approval in an execution.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/executions/{id}/approvals/{nodeId}

Approve or reject a pending human-in-the-loop request.

▼

Approve or reject a pending human-in-the-loop request.

Authentication

Required - Include Bearer token in Authorization header.

Settings & Configuration

GET

/api/hub/settings

Retrieve the authenticated user's settings and preferences.

▼

Retrieve the authenticated user's settings and preferences.

Authentication

Required - Include Bearer token in Authorization header.

PUT

/api/hub/settings

Update user settings and preferences.

▼

Update user settings and preferences.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/hub/api-keys

Get all saved API keys for the user (keys are encrypted at rest).

▼

Get all saved API keys for the user (keys are encrypted at rest).

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/hub/api-keys

Save a new API key for use in workflows.

▼

Save a new API key for use in workflows.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/user/llm-provider-configs

Get user's configured LLM provider API keys and settings.

▼

Get user's configured LLM provider API keys and settings.

Authentication

Required - Include Bearer token in Authorization header.

Agent Conversations

GET

/api/agent/histories

Get all agent conversation histories for the user.

▼

Get all agent conversation histories for the user.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/agent/conversation

Start a new conversation with the AI agent.

▼

Start a new conversation with the AI agent.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/agent/histories

Start a new agent conversation.

▼

Start a new agent conversation.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/agent/conversation/stream

Start a conversation with streaming response via SSE.

▼

Start a conversation with streaming response via SSE.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/agent/histories/{id}/messages

Add a message to an existing conversation.

▼

Add a message to an existing conversation.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/agent/micro-conversation

Quick single-turn agent interaction for simple tasks.

▼

Quick single-turn agent interaction for simple tasks.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/agent/conversation/continue

Continue conversation after tool execution completes.

▼

Continue conversation after tool execution completes.

Authentication

Required - Include Bearer token in Authorization header.

Teams

GET

/api/hub/teams

Get all teams the user is a member of.

▼

Get all teams the user is a member of.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/teams

Get all teams the user belongs to.

▼

Get all teams the user belongs to.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/hub/teams

Create a new team.

▼

Create a new team.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/hub/teams/{teamId}/invitations

Send a team invitation to a user.

▼

Send a team invitation to a user.

Authentication

Required - Include Bearer token in Authorization header.

Apps

GET

/api/hub/apps

Get all apps/templates owned by the user.

▼

Get all apps/templates owned by the user.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/apps

Get all apps for the authenticated user.

▼

Get all apps for the authenticated user.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/hub/apps/public

Browse public apps shared by the community.

▼

Browse public apps shared by the community.

GET

/api/mcp/v1/apps/{hash}

Get a specific app by hash.

▼

Get a specific app by hash.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/hub/apps/featured

Get featured/highlighted apps.

▼

Get featured/highlighted apps.

POST

/api/mcp/v1/apps

Create a new FlowDot app.

▼

Create a new FlowDot app.

Authentication

Required - Include Bearer token in Authorization header.

PUT

/api/mcp/v1/apps/{hash}

Update an existing app.

▼

Update an existing app.

Authentication

Required - Include Bearer token in Authorization header.

DELETE

/api/mcp/v1/apps/{hash}

Delete an app.

▼

Delete an app.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/apps/{hash}/workflows

Link a workflow to an app for invocation.

▼

Link a workflow to an app for invocation.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/apps/{hash}/publish

Publish an app to make it publicly visible.

▼

Publish an app to make it publicly visible.

Authentication

Required - Include Bearer token in Authorization header.

OAuth & SSO

GET

/api/auth/oauth/{provider}/redirect

Redirect user to OAuth provider for authentication.

▼

Redirect user to OAuth provider for authentication.

GET

/api/auth/oauth/{provider}/callback

Handle OAuth provider callback and complete authentication.

▼

Handle OAuth provider callback and complete authentication.

POST

/api/oauth/register

Register a new OAuth 2.1 client for MCP integration (ChatGPT, etc.).

▼

Register a new OAuth 2.1 client for MCP integration (ChatGPT, etc.).

POST

/api/oauth/token

Exchange authorization code for access token.

▼

Exchange authorization code for access token.

POST

/api/oauth/revoke

Revoke an access or refresh token.

▼

Revoke an access or refresh token.

Live Agent

GET

/api/mcp/v1/agent/live/providers

Get available audio providers for live agent sessions.

▼

Get available audio providers for live agent sessions.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/agent/live/voices

Get available voices for live agent TTS.

▼

Get available voices for live agent TTS.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/agent/live/session

Create a new live agent voice/video session.

▼

Create a new live agent voice/video session.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/agent/live/session/{id}

Get the status of a live agent session.

▼

Get the status of a live agent session.

Authentication

Required - Include Bearer token in Authorization header.

DELETE

/api/mcp/v1/agent/live/session/{id}

End an active live agent session.

▼

End an active live agent session.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/agent/live/sessions

Get all live sessions for the authenticated user.

▼

Get all live sessions for the authenticated user.

Authentication

Required - Include Bearer token in Authorization header.

Audio Providers

GET

/api/mcp/v1/audio/providers

Get all available audio providers (TTS, STT, music, sound effects).

▼

Get all available audio providers (TTS, STT, music, sound effects).

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/audio/providers/{providerId}/voices

Get available voices for a specific audio provider.

▼

Get available voices for a specific audio provider.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/audio/providers/{providerId}/models

Get available models for a specific audio provider.

▼

Get available models for a specific audio provider.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/audio/providers/{providerId}/test

Test audio provider configuration with a sample request.

▼

Test audio provider configuration with a sample request.

Authentication

Required - Include Bearer token in Authorization header.

LLM Providers

GET

/api/mcp/v1/llm/providers

Get all available LLM providers.

▼

Get all available LLM providers.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/llm/chat/stream

Stream chat completion responses via SSE.

▼

Stream chat completion responses via SSE.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/llm/test

Test LLM provider configuration.

▼

Test LLM provider configuration.

Authentication

Required - Include Bearer token in Authorization header.

Files

POST

/api/mcp/v1/files/upload

Upload a file for use in workflows.

▼

Upload a file for use in workflows.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/files/download/{filename}

Download an uploaded file.

▼

Download an uploaded file.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/files/generate-view-url

Generate a temporary signed URL for viewing a file.

▼

Generate a temporary signed URL for viewing a file.

Authentication

Required - Include Bearer token in Authorization header.

Custom Nodes

GET

/api/mcp/v1/custom-nodes

Get all custom nodes for the authenticated user.

▼

Get all custom nodes for the authenticated user.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/custom-nodes/{hash}

Get a specific custom node by hash.

▼

Get a specific custom node by hash.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/custom-nodes

Create a new custom workflow node.

▼

Create a new custom workflow node.

Authentication

Required - Include Bearer token in Authorization header.

PUT

/api/mcp/v1/custom-nodes/{hash}

Update an existing custom node.

▼

Update an existing custom node.

Authentication

Required - Include Bearer token in Authorization header.

DELETE

/api/mcp/v1/custom-nodes/{hash}

Delete a custom node.

▼

Delete a custom node.

Authentication

Required - Include Bearer token in Authorization header.

Agent Toolkits

GET

/api/mcp/v1/agent-toolkits

Get all agent toolkits for the authenticated user.

▼

Get all agent toolkits for the authenticated user.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/agent-toolkits/{hash}

Get a specific agent toolkit by hash.

▼

Get a specific agent toolkit by hash.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/agent-toolkits

Create a new MCP agent toolkit.

▼

Create a new MCP agent toolkit.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/agent-toolkits/{hash}/install

Install a toolkit to your account.

▼

Install a toolkit to your account.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/agent-toolkits/installations/{installationId}/tools/{toolName}/invoke

Execute a tool from an installed toolkit.

▼

Execute a tool from an installed toolkit.

Authentication

Required - Include Bearer token in Authorization header.

Knowledge Base

GET

/api/mcp/v1/knowledge/categories

Get all document categories in your knowledge base.

▼

Get all document categories in your knowledge base.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/knowledge/categories

Create a new category to organize documents.

▼

Create a new category to organize documents.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/mcp/v1/knowledge/documents

Get documents in your knowledge base.

▼

Get documents in your knowledge base.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/knowledge/documents/text

Upload text content directly as a document.

▼

Upload text content directly as a document.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/knowledge/documents/url

Download and add a document from a URL.

▼

Download and add a document from a URL.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/mcp/v1/knowledge/query

Search your knowledge base using semantic and keyword search.

▼

Search your knowledge base using semantic and keyword search.

Authentication

Required - Include Bearer token in Authorization header.

Learn Center

GET

/api/learn-center/sections

Get all documentation sections.

▼

Get all documentation sections.

GET

/api/learn-center/search

Search across all documentation content.

▼

Search across all documentation content.

Error Codes

The API uses standard HTTP status codes. Here are common errors you may encounter:

Status	Code	Description
400	`bad_request`	The request was malformed or contains invalid parameters.
401	`unauthorized`	Authentication is required but was not provided or is invalid.
401	`invalid_credentials`	The email or password provided is incorrect.
403	`forbidden`	You do not have permission to access this resource.
404	`not_found`	The requested resource does not exist.
410	`token_expired`	The authentication token has expired.
422	`validation_error`	The request data failed validation.
429	`rate_limited`	Too many requests. You have exceeded the rate limit.
500	`internal_error`	An unexpected error occurred on the server.

OpenAPI Specification

Download the OpenAPI 3.0 spec for use with Postman, Insomnia, or code generators.

Download Spec

Machine-readable API specification in JSON format.

openapi.json

FlowDot API Capabilities

The FlowDot API provides programmatic access to all core platform features. Here's what you can build:

Workflow Management

List all workflows in your account
Get workflow details and configuration
Execute workflows programmatically
Clone and duplicate workflows
Manage workflow visibility (public/private)

Custom Nodes

Create custom nodes with JavaScript
Define input and output sockets
Add configurable properties
Share nodes publicly or keep private
Version control for node updates

App Development

Create React-based frontend apps
Link apps to backend workflows
Multi-file app architecture support
Publish apps to the marketplace
Clone and customize existing apps

Execution & Monitoring

View execution history and logs
Monitor workflow performance metrics
Stream real-time execution results
Share execution results publicly
Create input presets for quick testing

API Best Practices

Follow these guidelines to build robust integrations with the FlowDot API:

Authentication Security

Store API tokens securely using environment variables
Never expose tokens in client-side JavaScript code
Rotate tokens periodically for enhanced security
Use separate tokens for development and production
Revoke compromised tokens immediately in the dashboard

Error Handling

Implement exponential backoff for rate limit (429) errors
Parse error response bodies for detailed messages
Log failed requests for debugging purposes
Handle network timeouts gracefully with retries
Validate input data before making API calls

Performance Optimization

Use pagination for large result sets
Cache workflow data when possible
Batch multiple operations when available
Use async execution for long-running workflows
Monitor API usage to stay within rate limits

Integration Patterns

Use webhooks for real-time workflow completion notifications
Implement idempotency for workflow execution requests
Store workflow IDs instead of duplicating configurations
Use input presets for repeatable test scenarios
Version your integration code alongside API updates

SDKs and Developer Tools

FlowDot provides tools to accelerate your API integration:

MCP Server

Connect FlowDot to AI assistants like Claude and Cursor using the Model Context Protocol.

npm install: npx @flowdot.ai/mcp-server
Works with Claude Desktop, Cursor IDE
Execute workflows from AI conversations

OpenAPI Specification

Download the OpenAPI 3.0 spec for client generation and API exploration.

Compatible with Postman and Insomnia
Generate client SDKs in any language
Interactive API documentation

Frequently Asked Questions

What is the FlowDot API base URL?

The FlowDot API base URL is https://flowdot.ai/api/mcp/v1 for all production API requests.

How do I get an API token?

Navigate to your FlowDot Dashboard → Settings → MCP Tokens and click "Generate New Token". Your token will start with fd_mcp_.

What authentication method does the API use?

The FlowDot API uses Bearer token authentication. Include your token in the Authorization header: Authorization: Bearer fd_mcp_xxxxxxxxxxxxx

What are the API rate limits?

Rate limits vary by plan: Free tier allows 60 requests/minute, Pro allows 300 requests/minute, and Enterprise has custom limits. When rate limited, you'll receive a 429 status code.

How do I handle API errors?

The API returns standard HTTP status codes: 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 429 (Rate Limited), and 500 (Server Error). All error responses include a JSON body with details.

Can I execute workflows via the API?

Yes, use the POST /workflows/{id}/execute endpoint to run any workflow programmatically. You can pass input values and receive execution results synchronously or asynchronously.

Does FlowDot have an MCP integration?

Yes, FlowDot provides a Model Context Protocol (MCP) server that lets AI assistants like Claude execute your workflows. Install with npx @flowdot.ai/mcp-server.