# How to Build a Fastio API Folder Structure

Manually creating workspaces slows down development and client onboarding. A Fastio API folder structure creation guide shows you how to automate this setup. By scripting programmatic folder creation in Fastio, development teams can instantly build nested directory trees. This approach keeps project layouts consistent and reduces manual errors.

Source: https://fast.io/resources/fastio-api-folder-structure-creation/
Last reviewed: 2026-02-24

## What is Programmatic Folder Creation?

API folder structure creation lets teams instantly spin up standard, nested workspaces for new projects or clients. Instead of clicking through a user interface to add directories, developers write a script that talks directly to the Fastio directory tree API. This turns your infrastructure blueprint into a working storage repository in seconds.

Consistency is key when scaling operations. Manual folder creation often causes naming errors, missing subdirectories, or folders landing in the wrong parent. Programmatic folder creation in Fastio removes these issues by following a strict template. The exact same hierarchy is generated every time a new client signs up or a project begins.

This automation fits right into your existing workflows. When a CRM event or an AI agent needs a new workspace, your script can POST each folder to `https://api.fast.io/current/workspace/{workspace_id}/storage/{parent_id}/createfolder/` (use the literal parent `root` for the first level). Teams can start uploading assets right away without waiting for an admin to set things up.

Helpful references: [Fastio Workspaces](/product/workspaces/), [Fastio Collaboration](/product/collaboration/), and [Fastio AI](/product/ai/).

## What to check before scaling Fastio API folder structure creation guide

Setting up a baseline directory tree is the first step toward effective automation. A common approach for agencies and development teams is deploying a standard multiple-folder project template. This structure separates raw assets, working files, deliverables, documentation, and client feedback.

Here is the breakdown of the 5-folder template:

*   **01_Raw_Assets**: The destination for unedited uploads, source files, and original media.
*   **02_Working_Files**: The active sandbox where developers and designers work with the raw assets.
*   **03_Deliverables**: The folder holding final, approved exports ready for client review.
*   **04_Documentation**: The repository for project briefs, API specifications, and meeting notes.
*   **05_Client_Feedback**: The designated area for annotations, review documents, and requested revisions.

Mapping this template to a script gives you a repeatable blueprint. Each folder is created with `POST /current/workspace/{workspace_id}/storage/{parent_id}/createfolder/`, using `root` as `{parent_id}` for this first level. This predictable setup helps AI agents and human collaborators navigate the workspace easily, so everyone knows exactly where to find specific files.

Here is a Python snippet that maps the template and posts each folder under `root`. Authenticate with `Authorization: Bearer {api_key}`. Most Fastio POST bodies are `application/x-www-form-urlencoded`.

```python
import requests

def create_standard_template(api_key, workspace_id):
    headers = {
        "Authorization": f"Bearer {api_key}",
    }
    template_folders = [
        "01_Raw_Assets",
        "02_Working_Files",
        "03_Deliverables",
        "04_Documentation",
        "05_Client_Feedback"
    ]

created_folders = []
    for folder_name in template_folders:
        response = requests.post(
            f"https://api.fast.io/current/workspace/{workspace_id}/storage/root/createfolder/",
            headers=headers,
            data={"name": folder_name},
        )
        created_folders.append(response)
    return created_folders
```

## Algorithms for Efficient Tree Generation

Building a complex directory structure requires some planning. Many implementations miss out on using algorithms for efficient tree generation with minimal API calls. Basic scripts often loop through a flat list, creating folders one by one and waiting for a response before moving to the next.

A better approach applies breadth-first search (BFS) or depth-first search (DFS) algorithms to map the intended structure. For standard nested hierarchies, BFS ensures parent directories are always created before their children. This dependency management is required when building a deep Fastio directory tree API implementation.

Think about a setup where you need to create a project folder, three subfolders, and two additional subfolders inside each of those. A basic script might wait for every POST before starting the next one, which adds latency and can hit rate limits. Sibling folders share a parent, so their `createfolder` calls can run concurrently. Children must wait until that parent exists.

When implementing these algorithms, track the identifier returned after each parent is created. Use that value as `{parent_id}` in the next `POST /current/workspace/{workspace_id}/storage/{parent_id}/createfolder/` call. Keep an internal state map linking local paths to Fastio folder IDs so the tree resolves correctly.

## Executing Fastio API Bulk Folders Creation

Creating folders sequentially becomes a bottleneck for high-volume provisioning. Fastio API bulk folders strategies focus on concurrency for siblings and a strict parent-before-child order. Minimizing round trips is the main goal when generating a massive directory tree for an enterprise migration.

Group independent folder creation calls into concurrent asynchronous requests. Since sibling folders do not depend on each other's IDs, their `POST /current/workspace/{workspace_id}/storage/{parent_id}/createfolder/` calls can run simultaneously.

For example, if you are provisioning the standard multiple-folder template at the workspace root, launch five concurrent requests to `.../storage/root/createfolder/`. This method reduces the network latency overhead from five sequential round trips to the duration of the single longest request. Nested folders still wait on their parent id, then fan out the same way one level down.

Retry failed calls with backoff. HTTP 429 with error code 1671 means you are rate limited; wait until the `x-ve-limit-expires` header before retrying that folder. A strong script retries only the failed folder without restarting the whole tree.

## Managing Inheritance and Access Control

A directory tree is only useful if the right people and agents can access it. After the folders exist, add teammates and agents as workspace members with `POST /current/workspace/{workspace_id}/members/{email_or_user_id}/`. List who is already on the workspace with `GET /current/workspace/{workspace_id}/members/list/`.

Workspace membership is the straightforward way to give collaborators access to the whole tree, including the five-folder template. Agents that authenticate with an API key work in the same workspace and can upload into `01_Raw_Assets` or write into `02_Working_Files` as soon as those folders exist.

When clients should only see finished work, create a branded Send, Receive, or Exchange share with `POST /current/workspace/{workspace_id}/create/share/`, or a durable single-file link with `POST /current/workspace/{workspace_id}/create/fileshare/`. Point those portals at the deliverables you want to share so internal working files stay inside the workspace.

Confirm the provisioning run with the audit log. Search activity with `GET /current/events/search/`, or long-poll `GET /current/activity/poll/{entityId}?wait=95&lastactivity={timestamp}`. That record shows who created folders, who joined the workspace, and which shares were opened.

## Integrating with the Model Context Protocol

Modern development environments often rely on AI agents to handle routine work. Integrating programmatic folder creation in Fastio with the Model Context Protocol (MCP) lets those agents provision the same template you script by hand.

Connect the official MCP server over streamable HTTP at `https://mcp.fast.io/mcp` (or `https://mcp.fast.io/mcp/key` with a Bearer header). Legacy SSE is available at `https://mcp.fast.io/sse`. Headless agents such as Claude Code and Cursor use code mode tools, including `execute`, which sends a structured `method`, `path`, `body`, and `params` against the REST API. A typical tools/call looks like this:

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"execute","arguments":{"method":"POST","path":"/current/workspace/1234567890123456789/storage/root/createfolder/"}}}
```

The agent can confirm the workspace id, then POST each template folder to `/current/workspace/{workspace_id}/storage/{parent_id}/createfolder/`, using `root` for the first level. You can also wrap that loop as your own MCP tool and invoke it with a natural language command such as "set up a new marketing campaign workspace."

Once files land in those folders, Ripley (the built-in RAG agent) can answer questions about them through the MCP `ai` tool (`ask`). Semantic search is also available at `GET /current/workspace/{workspace_id}/storage/search/`. There is no separate indexing step or external vector database to configure.

## Frequently asked questions

### How do I create nested folders in Fastio API?

Create the parent with POST /current/workspace/{workspace_id}/storage/{parent_id}/createfolder/, using the literal parent root when the folder sits at the workspace root. Then call the same route again with the new folder's id as {parent_id} for each child. A breadth-first pass creates every parent before its children.

### Can I template Fastio folders via API?

Yes. Define the hierarchy in your own JSON or YAML template, then iterate it in a script. For each entry, POST /current/workspace/{workspace_id}/storage/{parent_id}/createfolder/, using root for top-level folders and the parent folder's id for nested ones. That sets up the same environment for every new project or client.

### How do I handle rate limits during bulk creation?

Run sibling createfolder calls concurrently, and serialize children until their parent exists. If the API returns HTTP 429 with error code 1671, wait until the x-ve-limit-expires header before retrying that folder. An asynchronous queue with a concurrency limit plus this backoff finishes the tree without restarting from the top.

### Do subfolders inherit permissions from the parent?

Add people and agents with POST /current/workspace/{workspace_id}/members/{email_or_user_id}/ so they can work across the folders you just created. When a client should only see finished files, create a Send, Receive, or Exchange share with POST /current/workspace/{workspace_id}/create/share/, or a durable fileshare with POST /current/workspace/{workspace_id}/create/fileshare/. Review activity with GET /current/events/search/.

### Is it possible to automate folder creation using an AI agent?

Yes. Connect an agent to the Fastio MCP server at https://mcp.fast.io/mcp (or https://mcp.fast.io/mcp/key with a Bearer header). Headless agents can use the execute tool to POST /current/workspace/{workspace_id}/storage/{parent_id}/createfolder/. You can also wrap your template script and invoke it from the agent with a natural language command.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.