---
title: "Workspaces"
description: "Full CRUD REST API for Workspaces — create, list, update, delete, and assign projects. Workspaces are not auto-provisioned only; you can create and manage them programmatically."
canonical: "https://docs.ainative.studio/docs/api/workspaces"
last-updated: "2026-10-28T06:34:16.301Z"
---

# Workspaces

Source: https://docs.ainative.studio/docs/api/workspaces

> Full CRUD REST API for Workspaces — create, list, update, delete, and assign projects. Workspaces are not auto-provisioned only; you can create and manage them programmatically.

## Workspaces

A **workspace** groups your projects (and, on paid plans, team members and client
accounts). Every account gets a **Default Workspace** on signup, but that is not
the only way to get one — the platform ships a full CRUD API so you can create and
manage workspaces programmatically.

> **Workspace = organization.** In the data model a workspace maps to the
> "organization" concept (`user_organizations`, `projects.organization_id`). A
> project belongs to a workspace via its `organization_id`.

**Base URL:** `https://api.ainative.studio`

### Authentication

All workspace endpoints require authentication. You can use **either**:

- a JWT — `Authorization: Bearer <access_token>`, or
- an API key — `X-API-Key: <sk_...>`

### Tier caps

The number of workspaces you can create is capped by plan. Exceeding the cap
returns **`402 Payment Required`**.

| Plan | Workspace cap |
|---|---|
| Hobbyist / Free | 1 |
| Pro | higher (see pricing) |
| Team / Enterprise | higher (see pricing) |

---

## Create a workspace

<APIEndpoint method="POST" path="/api/v1/workspaces" />

**Request body** (`name` required):

| Field | Type | Notes |
|---|---|---|
| `name` | string | **required** |
| `description` | string \| null | max 1000 chars |
| `tier` | string | `free` \| `pro` \| `team` \| `enterprise` |
| `workspace_type` | string | `personal` \| `client` \| `team` |
| `client_metadata` | object \| null | `{company_name, contact_name, contact_email, billing_email, notes}` — for `client` workspaces |

```bash
curl -X POST https://api.ainative.studio/api/v1/workspaces \
  -H "Authorization: Bearer $AINATIVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "workspace_type": "client", "tier": "pro"}'
```

```python
import requests

resp = requests.post(
    "https://api.ainative.studio/api/v1/workspaces",
    headers={"Authorization": f"Bearer {token}"},
    json={"name": "Acme Corp", "workspace_type": "client", "tier": "pro"},
)
workspace = resp.json()["workspace"]
print(workspace["id"], workspace["name"])
```

```javascript
const resp = await fetch("https://api.ainative.studio/api/v1/workspaces", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Acme Corp", workspace_type: "client", tier: "pro" }),
});
const { workspace } = await resp.json();
```

**Response** `201 Created`:

```json
{
  "ok": true,
  "workspace": {
    "id": "b3f1...",
    "name": "Acme Corp",
    "description": null,
    "tier": "pro",
    "role": "owner",
    "is_default": false,
    "workspace_type": "client",
    "client_metadata": null,
    "member_count": 1,
    "project_count": 0,
    "created_at": "2026-08-02T01:23:00Z"
  },
  "message": "Workspace created"
}
```

Returns **`402`** if you are at your plan's workspace cap.

---

## List workspaces

<APIEndpoint method="GET" path="/api/v1/workspaces" />

```bash
curl https://api.ainative.studio/api/v1/workspaces \
  -H "Authorization: Bearer $AINATIVE_TOKEN"
```

Returns your workspaces (including the **Default Workspace**), each with
`member_count` and `project_count`.

---

## Get a workspace

<APIEndpoint method="GET" path="/api/v1/workspaces/{workspace_id}" />

```bash
curl https://api.ainative.studio/api/v1/workspaces/$WORKSPACE_ID \
  -H "Authorization: Bearer $AINATIVE_TOKEN"
```

Returns the workspace with its members and project summaries.

---

## Update a workspace

<APIEndpoint method="PATCH" path="/api/v1/workspaces/{workspace_id}" />

All fields optional; send only what you want to change.

| Field | Type | Notes |
|---|---|---|
| `name` | string \| null | 1–255 chars |
| `description` | string \| null | max 1000 chars |
| `workspace_type` | string \| null | `personal` \| `client` \| `team` |
| `client_metadata` | object \| null | see create |

```bash
curl -X PATCH https://api.ainative.studio/api/v1/workspaces/$WORKSPACE_ID \
  -H "Authorization: Bearer $AINATIVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corporation"}'
```

---

## Delete a workspace

<APIEndpoint method="DELETE" path="/api/v1/workspaces/{workspace_id}" />

```bash
curl -X DELETE https://api.ainative.studio/api/v1/workspaces/$WORKSPACE_ID \
  -H "Authorization: Bearer $AINATIVE_TOKEN"
```

---

## Assign a project to a workspace

Move an existing project under a workspace. A project belongs to exactly one
workspace (its `organization_id`).

<APIEndpoint method="POST" path="/api/v1/workspaces/{workspace_id}/projects" />

**Request body** (`project_id` required):

```bash
curl -X POST https://api.ainative.studio/api/v1/workspaces/$WORKSPACE_ID/projects \
  -H "Authorization: Bearer $AINATIVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "47539617-..."}'
```

```python
requests.post(
    f"https://api.ainative.studio/api/v1/workspaces/{workspace_id}/projects",
    headers={"Authorization": f"Bearer {token}"},
    json={"project_id": project_id},
)
```

---

## Notes

- Workspaces are **not** auto-provisioned only. A Default Workspace is created at
  signup for convenience, but the six endpoints above let you create and manage
  workspaces at any time.
- The `/api/v1` prefix also has a `/v1` alias.
- To create projects inside a workspace, use the
  [Projects API](/docs/api/overview) and pass `organization_id`, or assign an
  existing project with the endpoint above.