> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavera.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces & Projects

> Organize your work with workspaces and projects, manage team members, and control budgets

## Overview

Workspaces and Projects help you organize your work in Mavera. A workspace is the top-level container that holds projects, threads, personas, and other resources. Projects are subdivisions within workspaces for organizing related work.

## Workspace vs Project

| Aspect        | Workspace                                 | Project                            |
| ------------- | ----------------------------------------- | ---------------------------------- |
| **Level**     | Top-level container                       | Nested under a workspace           |
| **Scope**     | Team, department, or client               | Campaign, initiative, or product   |
| **Access**    | Role-based (owner, manager, editor, etc.) | Inherits workspace access          |
| **Budget**    | `budget_alert`, `usage_limit`             | Can have its own limits            |
| **Resources** | Members, projects, personas               | Threads, generations, focus groups |
| **Usage**     | Many APIs require `workspace_id`          | Some APIs accept `project_id`      |

**Hierarchy:** Organization → Workspace → Project. Create a workspace first, then optional projects within it. Most API calls (Focus Groups, Files, Video Analysis, Brand Voice, Content Generation) require a `workspace_id`. Projects are used for organizing work and tracking usage at a finer grain.

## Usage in Other Endpoints

Many Mavera APIs require or accept `workspace_id` (and sometimes `project_id`) to scope resources:

| Endpoint           | Requires                  | Notes                                     |
| ------------------ | ------------------------- | ----------------------------------------- |
| Focus Groups       | `workspace_id`            | Required when creating a focus group      |
| Files / Folders    | `workspace_id`            | Upload and organize files by workspace    |
| Video Analyses     | `workspace_id`            | Scope analyses to a workspace             |
| Brand Voice        | `workspace_id`            | Brand profiles belong to a workspace      |
| Content Generation | `workspace_id`            | Generations scoped to workspace           |
| Meetings           | `workspace_id` (optional) | Filter list by workspace                  |
| Mave threads       | —                         | Threads can be associated with projects   |
| Personas           | —                         | Personas can be workspace-scoped (custom) |

**Getting your workspace ID:** List workspaces with `GET /workspaces` or find it in the dashboard URL when viewing a workspace (e.g. `app.mavera.io/workspaces/ws_abc123`).

<CardGroup cols={2}>
  <Card title="Workspaces" icon="building">
    Top-level containers for team collaboration with role-based access control
  </Card>

  <Card title="Projects" icon="folder">
    Organize threads, generations, and resources within workspaces
  </Card>

  <Card title="Team Members" icon="users">
    Invite members with specific roles (manager, editor, viewer, etc.)
  </Card>

  <Card title="Budget Controls" icon="chart-line">
    Set usage limits and alerts for workspaces and projects
  </Card>
</CardGroup>

## Workspaces

### Listing Workspaces

<CodeGroup>
  ```python Python theme={"dark"}
  import requests

  api_key = "mvra_live_your_key_here"
  headers = {"Authorization": f"Bearer {api_key}"}

  # List all workspaces
  workspaces = requests.get(
      "https://app.mavera.io/api/v1/workspaces",
      headers=headers
  ).json()

  for ws in workspaces["data"]:
      print(f"{ws['name']} ({ws['role']})")
      print(f"  Members: {ws['member_count']}")
      print(f"  Projects: {ws['project_count']}")

  # Include member details
  workspaces = requests.get(
      "https://app.mavera.io/api/v1/workspaces",
      headers=headers,
      params={"include_members": "true"}
  ).json()
  ```

  ```javascript JavaScript theme={"dark"}
  const apiKey = "mvra_live_your_key_here";
  const headers = { "Authorization": `Bearer ${apiKey}` };

  // List workspaces
  const workspaces = await fetch(
    "https://app.mavera.io/api/v1/workspaces",
    { headers }
  ).then(r => r.json());

  workspaces.data.forEach(ws => {
    console.log(`${ws.name} (${ws.role})`);
    console.log(`  Members: ${ws.member_count}`);
  });
  ```

  ```bash cURL theme={"dark"}
  curl https://app.mavera.io/api/v1/workspaces \
    -H "Authorization: Bearer mvra_live_your_key_here"
  ```
</CodeGroup>

### Creating a Workspace

<CodeGroup>
  ```python Python theme={"dark"}
  workspace = requests.post(
      "https://app.mavera.io/api/v1/workspaces",
      headers=headers,
      json={
          "name": "Marketing Team",
          "budget_alert": 5000,  # Alert at 5000 credits
          "usage_limit": 10000   # Hard limit at 10000 credits
      }
  ).json()

  print(f"Created: {workspace['id']}")
  ```

  ```javascript JavaScript theme={"dark"}
  const workspace = await fetch("https://app.mavera.io/api/v1/workspaces", {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Marketing Team",
      budget_alert: 5000,
      usage_limit: 10000
    })
  }).then(r => r.json());
  ```

  ```bash cURL theme={"dark"}
  curl -X POST https://app.mavera.io/api/v1/workspaces \
    -H "Authorization: Bearer mvra_live_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{"name": "Marketing Team", "budget_alert": 5000}'
  ```
</CodeGroup>

### Updating a Workspace

<CodeGroup>
  ```python Python theme={"dark"}
  updated = requests.patch(
      f"https://app.mavera.io/api/v1/workspaces/{workspace_id}",
      headers=headers,
      json={
          "name": "Marketing Team - Q1",
          "usage_limit": 15000
      }
  ).json()
  ```

  ```javascript JavaScript theme={"dark"}
  const updated = await fetch(
    `https://app.mavera.io/api/v1/workspaces/${workspaceId}`,
    {
      method: "PATCH",
      headers: { ...headers, "Content-Type": "application/json" },
      body: JSON.stringify({ name: "Marketing Team - Q1" })
    }
  ).then(r => r.json());
  ```
</CodeGroup>

### Deleting a Workspace

<Warning>
  Only the workspace owner can delete a workspace. This action is irreversible and deletes all associated data.
</Warning>

<CodeGroup>
  ```python Python theme={"dark"}
  result = requests.delete(
      f"https://app.mavera.io/api/v1/workspaces/{workspace_id}",
      headers=headers
  ).json()

  if result["deleted"]:
      print("Workspace deleted")
  ```

  ```bash cURL theme={"dark"}
  curl -X DELETE https://app.mavera.io/api/v1/workspaces/ws_abc123 \
    -H "Authorization: Bearer mvra_live_your_key_here"
  ```
</CodeGroup>

## Team Members

### Member Roles

| Role                  | Description                        |
| --------------------- | ---------------------------------- |
| `owner`               | Full control, can delete workspace |
| `manager`             | Manage members and settings        |
| `editor`              | Create and edit content            |
| `analyst`             | View and analyze data              |
| `viewer`              | Read-only access                   |
| `creative_specialist` | Create content with specific focus |
| `client_viewer`       | Limited external access            |
| `department_admin`    | Department-level administration    |

### Listing Members

<CodeGroup>
  ```python Python theme={"dark"}
  members = requests.get(
      f"https://app.mavera.io/api/v1/workspaces/{workspace_id}/members",
      headers=headers
  ).json()

  print(f"Active members ({members['total_members']}):")
  for member in members["data"]:
      print(f"  {member['email']} - {member['role']}")

  print(f"\nPending invitations ({members['total_pending']}):")
  for invite in members["pending_invitations"]:
      print(f"  {invite['email']} - {invite['role']} (expires: {invite['expires_at']})")
  ```

  ```bash cURL theme={"dark"}
  curl https://app.mavera.io/api/v1/workspaces/ws_abc123/members \
    -H "Authorization: Bearer mvra_live_your_key_here"
  ```
</CodeGroup>

### Inviting Members

<CodeGroup>
  ```python Python theme={"dark"}
  invitation = requests.post(
      f"https://app.mavera.io/api/v1/workspaces/{workspace_id}/members",
      headers=headers,
      json={
          "email": "colleague@company.com",
          "role": "editor"
      }
  ).json()

  print(f"Invitation sent to {invitation['email']}")
  print(f"Expires: {invitation['expires_at']}")
  ```

  ```javascript JavaScript theme={"dark"}
  const invitation = await fetch(
    `https://app.mavera.io/api/v1/workspaces/${workspaceId}/members`,
    {
      method: "POST",
      headers: { ...headers, "Content-Type": "application/json" },
      body: JSON.stringify({
        email: "colleague@company.com",
        role: "editor"
      })
    }
  ).then(r => r.json());
  ```
</CodeGroup>

### Updating Member Role

<CodeGroup>
  ```python Python theme={"dark"}
  updated = requests.patch(
      f"https://app.mavera.io/api/v1/workspaces/{workspace_id}/members/{user_id}",
      headers=headers,
      json={"role": "manager"}
  ).json()

  print(f"Updated {updated['email']} to {updated['role']}")
  ```
</CodeGroup>

### Removing Members

<CodeGroup>
  ```python Python theme={"dark"}
  result = requests.delete(
      f"https://app.mavera.io/api/v1/workspaces/{workspace_id}/members/{user_id}",
      headers=headers
  ).json()

  if result["deleted"]:
      print("Member removed")
  ```
</CodeGroup>

## Projects

### Listing Projects

<CodeGroup>
  ```python Python theme={"dark"}
  # List all projects
  projects = requests.get(
      "https://app.mavera.io/api/v1/projects",
      headers=headers
  ).json()

  for project in projects["data"]:
      print(f"{project['name']} ({project['workspace_name']})")
      print(f"  Threads: {project['thread_count']}")
      print(f"  Generations: {project['generation_count']}")

  # Filter by workspace
  workspace_projects = requests.get(
      "https://app.mavera.io/api/v1/projects",
      headers=headers,
      params={"workspace_id": workspace_id}
  ).json()
  ```

  ```bash cURL theme={"dark"}
  # List all projects
  curl https://app.mavera.io/api/v1/projects \
    -H "Authorization: Bearer mvra_live_your_key_here"

  # Filter by workspace
  curl "https://app.mavera.io/api/v1/projects?workspace_id=ws_abc123" \
    -H "Authorization: Bearer mvra_live_your_key_here"
  ```
</CodeGroup>

### Creating a Project

<CodeGroup>
  ```python Python theme={"dark"}
  project = requests.post(
      "https://app.mavera.io/api/v1/projects",
      headers=headers,
      json={
          "name": "Q1 Campaign",
          "goal": "Launch spring marketing campaign",
          "workspace_id": workspace_id,  # Optional, uses default if not specified
          "budget_alert": 1000
      }
  ).json()

  print(f"Created project: {project['id']}")
  ```

  ```javascript JavaScript theme={"dark"}
  const project = await fetch("https://app.mavera.io/api/v1/projects", {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Q1 Campaign",
      goal: "Launch spring marketing campaign",
      workspace_id: workspaceId
    })
  }).then(r => r.json());
  ```
</CodeGroup>

### Getting Project Details

<CodeGroup>
  ```python Python theme={"dark"}
  project = requests.get(
      f"https://app.mavera.io/api/v1/projects/{project_id}",
      headers=headers
  ).json()

  print(f"Project: {project['name']}")
  print(f"Goal: {project['goal']}")
  print(f"Threads: {project['thread_count']}")
  print(f"Credits used (14 days): {project['credits_used_14d']}")
  ```
</CodeGroup>

### Updating a Project

<CodeGroup>
  ```python Python theme={"dark"}
  updated = requests.patch(
      f"https://app.mavera.io/api/v1/projects/{project_id}",
      headers=headers,
      json={
          "name": "Q1 Campaign - Phase 2",
          "goal": "Scale successful ads",
          "usage_limit": 5000
      }
  ).json()
  ```
</CodeGroup>

## Budget Controls

Both workspaces and projects support budget controls to help manage credit usage.

| Field           | Description                                          |
| --------------- | ---------------------------------------------------- |
| `budget_alert`  | Credit threshold that triggers an alert notification |
| `usage_limit`   | Hard limit that prevents further usage when reached  |
| `billing_email` | Email address for budget notifications               |

<CodeGroup>
  ```python Python theme={"dark"}
  # Set budget controls on a workspace
  requests.patch(
      f"https://app.mavera.io/api/v1/workspaces/{workspace_id}",
      headers=headers,
      json={
          "budget_alert": 8000,    # Alert at 8000 credits
          "usage_limit": 10000,   # Stop at 10000 credits
          "billing_email": "finance@company.com"
      }
  )

  # Set budget controls on a project
  requests.patch(
      f"https://app.mavera.io/api/v1/projects/{project_id}",
      headers=headers,
      json={
          "budget_alert": 2000,
          "usage_limit": 3000
      }
  )
  ```
</CodeGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Organize by team or client">
    Create separate workspaces for different teams or clients to maintain clear separation of resources and access control.
  </Accordion>

  <Accordion title="Use projects for campaigns or initiatives">
    Within a workspace, create projects for specific campaigns, products, or initiatives. This helps track usage and organize related work.
  </Accordion>

  <Accordion title="Set appropriate roles">
    Assign the minimum required role to each member. Use `viewer` for stakeholders who only need to see results, `editor` for content creators, and `manager` for team leads.
  </Accordion>

  <Accordion title="Configure budget alerts early">
    Set `budget_alert` thresholds to get notified before hitting limits. This gives you time to adjust or request additional credits.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Workspaces API Reference" icon="building" href="/api-reference/workspaces/list-workspaces">
    See the full API specification for Workspace endpoints
  </Card>

  <Card title="Projects API Reference" icon="folder" href="/api-reference/projects/list-projects">
    See the full API specification for Project endpoints
  </Card>
</CardGroup>