How to Integrate Dify AI with External File Storage

Dify (50,000+ GitHub stars) makes it easy to build AI apps with a drag-and-drop workflow builder. But file management is one of the first pain points developers hit when moving from prototypes to production. The default file handling in Dify is designed for user uploads during a chat session. Files are temporary inputs that feed the LLM's context window. Once the session ends or the container restarts, those files are gone. This is fine for a "chat with your PDF" demo. It breaks down fast when your agent needs to:

• Generate and store reports that users download hours or days later
• Maintain a running log of processed data across multiple sessions
• Share deliverables with clients or teammates who are not in the Dify interface
• Access a knowledge base that grows over time as the agent collects more documents

External file storage solves these problems by giving your agent a dedicated, persistent location to read and write files. Think of it as giving your agent a hard drive that survives between conversations.

This integration uses Dify's Custom Tool feature, which lets you connect any REST API via an OpenAPI specification. You control which endpoints your agent can call and what data it can access.

Requirements:

1. A Dify instance running version 0.6.0 or later. This works on both Dify Cloud and self-hosted Docker deployments.
2. A Fastio account with an API key. Create a key in Settings > Devices & Agents > API Keys, or with POST /current/user/auth/key/. The AI Business Trial is built for programmatic access. Every authenticated call uses Authorization: Bearer {api_key}. Workspace IDs are 19-digit numeric strings.
3. Basic familiarity with OpenAPI/Swagger. You will paste a JSON schema into Dify's tool editor. No coding required. Dify Custom Tools call Fastio over HTTP at https://api.fast.io/current/. If you later attach an MCP client, Fastio's server is at https://mcp.fast.io/mcp (or https://mcp.fast.io/mcp/key with a Bearer header).

Custom Tools are how Dify connects to external APIs. You define an OpenAPI schema that describes the available endpoints, and Dify exposes those endpoints as callable actions within your agent's toolbox.

Setup instructions:

1. Open your Dify dashboard and navigate to Tools > Custom in the top navigation. 2. Click Create Custom Tool. 3. Name it fastio_storage. This name is how your agent will reference the tool in prompts. 4. In the Schema field, paste the following OpenAPI definition:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Fastio Agent Storage",
    "version": "1.0.0",
    "description": "Upload and retrieve files from Fastio cloud storage"
  },
  "servers": [
    {
      "url": "https://api.fast.io/current"
    }
  ],
  "paths": {
    "/upload/": {
      "post": {
        "operationId": "uploadFile",
        "summary": "Upload a small file to cloud storage",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["name", "size", "chunk", "action", "instance_id", "folder_id"],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Filename"
                  },
                  "size": {
                    "type": "integer",
                    "description": "File size in bytes"
                  },
                  "chunk": {
                    "type": "string",
                    "format": "binary",
                    "description": "File bytes"
                  },
                  "action": {
                    "type": "string",
                    "description": "Use create for a one-request upload"
                  },
                  "instance_id": {
                    "type": "string",
                    "description": "Workspace ID (19-digit numeric string)"
                  },
                  "folder_id": {
                    "type": "string",
                    "description": "Destination folder node ID, or root"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Upload created. Body includes result, id (upload id), and new_file_id (node id)."
          }
        }
      }
    },
    "/workspace/{workspace_id}/storage/{parent_id}/list/": {
      "get": {
        "operationId": "listFiles",
        "summary": "List files in a folder",
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Workspace ID (19-digit numeric string)"
          },
          {
            "name": "parent_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Folder node ID to list"
          }
        ],
        "responses": {
          "200": {
            "description": "Folder listing. Pagination includes has_more, next_cursor, and page_size."
          }
        }
      }
    }
  }
}

This schema exposes two operations: a one-request upload (POST /current/upload/) and a folder listing (GET /current/workspace/{workspace_id}/storage/{parent_id}/list/). Keep the trailing slashes. You can extend it later with download (GET /current/workspace/{workspace_id}/storage/{node_id}/read/), delete (DELETE /current/workspace/{workspace_id}/storage/{node_id}/delete/), and search (GET /current/workspace/{workspace_id}/storage/search/ with search_in=filename|content|both). Agent-native stacks can also attach Fastio's MCP server at https://mcp.fast.io/mcp (or https://mcp.fast.io/mcp/key with a Bearer header). Named tools include upload, storage, ai, and find. 5. Under Authentication, select API Key. 6. Set the Header name to Authorization. 7. Enter your Fastio API key in the format: Bearer your_api_key_here. 8. Click Save and run the built-in connectivity test. Dify encrypts and stores your API key securely. It gets attached automatically to every request your agent makes through this tool.

Connect Your AI Stack to Fastio

Fastio gives teams shared workspaces, MCP tools, and searchable file context to run dify ai file storage integration workflows with reliable agent and human handoffs.

Start 14-Day Trial

With the Custom Tool created, you can drop it into any Dify workflow or chatflow. The tool works like any other node on the canvas, with typed inputs and structured outputs.

For a workflow that generates and stores a report:

1. Open the Dify app builder and create a new Workflow (or edit an existing one). 2. Add your processing nodes first. For example: an LLM node that summarizes input data, followed by a Code node that formats the summary as a PDF. 3. Add a Tool node after the processing step. Search for fastio_storage and select the uploadFile action. 4. Map the inputs:

• chunk: Connect the file bytes from the PDF generation node.
• name: Set the filename, for example summary.pdf.
• size: Pass the byte length of that file.
• action: Set to create.
• instance_id: Your workspace ID.
• folder_id: root, or an existing folder node ID. 5. Connect a final LLM or Answer node that reads new_file_id from the 201 response and returns it to the user.

For an agent-style chatflow:

If you are building a conversational agent rather than a fixed workflow, add fastio_storage to the agent's tool list in the app configuration. The agent will decide when to call the upload or list tools based on the user's request. For example, a user could say "save this analysis to my project folder" and the agent would call uploadFile with name, size, chunk, action=create, instance_id, and folder_id. The key difference between workflows and chatflows: workflows call the tool at a fixed step, while agents call it dynamically based on conversation context.

Uploading is half the story. The real value comes when your agent can pull files back, search through stored documents, and generate shareable links for people outside the Dify interface.

Retrieving files in a workflow:

Use the listFiles tool with workspace_id and parent_id (the folder node ID), then pass a node_id to GET /current/workspace/{workspace_id}/storage/{node_id}/read/ for bytes or GET /current/workspace/{workspace_id}/storage/{node_id}/details/ for metadata. You can chain this with an LLM node that picks the right file based on natural language. For example: "Find the most recent invoice for Acme Corp" lists a known invoices folder, then the LLM selects the newest entry. Filename or content search is GET /current/workspace/{workspace_id}/storage/search/ (search_in=filename|content|both).

Sharing files with external users:

Fastio files live in workspaces with configurable access controls. You have three sharing options:

• Send, Receive, or Exchange shares: Create a branded share with POST /current/workspace/{workspace_id}/create/share/.
• Durable single-file links: Create a fileshare with POST /current/workspace/{workspace_id}/create/fileshare/.
• Workspace invitations: Add human collaborators with POST /current/workspace/{workspace_id}/members/{email_or_user_id}/ so they can browse, preview, and comment on files through the Fastio web interface. Files are available as soon as the upload call returns 201 with new_file_id. Your agent can upload a file in São Paulo, and a user in Tokyo can open the share right after that response lands.

Once the basic integration works, you can add more advanced patterns that turn your Dify agent from a simple file mover into an intelligent document worker.

Built-in RAG with workspace intelligence

Turn on workspace intelligence and Ripley, Fastio's built-in RAG agent, can answer questions about the files in that workspace. Your Dify agent can start a Ripley chat with POST /current/workspace/{workspace_id}/ai/agent/, then send a message with POST /current/workspace/{workspace_id}/ai/agent/{chat_id}/message/. For a single cited answer, attach Fastio MCP and call the ai tool with action ask (profile_type required). Semantic search is GET /current/workspace/{workspace_id}/storage/search/. Ask "find the contract clause about termination penalties" and you get the passage with a citation. This keeps retrieval in the storage layer, so you do not have to stand up a separate vector database. No Pinecone setup, no embedding pipeline, no chunk-size tuning.

Activity events for event-driven workflows

Point a Dify HTTP node at Fastio activity so a workflow can start when new files land. GET /current/activity/poll/{entityId}?wait=95&lastactivity={timestamp} waits for the next event. GET /current/events/search/ reads the audit log. When a teammate adds a document to an inbox folder, Dify can list that folder and begin processing. This creates a reactive pipeline: humans upload files through the web interface, and AI agents process them without anyone clicking a button.

File locks for multi-agent access

If you run multiple Dify agents that share the same workspace (common in team setups), lock a file before editing it. POST /current/workspace/{workspace_id}/storage/{node_id}/lock/ acquires the lock. POST /current/workspace/{workspace_id}/storage/{node_id}/lock/heartbeat/ keeps it. DELETE /current/workspace/{workspace_id}/storage/{node_id}/lock/ releases it. This prevents race conditions where two agents overwrite each other's changes.