How do I authenticate FlowDot API requests?

Include a Bearer token in the Authorization header. Generate tokens in your dashboard under Settings → MCP Tokens. Format: 'Authorization: Bearer fd_mcp_xxxxxxxxxxxxx'

FlowDot API Reference - Developer Documentation

TL;DR — Two APIs, pick the one that matches your use case:

LLM Aggregator (OpenAI-compatible): https://flowdot.ai/api/v1 with Bearer fd_agg_…. Point any OpenAI SDK at it. Use nested model IDs like openai/gpt-4o-mini, anthropic/claude-sonnet-4-6, redpill/google/gemini-2.5-flash-lite. See the aggregator guide.
Platform / MCP API: https://flowdot.ai/api/mcp/v1 and /api/hub/* with Bearer fd_mcp_…. For workflow execution, custom nodes, apps, knowledge base, etc.
Get a key: open any app page → click the settings gear (top-right) → FlowDot API Keys tab (for fd_agg_). fd_mcp_ tokens live under Settings → MCP Tokens.
OpenAPI spec: /api/learn-center/openapi.json

FlowDot exposes two REST APIs. The LLM Aggregator API is a drop-in replacement for OpenAI's API — same shape, one key, every model (OpenAI, Anthropic, Google, Redpill, OpenRouter, and more) addressable via nested model IDs. The Platform API lets you integrate FlowDot workflows, custom nodes, apps, and knowledge-base features into your own systems.

128

Endpoints

24

Authentication

FlowDot issues three kinds of credentials. Use the one that matches the API you're calling:

`fd_agg_` — LLM Aggregator keys

For the OpenAI-compatible aggregator at /api/v1/*. Create one in the app: click the settings gear (top-right of any app page) → FlowDot API Keys tab → Create Key. The plaintext key is shown once at creation — copy it immediately.

Authorization: Bearer fd_agg_xxxxxxxxxxxxx

`fd_mcp_` — Platform / MCP tokens

For /api/mcp/v1/* and /api/hub/* (workflows, apps, custom nodes, knowledge base). Create in the settings modal (gear icon, top-right) → MCP Tokens tab.

Authorization: Bearer fd_mcp_xxxxxxxxxxxxx

Session cookies — web dashboard only

The /api/aggregator/keys/* and /api/user/credits/* endpoints are gated by auth:sanctum session cookies. They power the web UI — not callable from third-party integrations.

Example — aggregator chat completion

curl https://flowdot.ai/api/v1/chat/completions \
  -H "Authorization: Bearer fd_agg_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"Hi"}]}'

Example — platform (workflow list)

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

Settings Modal — where each thing lives

All per-user configuration lives in one settings modal. Open any app page (Dashboard, Workflows, Agent, etc.) and click the settings gear icon in the top-right. The modal has these tabs:

Tab	What it does
FlowDot Credits	Credit balance, transaction history, buy credits.
FlowDot API Keys	`fd_agg_…` keys for the OpenAI-compatible aggregator API (`/api/v1/*`).
MCP Tokens	`fd_mcp_…` tokens for the Platform / MCP API (`/api/mcp/v1/`, `/api/hub/`).
Notifications	Notification preferences.
LLM BYOK	Your own provider API keys (OpenAI, Anthropic, Google, etc.). Calls that resolve to a BYOK provider skip FlowDot credits.
Audio BYOK	Same idea, for TTS / STT providers.
Preferred Models	Default model choices for the Simple / Capable / Complex tiers used by LLM nodes.
Research	Deep-research / web-research preferences.

Base URLs

LLM Aggregator (OpenAI-compatible) — use with fd_agg_

https://flowdot.ai/api/v1

Platform / MCP — use with fd_mcp_

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

Hub REST (same auth as MCP) — workflows, apps, knowledge base, etc.

https://flowdot.ai/api/hub

API Reference

POST

/api/auth/login

Authenticate with email and password to receive a Sanctum token for API access.

▼

Authenticate with email and password to receive a Sanctum token for API access.

Authentication

Required - Include Bearer token in Authorization header.

Example

POST

/api/auth/register

Create a new user account. A verification email will be sent.

▼

Create a new user account. A verification email will be sent.

Authentication

Required - Include Bearer token in Authorization header.

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/logout

Invalidate the current access token.

▼

Invalidate the current access token.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/auth/validate

Validate the current authentication token and return user details.

▼

Validate the current authentication token and return user details.

Authentication

Required - Include Bearer token in Authorization header.

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.

FlowDot 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.

Authentication

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 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.

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 (MCP)

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 & RAG

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.

LLM Aggregator API

POST

/api/v1/chat/completions

Drop-in replacement for OpenAI's POST /v1/chat/completions. Accepts nested model...

▼

Drop-in replacement for OpenAI's POST /v1/chat/completions. Accepts nested model IDs like 'openai/gpt-4o-mini', 'anthropic/claude-sonnet-4-6', 'google/gemini-2.5-flash', 'redpill/google/gemini-2.5-flash-lite', or 'openrouter/meta-llama/llama-3.3-70b-instruct'. Supports streaming (SSE) and OpenAI tool calling. Requires a Bearer fd_agg_ key.

Authentication

Required - Include Bearer token in Authorization header.

Example

curl https://flowdot.ai/api/v1/chat/completions \
  -H "Authorization: Bearer fd_agg_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role":"user","content":"Hello!"}]
  }'

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "openai/gpt-4o-mini",
  "choices": [{
    "index": 0,
    "message": {"role":"assistant","content":"Hello! How can I help?"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 9, "completion_tokens": 8, "total_tokens": 17}
}

GET

/api/v1/models

OpenAI-compatible models list. Returns every model available through the aggrega...

▼

OpenAI-compatible models list. Returns every model available through the aggregator across all upstream providers. Each item carries a nested ID (e.g. 'openai/gpt-4o-mini', 'anthropic/claude-sonnet-4-6', 'redpill/deepseek-ai/DeepSeek-V3') that can be passed directly as 'model' in a chat completion request.

Authentication

Required - Include Bearer token in Authorization header.

Example

curl https://flowdot.ai/api/v1/models \
  -H "Authorization: Bearer fd_agg_xxxxxxxxxxxxx"

Response

{
  "object": "list",
  "data": [
    {"id":"openai/gpt-4o-mini","object":"model","owned_by":"openai"},
    {"id":"anthropic/claude-sonnet-4-6","object":"model","owned_by":"anthropic"},
    {"id":"redpill/google/gemini-2.5-flash-lite","object":"model","owned_by":"redpill"}
  ]
}

GET

/api/v1/models/{model}

Return metadata for a single model by its nested ID. URL-encode slashes in the m...

▼

Return metadata for a single model by its nested ID. URL-encode slashes in the model ID when passing it as a path parameter.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/v1/embeddings

OpenAI-compatible embeddings endpoint. Pass a nested embedding model ID such as...

▼

OpenAI-compatible embeddings endpoint. Pass a nested embedding model ID such as 'openai/text-embedding-3-small'.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/v1/audio/speech

OpenAI-compatible TTS endpoint. Returns audio bytes in the requested format.

▼

OpenAI-compatible TTS endpoint. Returns audio bytes in the requested format.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/v1/audio/transcriptions

OpenAI-compatible speech-to-text. multipart/form-data with an audio file.

▼

OpenAI-compatible speech-to-text. multipart/form-data with an audio file.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/v1/audio/translations

OpenAI-compatible audio translation — transcribes an audio file in any supported...

▼

OpenAI-compatible audio translation — transcribes an audio file in any supported language into English text.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/v1/images/generations

OpenAI-compatible image generation.

▼

OpenAI-compatible image generation.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/aggregator/keys

Dashboard API — auth:sanctum session. Lists the fd_agg_ keys owned by the authen...

▼

Dashboard API — auth:sanctum session. Lists the fd_agg_ keys owned by the authenticated user. Third-party integrations should not call this endpoint with an fd_agg_ token; it is for the web dashboard only.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/aggregator/keys

Creates a new fd_agg_ key. The full plaintext key is returned exactly once in th...

▼

Creates a new fd_agg_ key. The full plaintext key is returned exactly once in the response — store it immediately. auth:sanctum.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/aggregator/keys/{id}

Fetch metadata for a single fd_agg_ key. Plaintext is never returned. auth:sanct...

▼

Fetch metadata for a single fd_agg_ key. Plaintext is never returned. auth:sanctum.

Authentication

Required - Include Bearer token in Authorization header.

PUT

/api/aggregator/keys/{id}

Rename a key. auth:sanctum.

▼

Rename a key. auth:sanctum.

Authentication

Required - Include Bearer token in Authorization header.

DELETE

/api/aggregator/keys/{id}

Revoke a key. Subsequent requests with that fd_agg_ value return 401. auth:sanct...

▼

Revoke a key. Subsequent requests with that fd_agg_ value return 401. auth:sanctum.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/aggregator/keys/{id}/usage

Per-key usage stats (request count, tokens, credit spend) over time. auth:sanctu...

▼

Per-key usage stats (request count, tokens, credit spend) over time. auth:sanctum.

Authentication

Required - Include Bearer token in Authorization header.

POST

/api/aggregator/keys/{id}/regenerate

Rotate a key — invalidates the old plaintext and returns a new fd_agg_ value. au...

▼

Rotate a key — invalidates the old plaintext and returns a new fd_agg_ value. auth:sanctum.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/user/credits/balance

Current FlowDot credit balance and lifetime totals for the authenticated user. a...

▼

Current FlowDot credit balance and lifetime totals for the authenticated user. auth:sanctum.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/user/credits/transactions

Paginated credit ledger — deposits, usage, refunds, adjustments, fees. auth:sanc...

▼

Paginated credit ledger — deposits, usage, refunds, adjustments, fees. auth:sanctum.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/user/credits/summary

Rolled-up credit stats for dashboards. auth:sanctum.

▼

Rolled-up credit stats for dashboards. auth:sanctum.

Authentication

Required - Include Bearer token in Authorization header.

GET

/api/user/credits/usage

Credit spend broken down by model and workflow. auth:sanctum.

▼

Credit spend broken down by model and workflow. auth:sanctum.

Authentication

Required - Include Bearer token in Authorization header.

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 invalid or malformed. This usually means required parameters are missing or have invalid values.
401	`unauthorized`	Authentication is required but was not provided or is invalid.
401	`INVALID_AGGREGATOR_KEY`	The Bearer token passed to an /api/v1/* endpoint is missing, malformed, revoked, or does not start with fd_agg_.
401	`AUTH_ERROR`	Authentication failed during a Live Agent session.
401	`invalid_credentials`	The email or password provided is incorrect.
402	`INSUFFICIENT_CREDITS`	The estimated cost of the request (including a 20% safety buffer) exceeds the user's available credit balance. Returned by /api/v1/* calls funded via the FlowDot credits path.
403	`forbidden`	You don't have permission to access this resource.
404	`not_found`	The requested resource could not be found.
408	`SESSION_EXPIRED`	Your Live Agent session has timed out.
410	`token_expired`	The authentication token has expired.
422	`validation_error`	The request data failed validation checks.
429	`rate_limited`	You've exceeded the rate limit for this endpoint.
429	`LIVE_007`	You've exceeded the maximum number of concurrent Live Agent sessions (2 per user).
429	`MODEL_RATE_LIMITED`	The upstream provider for the selected model has rate-limited the request. Check the Retry-After header.
500	`internal_error`	An unexpected error occurred on the server.
500	`TTS_ERROR`	Failed to generate audio from text in the Live Agent.
500	`STT_ERROR`	Failed to transcribe audio in the Live Agent.
500	`LLM_ERROR`	The AI language model provider returned an error.
502	`UPSTREAM_PROVIDER_ERROR`	The upstream provider (OpenAI, Anthropic, Google, Redpill, OpenRouter, etc.) returned a 5xx or otherwise failed. Credit is not deducted for failed upstream calls.

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?

Open any app page, click the settings gear (top-right), go to the MCP Tokens tab, 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".

FlowDot API Reference - Developer Documentation

Authentication

fd_agg_ — LLM Aggregator keys

fd_mcp_ — Platform / MCP tokens

Session cookies — web dashboard only

Example — aggregator chat completion

Example — platform (workflow list)

Settings Modal — where each thing lives

Base URLs

API Reference

Authentication

Example

Authentication

Example

Response

Authentication

Authentication

Workflows

Authentication

Example

Response

Authentication

Example

Authentication

Authentication

Example

Authentication

Authentication

Authentication

Authentication

Authentication

Authentication

Authentication

Authentication

Authentication

Example

Response

Authentication

Authentication

Authentication

Authentication

Executions

Authentication

Example

Response

Authentication

Authentication

Authentication

Authentication

Authentication

Authentication

Authentication

Authentication

Settings & Configuration

Authentication

Authentication

Authentication

Authentication

Authentication

Agent Conversations

Authentication

Authentication

Authentication

Authentication

Authentication

Authentication

Authentication

Teams

Authentication

Authentication

Authentication

Authentication

FlowDot Apps

Authentication

Authentication

Authentication

Authentication

Authentication

Authentication

Authentication

`fd_agg_` — LLM Aggregator keys

`fd_mcp_` — Platform / MCP tokens