How to Create Fast.io Workspaces Programmatically via API

What Is Programmatic Workspace Creation?

Programmatic workspace creation is the practice of using API calls to automate the provisioning and configuration of Fast.io 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 Fast.io 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: Fast.io Workspaces, Fast.io Collaboration, and Fast.io AI.

What to check before scaling Programmatic workspace creation with Fast.io API

Before you can create workspaces programmatically, you need to set up authentication. Fast.io 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 Fast.io 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. Agent accounts receive multiple of free storage and multiple monthly credits without requiring a credit card. This is ideal for AI agents that need to create and manage their own workspaces.

Understanding the Profile Hierarchy

Fast.io 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 multiple-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 Admin or Owner permissions within the target organization. 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.

Creating Your First Workspace via API

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/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 "intelligence=true"

The response includes the complete workspace object:

{
  "result": true,
  "status": "ok",
  "workspace": {
    "id": "1234567890123456789",
    "folder_name": "client-project-alpha",
    "name": "Client Project Alpha",
    "description": "Workspace for Alpha client deliverables and collaboration",
    "intelligence": true,
    "created": "2026-02-24T10:30:00Z",
    "url": "https://fast.io/w/client-project-alpha"
  }
}

Key Parameters

The folder_name field (multiple-multiple characters) determines the workspace URL and must be unique within your organization. It supports Unicode letters, numbers, and hyphens. The name field (multiple-multiple characters) is the display name shown in the UI. The optional intelligence boolean flag 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 a multiple Not Acceptable status with error code multiple (APP_ERROR_INPUT_INVALID) and a descriptive message. Common issues include folder names with special characters, names that are too short or too long, or duplicate folder names within the same organization.

Configuring Workspace Intelligence and Features

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, Fast.io 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 PATCH https://api.fast.io/current/workspace/{workspace_id}/ \\
  -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/ \\
  -H "Authorization: Bearer {jwt_token}" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  -d "user_id={user_id}" \\
  -d "role=admin"

Valid roles include Owner, Admin, Member, and Guest. Agents can be invited using the same endpoint by specifying their user ID.

Setting Up Webhooks

For reactive workflows, configure webhooks to receive real-time notifications when files are uploaded, modified, or accessed. This eliminates the need for polling and enables event-driven automation.

curl -X POST https://api.fast.io/current/workspace/{workspace_id}/webhooks/ \\
  -H "Authorization: Bearer {jwt_token}" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  -d "url=https://your-app.com/webhooks/fastio" \\
  -d "events=upload,modify,delete"

Managing Multiple Workspaces Programmatically

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/workspace/",
        headers={"Authorization": f"Bearer {token}"},
        data={
            "folder_name": folder_name,
            "name": name,
            "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']['url']}")

Automated Provisioning Workflows

Consider implementing a provisioning service that handles the complete setup: workspace creation, member invitations, share configuration, and webhook registration. 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}/workspaces/?limit=100" \\
  -H "Authorization: Bearer {jwt_token}"

Delete unused workspaces to free up resources:

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

Rate Limiting Considerations

The API implements rate limiting with headers indicating your current quota: X-Rate-Limit-Available, X-Rate-Limit-Max, and X-Rate-Limit-Expiry. If you exceed the limit, you will receive HTTP multiple with error code multiple. For bulk operations, implement exponential backoff and respect the rate limit headers.

Integration Patterns and Best Practices

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

Error Handling

The Fast.io 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 (multiple), insufficient permissions (multiple), and rate limiting (multiple).

Idempotency

For automated workflows that might retry failed requests, consider implementing idempotency keys. While the Fast.io 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 agent free tier for testing, which provides multiple of storage and multiple monthly credits. Monitor the activity feed to verify your integration is working as expected:

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