Workspaces & Projects

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).

Workspaces

Top-level containers for team collaboration with role-based access control

Projects

Organize threads, generations, and resources within workspaces

Team Members

Invite members with specific roles (manager, editor, viewer, etc.)

Budget Controls

Set usage limits and alerts for workspaces and projects

Workspaces

Listing Workspaces

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()

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}`);
});

curl https://app.mavera.io/api/v1/workspaces \
  -H "Authorization: Bearer mvra_live_your_key_here"

Creating a Workspace

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']}")

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());

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}'

Updating a Workspace

updated = requests.patch(
    f"https://app.mavera.io/api/v1/workspaces/{workspace_id}",
    headers=headers,
    json={
        "name": "Marketing Team - Q1",
        "usage_limit": 15000
    }
).json()

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());

Deleting a Workspace

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

result = requests.delete(
    f"https://app.mavera.io/api/v1/workspaces/{workspace_id}",
    headers=headers
).json()

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

curl -X DELETE https://app.mavera.io/api/v1/workspaces/ws_abc123 \
  -H "Authorization: Bearer mvra_live_your_key_here"

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

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']})")

curl https://app.mavera.io/api/v1/workspaces/ws_abc123/members \
  -H "Authorization: Bearer mvra_live_your_key_here"

Inviting Members

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']}")

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());

Updating Member Role

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']}")

Removing Members

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")

Projects

Listing Projects

# 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()

# 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"

Creating a Project

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']}")

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());

Getting Project Details

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']}")

Updating a Project

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()

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

# 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
    }
)

Best Practices

Organize by team or client

Create separate workspaces for different teams or clients to maintain clear separation of resources and access control.

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.

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.

Configure budget alerts early

Set budget_alert thresholds to get notified before hitting limits. This gives you time to adjust or request additional credits.

Workspaces API Reference

See the full API specification for Workspace endpoints

Projects API Reference

See the full API specification for Project endpoints

Getting Started

Core Concepts

Features

SDKs & Libraries

Workspaces & Projects

Overview

Workspace vs Project

Usage in Other Endpoints

Workspaces

Projects

Team Members

Budget Controls

Workspaces

Listing Workspaces

Creating a Workspace

Updating a Workspace

Deleting a Workspace

Team Members

Member Roles

Listing Members

Inviting Members

Updating Member Role

Removing Members

Projects

Listing Projects

Creating a Project

Getting Project Details

Updating a Project

Budget Controls

Best Practices

Workspaces API Reference

Projects API Reference

​Overview

​Workspace vs Project

​Usage in Other Endpoints

Workspaces

Projects

Team Members

Budget Controls

​Workspaces

​Listing Workspaces

​Creating a Workspace

​Updating a Workspace

​Deleting a Workspace

​Team Members

​Member Roles

​Listing Members

​Inviting Members

​Updating Member Role

​Removing Members

​Projects

​Listing Projects

​Creating a Project

​Getting Project Details

​Updating a Project

​Budget Controls

​Best Practices

Workspaces API Reference

Projects API Reference

Overview

Workspace vs Project

Usage in Other Endpoints

Workspaces

Listing Workspaces

Creating a Workspace

Updating a Workspace

Deleting a Workspace

Team Members

Member Roles

Listing Members

Inviting Members

Updating Member Role

Removing Members

Projects

Listing Projects

Creating a Project

Getting Project Details

Updating a Project

Budget Controls

Best Practices