Skip to main content

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.

​
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

AspectWorkspaceProject
LevelTop-level containerNested under a workspace
ScopeTeam, department, or clientCampaign, initiative, or product
AccessRole-based (owner, manager, editor, etc.)Inherits workspace access
Budgetbudget_alert, usage_limitCan have its own limits
ResourcesMembers, projects, personasThreads, generations, focus groups
UsageMany APIs require workspace_idSome 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:
EndpointRequiresNotes
Focus Groupsworkspace_idRequired when creating a focus group
Files / Foldersworkspace_idUpload and organize files by workspace
Video Analysesworkspace_idScope analyses to a workspace
Brand Voiceworkspace_idBrand profiles belong to a workspace
Content Generationworkspace_idGenerations scoped to workspace
Meetingsworkspace_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()

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

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

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

​
Team Members

​
Member Roles

RoleDescription
ownerFull control, can delete workspace
managerManage members and settings
editorCreate and edit content
analystView and analyze data
viewerRead-only access
creative_specialistCreate content with specific focus
client_viewerLimited external access
department_adminDepartment-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']})")

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

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

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

​
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.
FieldDescription
budget_alertCredit threshold that triggers an alert notification
usage_limitHard limit that prevents further usage when reached
billing_emailEmail 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

Create separate workspaces for different teams or clients to maintain clear separation of resources and access control.
Within a workspace, create projects for specific campaigns, products, or initiatives. This helps track usage and organize related work.
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.
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