# How to Create Fastio Workspaces Programmatically via API

Programmatic workspace creation allows developers to dynamically spin up isolated, intelligence-ready Fastio environments via API. Instead of manually clicking through a dashboard to set up each workspace, you can automate the entire process with a single POST request. This approach reduces client onboarding time from hours to seconds and enables automated provisioning for multi-agent systems.

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

## What Is Programmatic Workspace Creation?

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](/product/workspaces/), [Fastio Collaboration](/product/collaboration/), and [Fastio AI](/product/ai/).

## What to check before scaling Programmatic workspace creation with Fastio API

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

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

```bash
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:

```json
{
  "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, 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:

```bash
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:

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

**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:

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

## 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:

```python
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:

```bash
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:

```bash
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 429. 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 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 (multiple), insufficient permissions (multiple), and rate limiting (multiple).

**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, which provides multiple of storage and multiple monthly credits. Monitor the activity feed to verify your integration is working as expected:

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

## Frequently asked questions

### Can I create Fastio workspaces via API?

Yes, Fastio provides a complete REST API for programmatic workspace creation. Use the POST `/current/workspace/` endpoint with your JWT token or API key. The API accepts parameters for folder name, display name, description, and Intelligence Mode activation. This enables automation for multi-tenant SaaS applications, client onboarding workflows, and AI agent orchestration systems.

### How do I automate Fastio workspace setup?

Automate workspace setup by integrating the Fastio API into your application code. First, obtain an API token via Basic Auth or create a long-lived API key. Then make POST requests to the workspace endpoint with your desired configuration. For complete automation, also use the API to invite members, configure webhooks, and enable Intelligence Mode. Consider implementing error handling, rate limit awareness, and retry logic for production reliability.

### What authentication methods does the Fastio API support?

The Fastio API supports four authentication methods: Basic Auth to JWT exchange for interactive sessions, OAuth 2.0 PKCE for desktop and mobile applications, long-lived API keys for server-to-server integrations, and session-based authentication for browser-based usage. All methods use the Authorization header with a Bearer token.

### How much does it cost to create workspaces via API?

Workspace creation is included across all Fastio plans. Plans start at Starter ($29/month) and scale to Business ($99/month) and Growth ($299/month), with a 14-day Business Trial available. Organizations consume usage-based credits for storage, bandwidth, and AI processing, keeping programmatic workspace creation cost-effective at scale.

### Can AI agents create their own workspaces?

Yes, AI agents can create and manage workspaces just like human users. Agents register for accounts with `agent=true`, receive their own API credentials, and can perform all workspace operations via the API or MCP server. Agents can also create organizations, invite human collaborators, and transfer ownership to humans when their work is complete.

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