# Create a workspace

`POST https://api.vidmoat.com/v1/workspaces`

- Scope: `projects.write`
- Cost: Free

Create a workspace. Pass teamId to make it a shared one.

### Body

- `name` (string, required): Up to 48 characters.
- `color` (string, optional): One of `#FF4D2E`, `#5AA9FF`, `#7ED9A6`, `#FFD447`, `#A855F7`, `#FF7A5A`, `#9EDCC4`, `#94A3B8`. Any other value is stored as `null`.
- `icon` (string, optional): One emoji (at most two code points). Longer is stored as `null`.
- `teamId` (string, optional): A team you belong to, for a shared workspace.

## Response

Returns `201`.

### Response fields

- `id` (string): The workspace id.
- `name` (string): Its name.
- `color` (string or null): A hex colour, or `null` when none is set.
- `icon` (string or null): An emoji, or `null`.
- `teamId` (string or null): The team it belongs to, or `null` for a personal workspace.
- `projectCount` (integer): Projects filed in it (0 for a new one).

## Errors

Besides the errors any request can get ([authentication](https://developer.vidmoat.com/developer/docs/authentication#when-a-request-is-refused), [rate limits](https://developer.vidmoat.com/developer/docs/rate-limits)):

| Status | Code | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | No name, a team you are not in, or you already have 60 workspaces. |

## Request examples

```bash curl
curl -X POST https://api.vidmoat.com/v1/workspaces \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Q3","icon":"📦"}'
```

```js Node
const res = await fetch('https://api.vidmoat.com/v1/workspaces', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Acme Q3',
    icon: '📦',
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? `HTTP ${res.status}`);
console.log(data);
```

```python Python
import os
import requests

res = requests.post(
    "https://api.vidmoat.com/v1/workspaces",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    json={
      "name": "Acme Q3",
      "icon": "📦",
    },
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{ "id": "ws_2", "name": "Acme Q3", "color": null, "icon": "📦", "teamId": null, "projectCount": 0 }
```

---

Source: https://developer.vidmoat.com/developer/docs/api/workspaces/create-workspace
Previous: [List workspaces](https://developer.vidmoat.com/developer/docs/api/workspaces/list-workspaces.md)
Next: [Update a workspace](https://developer.vidmoat.com/developer/docs/api/workspaces/update-workspace.md)
All documentation: https://developer.vidmoat.com/llms-full.txt