Files & Folders

Upload, manage, and organize files and folders via the Mavera API

Overview

The Files API allows you to upload, manage, and retrieve files/assets in your Mavera workspaces. Files can include images, videos, documents, and other media that you want to use with other API features like responses, video analysis, or brand voice creation.

Direct Uploads

Upload files directly to storage using presigned URLs - no file data passes through the API server

Folder Organization

Create folders to organize files, with full CRUD operations via API

Favorites

Mark files and folders as favorites for quick access

Search

Search files and folders by name with case-insensitive matching

Upload Flow

The file upload process uses presigned URLs for efficient, direct-to-storage uploads:

1. Request Upload URL

   Call POST /api/v1/files/upload-url with file metadata to get a presigned upload URL

2. Upload File

   Use the presigned URL to upload the file directly to storage (PUT request)

3. Create File Record

   Call POST /api/v1/files to create the database record and start tracking storage usage

Basic Usage

Uploading a File

Python

import requests
import hashlib

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

# Read file
with open("document.pdf", "rb") as f:
    content = f.read()

# Step 1: Get presigned upload URL
upload_response = requests.post(
    "https://app.mavera.io/api/v1/files/upload-url",
    headers=headers,
    json={
        "file_name": "document.pdf",
        "file_type": "application/pdf",
        "file_size": len(content),
        "workspace_id": workspace_id
    }
).json()

print(f"Upload URL expires in: {upload_response['expires_in']}s")

# Step 2: Upload to presigned URL
requests.put(
    upload_response["upload_url"],
    data=content,
    headers={"Content-Type": "application/pdf"}
)

# Step 3: Create file record
file = requests.post(
    "https://app.mavera.io/api/v1/files",
    headers=headers,
    json={
        "name": "document.pdf",
        "type": "application/pdf",
        "url": upload_response["public_url"],
        "workspace_id": workspace_id,
        "file_size": len(content)
    }
).json()

print(f"File created: {file['id']}")
print(f"URL: {file['url']}")

Listing Files

Python

import requests

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

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

for file in files["data"]:
    print(f"{file['name']} ({file['type']}) - {file['size']} bytes")
    print(f"  Favorite: {file['is_favorite']}")

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

# Filter by type (images only)
images = requests.get(
    "https://app.mavera.io/api/v1/files",
    headers=headers,
    params={"type": "image"}
).json()

# Get only favorites
favorites = requests.get(
    "https://app.mavera.io/api/v1/files",
    headers=headers,
    params={"is_favorite": "true"}
).json()

# Search by name
results = requests.get(
    "https://app.mavera.io/api/v1/files",
    headers=headers,
    params={"search": "report"}
).json()

# Paginate through results
cursor = None
all_files = []

while True:
    params = {"limit": 50}
    if cursor:
        params["cursor"] = cursor

    response = requests.get(
        "https://app.mavera.io/api/v1/files",
        headers=headers,
        params=params
    ).json()

    all_files.extend(response["data"])

    if not response["has_more"]:
        break

    cursor = response["next_cursor"]

print(f"Total files: {len(all_files)}")

Managing Favorites

Toggle favorite status on files to mark them for quick access:

Python

# Toggle favorite on a file
result = requests.post(
    "https://app.mavera.io/api/v1/files/file_abc123/favorite",
    headers=headers
).json()

print(f"File is now favorite: {result['is_favorite']}")

# List only favorites
favorites = requests.get(
    "https://app.mavera.io/api/v1/files",
    headers=headers,
    params={"is_favorite": "true"}
).json()

Getting File Details

Python

file = requests.get(
    "https://app.mavera.io/api/v1/files/file_abc123",
    headers=headers
).json()

print(f"Name: {file['name']}")
print(f"URL: {file['url']}")
print(f"Type: {file['type']}")
print(f"Size: {file['size']} bytes")
print(f"Folder: {file['folder']['name'] if file['folder'] else 'None'}")

Deleting Files

Python

response = requests.delete(
    "https://app.mavera.io/api/v1/files/file_abc123",
    headers=headers
).json()

if response["deleted"]:
    print(f"File {response['id']} deleted successfully")

Folders

Create and manage folders to organize your files.

Creating Folders

Python

# Create a folder
folder = requests.post(
    "https://app.mavera.io/api/v1/folders",
    headers=headers,
    json={
        "name": "Marketing Assets",
        "workspace_id": "ws_abc123"
    }
).json()

print(f"Folder created: {folder['id']}")

Listing Folders

Python

# List folders in a workspace
folders = requests.get(
    "https://app.mavera.io/api/v1/folders",
    headers=headers,
    params={"workspace_id": "ws_abc123"}
).json()

for folder in folders["data"]:
    print(f"{folder['name']} - {folder['file_count']} files")

# Search folders
results = requests.get(
    "https://app.mavera.io/api/v1/folders",
    headers=headers,
    params={
        "workspace_id": "ws_abc123",
        "search": "marketing"
    }
).json()

# Get favorite folders only
favorites = requests.get(
    "https://app.mavera.io/api/v1/folders",
    headers=headers,
    params={
        "workspace_id": "ws_abc123",
        "is_favorite": "true"
    }
).json()

Getting Folder Contents

Python

# Get folder with files
folder = requests.get(
    "https://app.mavera.io/api/v1/folders/folder_xyz",
    headers=headers,
    params={"include_files": "true"}
).json()

print(f"Folder: {folder['name']}")
print(f"Total files: {folder['file_count']}")

for file in folder["files"]["data"]:
    print(f"  - {file['name']}")

Deleting Folders

Deleting a folder also deletes all files inside it and reclaims the storage quota.

Python

result = requests.delete(
    "https://app.mavera.io/api/v1/folders/folder_xyz",
    headers=headers
).json()

print(f"Folder deleted: {result['deleted']}")
print(f"Files removed: {result['files_deleted']}")

Folder Favorites

Python

# Toggle folder favorite
result = requests.post(
    "https://app.mavera.io/api/v1/folders/folder_xyz/favorite",
    headers=headers
).json()

print(f"Folder is now favorite: {result['is_favorite']}")

File Size Limits

File Type	Maximum Size
Video files (video/*)	2 GB
All other files	10 MB

Storage Quota

File uploads count against your subscription’s storage quota. You can check your current usage via the dashboard or subscription API.

When you delete a file, the storage is reclaimed and your quota is updated accordingly.

Using Files with Other APIs

Once uploaded, files can be referenced in other API calls:

With the Responses API

# Use file URL in response input attachments
response = requests.post(
    "https://app.mavera.io/api/v1/responses",
    headers=headers,
    json={
        "model": "mavera-v1",
        "input": [
            {
                "role": "user",
                "content": "Describe this image",
                "attachments": [
                    {
                        "type": "image",
                        "url": file["url"]
                    }
                ]
            }
        ]
    }
)

With Brand Voice

# Use uploaded documents for brand voice analysis
response = requests.post(
    "https://app.mavera.io/api/v1/brand-voices",
    headers=headers,
    json={
        "label": "My Brand Voice",
        "usage_context": "Marketing content",
        "documents": [
            {
                "name": file["name"],
                "url": file["url"],
                "file_type": file["type"],
                "file_size": file["size"]
            }
        ]
    }
)

Best Practices

Use checksums for integrity verification

Include a SHA256 checksum when requesting upload URLs to ensure file integrity:

import hashlib
checksum = hashlib.sha256(content).hexdigest()

upload_response = requests.post(
    "https://app.mavera.io/api/v1/files/upload-url",
    json={
        "file_name": "document.pdf",
        "file_type": "application/pdf",
        "file_size": len(content),
        "checksum": checksum,  # SHA256 checksum
        "workspace_id": workspace_id
    }
)

Handle upload errors gracefully

The presigned URL expires after 1 hour. If upload fails, request a new URL:

def upload_with_retry(file_path, workspace_id, max_retries=3):
    for attempt in range(max_retries):
        try:
            # Get fresh upload URL
            upload_response = get_upload_url(file_path, workspace_id)
            # Upload to presigned URL
            upload_to_storage(upload_response["upload_url"], file_path)
            # Create record
            return create_file_record(upload_response, file_path)
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff

Organize files with folders

Use folder_id to organize files logically:

# Upload to a specific folder
upload_response = requests.post(
    "https://app.mavera.io/api/v1/files/upload-url",
    json={
        "file_name": "report.pdf",
        "file_type": "application/pdf",
        "file_size": file_size,
        "workspace_id": workspace_id,
        "folder_id": "folder_xyz"  # Optional folder
    }
)

Check storage quota before uploading

For large files, verify you have sufficient storage quota before uploading:

# The upload-url endpoint will return an error if quota would be exceeded
response = requests.post(
    "https://app.mavera.io/api/v1/files/upload-url",
    json={...}
)
if "error" in response.json():
    error = response.json()["error"]
    if "storage" in error["message"].lower():
        print("Storage quota exceeded!")

Files API Reference

See the full API specification for Files endpoints

Folders API Reference

See the full API specification for Folders endpoints