How to Create Fastio Workspaces Programmatically via API

Programmatic workspace creation is the practice of using API calls to automate the provisioning and configuration of Fastio workspaces. Rather than logging into a web interface and manually creating workspaces for each project, client, or agent team, developers can integrate workspace creation directly into their applications and workflows.

The core workflow involves making authenticated POST requests to the Fastio API endpoints. When you create a workspace programmatically, you specify parameters like the workspace name, folder name, description, and optional settings such as Intelligence Mode activation. The API returns a workspace object containing the unique identifier, which you can then use to invite members, upload files, or configure sharing.

This approach is particularly valuable for scenarios requiring rapid workspace provisioning. Development teams can spin up isolated environments for testing, agencies can create dedicated client portals on demand, and AI agent systems can automatically generate workspaces as part of their workflow orchestration.

Helpful references: Fastio Workspaces, Fastio Collaboration, and Fastio AI.

• AI Automation Storage API: Persistent Storage for Autonomous AgentsAn AI automation storage API provides programmatic access to persistent file storage that autonomous agents can use to...
• How to Extract Metadata from Google Workspace Files via APIGoogle Workspace files live entirely in the cloud, so there is no local file to parse with traditional metadata tools....
• How to Implement Cross-Workspace Search with Fastio APICross-workspace search with the Fastio API allows centralized systems to securely query data across multiple isolated...
• Fastio API Audit Log Retrieval: A Developer's TutorialAudit log retrieval via the Fastio API lets developers export and monitor agent and human workspace activity for...
• How to Store CI/CD Build Artifacts Using the Fastio APIThis Fastio API guide shows you how to works alongside platforms like GitHub Actions and GitLab CI. Adding the Fastio...
• How to Automate Fastio Workspaces with PulumiAutomating Fastio workspaces with Pulumi lets you provision agentic storage using familiar programming languages. This...

More on this subject: Agent Memory and Storage (261 guides)

Before you can create workspaces programmatically, you need to set up authentication. Fastio supports multiple authentication methods, but for API-based workspace creation, you will typically use either API keys or JWT tokens obtained through Basic Auth.

Getting Your API Credentials

To create an API key, authenticate with your Fastio account and make a POST request to /current/user/auth/key/. This returns a long-lived token that you include in the Authorization header of all subsequent requests: Authorization: Bearer {your_token}.

If you are building an autonomous agent system, create an agent account by setting agent=true during user registration. This is ideal for AI agents that need to create and manage their own workspaces.

Understanding the Profile Hierarchy

Fastio organizes resources hierarchically: User → Organization → Workspace/Share. When you create a workspace, you must specify which organization owns it. If you are operating as an autonomous agent, you will first create an organization, then create workspaces within that organization. Organization and workspace IDs are 19-digit numeric strings, though you can also use custom names like domain names for organizations and folder names for workspaces.

Required Permissions

Workspace creation requires Member or above within the target organization, subject to the org's workspace-create policy. If you are creating workspaces as an agent that owns the organization, you automatically have these permissions. For collaboration scenarios where a human invites your agent to their organization, ensure you have been granted appropriate role-based access.

Once authenticated, creating a workspace is straightforward. The endpoint accepts form-encoded parameters defining the workspace properties.

The POST Request

Here is the exact API call to create a workspace:

curl -X POST https://api.fast.io/current/org/{org_id}/create/workspace/ \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "folder_name=client-project-alpha" \
  -d "name=Client Project Alpha" \
  -d "description=Workspace for Alpha client deliverables and collaboration" \
  -d "perm_join=Member or above" \
  -d "perm_member_manage=Admin or above" \
  -d "intelligence=true"

The response includes the new workspace's ID:

{
  "result": true,
  "workspace": {
    "id": "1234567890123456789",
    "folder_name": "client-project-alpha",
    "intelligence": true
  }
}

Key Parameters

The folder_name field (4-80 characters) determines the workspace URL and must be unique across all Fastio workspaces. It supports Unicode letters, numbers, and hyphens. The name field (2-100 characters) is the display name shown in the UI. The optional intelligence flag (on by default) activates Intelligence Mode, which auto-indexes files for RAG, enables semantic search, and allows AI chat with citations.

Field Validation

All fields undergo server-side validation. If you provide invalid input, the API returns HTTP 406 Not Acceptable with error class 1605 (Invalid Input) and a descriptive message. Common issues include folder names with special characters and names that are too short or too long; a folder name that is already in use also returns 406, with class 1658.

Give Your AI Agents Persistent Storage

Start building with the Fastio API today. Get generous storage, included credits, and shared workspaces with our 14-day Business Trial.

Start 14-Day Trial

After creating a workspace, you can configure additional features that make the environment ready for AI-powered collaboration.

Enabling Intelligence Mode

Intelligence Mode transforms a workspace from simple storage into an intelligent knowledge base. When enabled, Fastio automatically indexes all uploaded files for semantic search, extracts metadata, and enables AI chat with source citations. You can toggle this during creation by setting intelligence=true or activate it later via the API.

To enable Intelligence Mode on an existing workspace:

curl -X POST https://api.fast.io/current/workspace/{workspace_id}/update/ \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "intelligence=true"

Inviting Collaborators

Workspaces support both human and AI agent collaboration. To invite members, use the workspace members endpoint:

curl -X POST https://api.fast.io/current/workspace/{workspace_id}/members/{user_id}/ \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "permissions=admin"

Valid permissions values are admin, member, and guest; ownership is transferred separately. Agents can be invited using the same endpoint by specifying their user ID.

Subscribing to the Event Stream

For reactive workflows, subscribe to Fastio's WebSocket events feed or poll the activity feed to receive notifications when files are uploaded, modified, or deleted in the workspace:

curl -X GET "https://api.fast.io/current/events/search/?workspace_id={workspace_id}&limit=50" \
  -H "Authorization: Bearer {jwt_token}"

For applications requiring multiple isolated environments, you will need patterns for bulk creation, organization, and lifecycle management.

Bulk Workspace Creation

When onboarding multiple clients or deploying multi-agent systems, you can create workspaces in a loop. Here is a Python example:

import requests

def create_workspace(org_id, folder_name, name, token):
    response = requests.post(
        f"https://api.fast.io/current/org/{org_id}/create/workspace/",
        headers={"Authorization": f"Bearer {token}"},
        data={
            "folder_name": folder_name,
            "name": name,
            "perm_join": "Member or above",
            "perm_member_manage": "Admin or above",
            "intelligence": "true"
        }
    )
    return response.json()

### Create workspaces for multiple clients
clients = ["acme-corp", "beta-industries", "gamma-tech"]
for client in clients:
    result = create_workspace(
        org_id="1234567890123456789",
        folder_name=f"{client}-project",
        name=f"{client.replace('-', ' ').title()} Project",
        token="your_jwt_token"
    )
    print(f"Created workspace for {client}: {result['workspace']['id']}")

Automated Provisioning Workflows

Consider implementing a provisioning service that handles the complete setup: workspace creation, member invitations, and share configuration. This service can expose a simple interface to your application while managing the complexity of multiple API calls.

Monitoring and Cleanup

List all workspaces in an organization to track usage and identify candidates for archival:

curl -X GET "https://api.fast.io/current/org/{org_id}/list/workspaces/" \
  -H "Authorization: Bearer {jwt_token}"

Delete unused workspaces to free up resources (owner only; confirm must match the workspace's folder name or ID):

curl -X DELETE "https://api.fast.io/current/workspace/{workspace_id}/delete/?confirm={folder_name}" \
  -H "Authorization: Bearer {jwt_token}"

Rate Limiting Considerations

The API implements rate limiting with headers indicating your current quota: x-ve-limit-avail, x-ve-limit-max, and x-ve-limit-expires. If you exceed the limit, you will receive HTTP 429. For bulk operations, implement exponential backoff and respect the rate limit headers.

Successful programmatic workspace creation requires attention to error handling, idempotency, and security.

Error Handling

The Fastio API uses a consistent error envelope with unique error codes. Always check the result boolean in responses. When result is false, the error object contains a human-readable message and documentation URL. Common errors include duplicate folder names (HTTP 406), insufficient permissions (HTTP 403), and rate limiting (HTTP 429).

Idempotency

For automated workflows that might retry failed requests, consider implementing idempotency keys. While the Fastio API does not natively support idempotency keys, you can achieve similar safety by checking for workspace existence before creation or using deterministic folder names based on your application identifiers.

Security Best Practices

Store API tokens securely using environment variables or secret management systems. Never commit tokens to version control. Rotate API keys regularly, especially for production applications. When creating workspaces for external clients, use descriptive names that help identify the purpose without exposing sensitive information.

Testing Your Integration

Test workspace creation in a development environment before deploying to production. Use the Business Trial for testing. Monitor the activity feed to verify your integration is working as expected:

curl -X GET "https://api.fast.io/current/events/search/?org_id={org_id}&category=workspace&limit=50" \
  -H "Authorization: Bearer {jwt_token}"