---
title: Add Workspace
slug: add-workspace
docTags: 
createdAt: 2025-04-23T22:32:17.456Z
---

### API Endpoint Documentation: /api/workspaces/add

### Description:

This endpoint allows you to create a new workspace by sending a POST request. The request body contains workspace details such as name, workspace type, plan ID, and optional logo images.

### Endpoint:

:::BlockQuote
POST https\://admin.\<your-site>.com/api/workspaces/add
:::

### Headers:

- **accept**: application/json Specifies that the request expects a JSON response.
- **authorization**: Bearer \<JWT Token> A JSON Web Token (JWT) that authenticates the request. Replace \<JWT Token> with a valid token.
- **content-type**: multipart/form-data; boundary=\<boundary> Specifies that the request body is in multipart/form-data format, necessary for file uploads.

### Request Body:

The request body should be in multipart/form-data format, containing the following fields:

- **name**: string The name of the workspace.
- **workspace\_type**: string The type of workspace (e.g., "IFRAME\_EMBED", "JWT\_FULL\_EMBED").
- **plan\_id**: string (Optional) The ID of the plan to associate with the workspace.
- **square\_logo**: file (Optional) A square logo image file for the workspace. Must be less than 10MB.
- **image\_logo**: file (Optional) A logo image file for the workspace. Must be less than 10MB.
- **integrations**: string (Optional) A JSON string containing integration configurations for the workspace.

### Example Request Body:

:::BlockQuote
\{
&#x20; "name": "Finance Department",
&#x20; "workspace\_type": "IFRAME\_EMBED",
&#x20; "plan\_id": "678e56b778bd25203b900e63",
&#x20; "square\_logo": "\[Binary file data]",
&#x20; "image\_logo": "\[Binary file data]",
&#x20; "integrations": "\[]"
}
:::

Note: For multipart/form-data requests with file uploads, the actual request body will be formatted differently, with binary file content included.

### Method:

- **POST**: Sends a request to create a new workspace with the specified details.

### Example Request (Node.js):

:::BlockQuote
const fetch = require('node-fetch');
const FormData = require('form-data');
const fs = require('fs');

const url = 'https\://admin.\<your-site>.com/api/workspaces/add';
const form = new FormData();

// Add text fields
form.append('name', 'Finance Department');
form.append('workspace\_type', 'IFRAME\_EMBED');
form.append('plan\_id', '678e56b778bd25203b900e63');
form.append('integrations', '\[]');

// Add files if available
if (fs.existsSync('./finance\_square\_logo.png')) \{
&#x20; form.append('square\_logo', fs.createReadStream('./finance\_square\_logo.png'));
}

if (fs.existsSync('./finance\_logo.png')) \{
&#x20; form.append('image\_logo', fs.createReadStream('./finance\_logo.png'));
}

const options = \{
&#x20; method: 'POST',
&#x20; headers: \{
&#x20;   'accept': 'application/json',
&#x20;   'authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
&#x20;   // No need to set content-type as form-data sets it automatically with boundary
&#x20; },
&#x20; body: form
};

fetch(url, options)
&#x20; .then(response => response.json())
&#x20; .then(data => console.log(data))
&#x20; .catch(error => console.error('Error:', error));
:::

### Response:

The API will return a JSON response indicating the success or failure of the operation.

### Success Response (200):

:::BlockQuote
\{
&#x20; "status": 200,
&#x20; "data": \{
&#x20;   "workspace\_id": "6812cf45a9b33e12456789ab"
&#x20; },
&#x20; "message": "Workspace successfully added."
}
:::

### Error Response (400):

:::BlockQuote
\{
&#x20; "status": 400,
&#x20; "message": "File size must be less than 10MB."
}
:::

Or:

:::BlockQuote
\{
&#x20; "status": 400,
&#x20; "message": "Name is required."
}
:::

### Authentication:

This API requires a valid JWT token for authentication and admin privileges. Ensure that the token is included in the authorization header as Bearer \<JWT Token>.

### Usage Notes:

- This endpoint requires admin privileges to use.
- The system automatically generates a unique slug from the workspace name.
- If no plan\_id is provided, the system assigns a free (no charge) plan.
- Logo files must be less than 10MB in size.
- When creating a JWT\_FULL\_EMBED workspace type, the layout\_type is automatically set to NO\_NAVIGATION.
- For other workspace types, the layout\_type defaults to LEFT\_NAVIGATION.
- The system automatically creates subscription and transaction records based on the selected plan.
- If integrations are provided, the system will create workspace integration credentials for each integration.
- The system logs workspace creation in the activity log.