> ## Documentation Index
> Fetch the complete documentation index at: https://moonshadow-ep3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

Workspaces are the top-level containers for teams in Moonshadow. Every workspace holds its own members, integrations, and event history. Use these endpoints to create new workspaces, list your existing ones, and update workspace settings.

***

## List Workspaces

Returns a paginated list of workspaces you have access to.

```bash theme={null}
curl -G https://api.moonshadow.dev/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "limit=20"
```

### Query Parameters

<ParamField query="limit" default="20" type="integer">
  Number of workspaces to return. Maximum is 100.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor from a previous response to fetch the next page.
</ParamField>

### Response

<ResponseField name="data" type="array">
  Array of workspace objects.
</ResponseField>

<ResponseField name="data[].id" type="string">
  Unique workspace identifier, e.g. `ws_abc123`.
</ResponseField>

<ResponseField name="data[].name" type="string">
  Human-readable workspace name.
</ResponseField>

<ResponseField name="data[].slug" type="string">
  URL-friendly unique identifier for the workspace.
</ResponseField>

<ResponseField name="data[].plan" type="string">
  Billing plan: `free`, `team`, or `enterprise`.
</ResponseField>

<ResponseField name="pagination" type="object">
  Cursor pagination metadata.
</ResponseField>

```json theme={null}
{
  "data": [
    {
      "id": "ws_abc123",
      "name": "Engineering",
      "slug": "engineering",
      "plan": "team",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-03-01T14:22:00Z"
    },
    {
      "id": "ws_def456",
      "name": "Design",
      "slug": "design",
      "plan": "free",
      "created_at": "2024-02-10T09:00:00Z",
      "updated_at": "2024-02-10T09:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IndzX2RlZjQ1NiJ9",
    "has_more": true
  }
}
```

***

## Create a Workspace

Creates a new workspace for your team.

```bash theme={null}
curl -X POST https://api.moonshadow.dev/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing",
    "slug": "marketing",
    "plan": "team"
  }'
```

### Request Body

<ParamField body="name" type="string" required>
  Display name for the workspace. Must be between 1 and 100 characters.
</ParamField>

<ParamField body="slug" type="string" required>
  URL-friendly unique identifier. Must match `^[a-z0-9-]+$` and be 2 to 50 characters.
</ParamField>

<ParamField body="plan" default="free" type="string">
  Billing plan for the workspace. Options: `free`, `team`, `enterprise`.
</ParamField>

### Response

Returns the newly created workspace object with a generated `id`.

```json theme={null}
{
  "id": "ws_ghi789",
  "name": "Marketing",
  "slug": "marketing",
  "plan": "team",
  "created_at": "2024-06-10T16:45:00Z",
  "updated_at": "2024-06-10T16:45:00Z"
}
```

***

## Get a Workspace

Retrieves a single workspace by its ID.

```bash theme={null}
curl https://api.moonshadow.dev/v1/workspaces/ws_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Path Parameters

<ParamField path="id" type="string" required>
  The workspace ID, e.g. `ws_abc123`.
</ParamField>

### Response

```json theme={null}
{
  "id": "ws_abc123",
  "name": "Engineering",
  "slug": "engineering",
  "plan": "team",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-03-01T14:22:00Z"
}
```

***

## Update a Workspace

Updates fields on an existing workspace.

```bash theme={null}
curl -X PATCH https://api.moonshadow.dev/v1/workspaces/ws_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Team",
    "plan": "enterprise"
  }'
```

### Path Parameters

<ParamField path="id" type="string" required>
  The workspace ID to update.
</ParamField>

### Request Body

<ParamField body="name" type="string">
  New display name for the workspace.
</ParamField>

<ParamField body="slug" type="string">
  New slug. Must still be globally unique.
</ParamField>

<ParamField body="plan" type="string">
  New billing plan: `free`, `team`, or `enterprise`.
</ParamField>

### Response

Returns the updated workspace object.

```json theme={null}
{
  "id": "ws_abc123",
  "name": "Engineering Team",
  "slug": "engineering",
  "plan": "enterprise",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-06-10T17:00:00Z"
}
```

<Warning>
  Changing a workspace's `plan` may trigger billing changes. Use with care in production.
</Warning>