Files & Folders

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:

Request Upload URL

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

Upload File

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

Create File Record

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

Basic Usage

Uploading a File

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

const apiKey = "mvra_live_your_key_here";
const headers = {
  "Authorization": `Bearer ${apiKey}`,
  "Content-Type": "application/json"
};
const workspaceId = "ws_abc123";

async function uploadFile(file) {
  // Step 1: Get presigned upload URL
  const uploadResponse = await fetch(
    "https://app.mavera.io/api/v1/files/upload-url",
    {
      method: "POST",
      headers,
      body: JSON.stringify({
        file_name: file.name,
        file_type: file.type,
        file_size: file.size,
        workspace_id: workspaceId
      })
    }
  ).then(r => r.json());

  // Step 2: Upload to presigned URL
  await fetch(uploadResponse.upload_url, {
    method: "PUT",
    body: file,
    headers: { "Content-Type": file.type }
  });

  // Step 3: Create file record
  const fileRecord = await fetch("https://app.mavera.io/api/v1/files", {
    method: "POST",
    headers,
    body: JSON.stringify({
      name: file.name,
      type: file.type,
      url: uploadResponse.public_url,
      workspace_id: workspaceId,
      file_size: file.size
    })
  }).then(r => r.json());

  return fileRecord;
}

// Usage with file input
const input = document.querySelector('input[type="file"]');
input.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  const result = await uploadFile(file);
  console.log("Uploaded:", result.id);
});

# Step 1: Get presigned upload URL
curl -X POST https://app.mavera.io/api/v1/files/upload-url \
  -H "Authorization: Bearer mvra_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "image.png",
    "file_type": "image/png",
    "file_size": 524288,
    "workspace_id": "ws_abc123"
  }'

# Response includes upload_url and public_url

# Step 2: Upload to presigned URL (use upload_url from response)
curl -X PUT "PRESIGNED_URL_FROM_STEP_1" \
  -H "Content-Type: image/png" \
  --data-binary @image.png

# Step 3: Create file record (use public_url from step 1)
curl -X POST https://app.mavera.io/api/v1/files \
  -H "Authorization: Bearer mvra_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "image.png",
    "type": "image/png",
    "url": "PUBLIC_URL_FROM_STEP_1",
    "workspace_id": "ws_abc123",
    "file_size": 524288
  }'

Listing Files

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

const apiKey = "mvra_live_your_key_here";
const headers = { "Authorization": `Bearer ${apiKey}` };

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

files.data.forEach(file => {
  console.log(`${file.name} (${file.type}) - ${file.size} bytes`);
  console.log(`  Favorite: ${file.is_favorite}`);
});

// Filter by type
const images = await fetch(
  "https://app.mavera.io/api/v1/files?type=image",
  { headers }
).then(r => r.json());

// Get favorites only
const favorites = await fetch(
  "https://app.mavera.io/api/v1/files?is_favorite=true",
  { headers }
).then(r => r.json());

// Search by name
const searchResults = await fetch(
  "https://app.mavera.io/api/v1/files?search=report",
  { headers }
).then(r => r.json());

// Paginate
async function getAllFiles() {
  const allFiles = [];
  let cursor = null;

  while (true) {
    const url = new URL("https://app.mavera.io/api/v1/files");
    url.searchParams.set("limit", "50");
    if (cursor) url.searchParams.set("cursor", cursor);

    const response = await fetch(url, { headers }).then(r => r.json());
    allFiles.push(...response.data);

    if (!response.has_more) break;
    cursor = response.next_cursor;
  }

  return allFiles;
}

Managing Favorites

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

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

// Toggle favorite on a file
const result = await fetch(
  "https://app.mavera.io/api/v1/files/file_abc123/favorite",
  { method: "POST", headers }
).then(r => r.json());

console.log(`File is now favorite: ${result.is_favorite}`);

Getting File Details

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

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

console.log(`Name: ${file.name}`);
console.log(`URL: ${file.url}`);

Deleting Files

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

const result = await fetch(
  "https://app.mavera.io/api/v1/files/file_abc123",
  { method: "DELETE", headers }
).then(r => r.json());

if (result.deleted) {
  console.log(`File ${result.id} deleted`);
}

Folders

Create and manage folders to organize your files.

Creating Folders

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

const folder = await fetch("https://app.mavera.io/api/v1/folders", {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Marketing Assets",
    workspace_id: "ws_abc123"
  })
}).then(r => r.json());

console.log(`Folder created: ${folder.id}`);

Listing Folders

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

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

folders.data.forEach(folder => {
  console.log(`${folder.name} - ${folder.file_count} files`);
});

Getting Folder Contents

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

const folder = await fetch(
  "https://app.mavera.io/api/v1/folders/folder_xyz?include_files=true",
  { headers }
).then(r => r.json());

console.log(`Folder: ${folder.name}`);
folder.files.data.forEach(file => {
  console.log(`  - ${file.name}`);
});

Deleting Folders

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

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

const result = await fetch(
  "https://app.mavera.io/api/v1/folders/folder_xyz",
  { method: "DELETE", headers }
).then(r => r.json());

console.log(`Deleted ${result.files_deleted} files`);

Folder Favorites

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

const result = await fetch(
  "https://app.mavera.io/api/v1/folders/folder_xyz/favorite",
  { method: "POST", headers }
).then(r => r.json());

console.log(`Folder 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

Getting Started

Core Concepts

Features

SDKs & Libraries

Files & Folders

Overview

Direct Uploads

Folder Organization

Favorites

Search

Upload Flow

Basic Usage

Uploading a File

Listing Files

Managing Favorites

Getting File Details

Deleting Files

Folders

Creating Folders

Listing Folders

Getting Folder Contents

Deleting Folders

Folder Favorites

File Size Limits

Storage Quota

Using Files with Other APIs

With the Responses API

With Brand Voice

Best Practices

Files API Reference

Folders API Reference

​Overview

Direct Uploads

Folder Organization

Favorites

Search

​Upload Flow

​Basic Usage

​Uploading a File

​Listing Files

​Managing Favorites

​Getting File Details

​Deleting Files

​Folders

​Creating Folders

​Listing Folders

​Getting Folder Contents

​Deleting Folders

​Folder Favorites

​File Size Limits

​Storage Quota

​Using Files with Other APIs

​With the Responses API

​With Brand Voice

​Best Practices

Files API Reference

Folders API Reference

Overview

Upload Flow

Basic Usage

Uploading a File

Listing Files

Managing Favorites

Getting File Details

Deleting Files

Folders

Creating Folders

Listing Folders

Getting Folder Contents

Deleting Folders

Folder Favorites

File Size Limits

Storage Quota

Using Files with Other APIs

With the Responses API

With Brand Voice

Best Practices