Folders

Overview

Folders in Marq help you organize your projects and templates in a hierarchical structure, making it easy to manage content across teams and departments. This guide covers how to create, manage, and work with folders using the Marq API.

Understanding Folder Structure

Marq folders work similarly to file system directories:

• Home folder: The root folder for each user
• Shared folders: Folders that have been shared with multiple users
• Subfolders: Folders nested within other folders
• Project organization: Projects can be placed in specific folders for better organization

Getting Started with Folders

List All Folders

Retrieve all folders accessible to the authenticated user:

GET https://api.marq.com/v1/folders

Example Response:

{
  "folders": [
    {
      "id": 12345,
      "name": "Marketing Campaigns",
      "parent": "home",
      "ownerUserId": 164252231,
      "createdAt": "2024-01-15T10:30:00Z",
      "projectCount": 15
    },
    {
      "id": 67890,
      "name": "Sales Collateral",
      "parent": "shared",
      "ownerUserId": 164252232,
      "createdAt": "2024-01-20T14:45:00Z",
      "projectCount": 8
    }
  ],
  "nextPageToken": "abc123"
}

Filter Folders by Parent

Use the parent parameter to filter folders by their location:

GET https://api.marq.com/v1/folders?parent=shared

Available parent values:

• home - User's personal root folder
• shared - Folders shared with the user
• {folder_id} - Subfolders within a specific folder

Create a New Folder

Create a folder in the user's home directory:

POST https://api.marq.com/v1/folders
Content-Type: application/json

{
  "name": "Q1 2024 Campaigns",
  "ownerUserId": 164252231
}

Create a Subfolder:

POST https://api.marq.com/v1/folders
Content-Type: application/json

{
  "name": "Email Templates",
  "ownerUserId": 164252231,
  "parent": 12345
}

Example Response:

{
  "id": 98765,
  "name": "Q1 2024 Campaigns",
  "parent": "home",
  "ownerUserId": 164252231,
  "createdAt": "2024-07-09T16:20:00Z",
  "projectCount": 0
}

Get Folder Details

Retrieve information about a specific folder:

GET https://api.marq.com/v1/folders/12345

Example Response:

{
  "id": 12345,
  "name": "Marketing Campaigns",
  "parent": "home",
  "ownerUserId": 164252231,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-07-05T09:15:00Z",
  "projectCount": 15,
  "subfolders": [
    {
      "id": 98765,
      "name": "Email Templates"
    }
  ]
}

Working with Projects in Folders

Create a Project in a Specific Folder

When creating a project, specify the folderId to organize it:

POST https://api.marq.com/v1/projects
Content-Type: application/json

{
  "templateId": "499caa4f-34df-4e7a-b903-e27af918b545",
  "creatorId": 164252231,
  "folderId": 12345,
  "title": "Summer Campaign Flyer",
  "projectSmartFields": [
    {
      "name": "Campaign Name",
      "value": "Summer Sale 2024"
    }
  ]
}

List Projects in a Folder

Use the project listing endpoint to filter by folder:

GET https://api.marq.com/v1/projects?folderId=12345

Pagination

When working with large numbers of folders, use pagination:

GET https://api.marq.com/v1/folders?pageSize=25&pageToken=abc123

Parameters:

• pageSize: Number of results per page (default: 25, max: 100)
• pageToken: Token from the previous response's nextPageToken

Best Practices

Folder Organization

1. Use descriptive names: Make folder names clear and searchable
2. Create a logical hierarchy: Organize by team, campaign, or project type
3. Avoid deep nesting: Keep folder structures reasonably flat for easier navigation

API Usage

1. Check ownership: Only folder owners can create subfolders
2. Handle pagination: Use pageToken for large folder lists
3. Cache folder IDs: Store frequently used folder IDs to avoid repeated API calls

Team Collaboration

1. Shared folders: Use shared folders for cross-team projects
2. Consistent naming: Establish naming conventions across your organization
3. Regular cleanup: Archive or reorganize folders as projects are completed

Common Use Cases

Marketing Team Structure

Marketing Campaigns (shared)
├── Q1 2024
│   ├── Email Templates
│   └── Social Media
├── Q2 2024
│   ├── Print Materials
│   └── Digital Assets
└── Brand Assets
    ├── Logos
    └── Templates

Sales Organization

Sales Collateral (shared)
├── Product Sheets
├── Proposals
├── Case Studies
└── Team Folders
    ├── East Coast
    └── West Coast

Error Handling

Common Error Responses

Folder not found (404):

{
  "error": "Folder not found",
  "code": "FOLDER_NOT_FOUND",
  "message": "The requested folder does not exist or you don't have access to it."
}

Insufficient permissions (403):

{
  "error": "Insufficient permissions",
  "code": "INSUFFICIENT_PERMISSIONS",
  "message": "You don't have permission to create folders in this location."
}

Invalid parent folder (400):

{
  "error": "Invalid parent folder",
  "code": "INVALID_PARENT",
  "message": "The specified parent folder is invalid or doesn't exist."
}

Notes

• Folder names must be unique within their parent directory
• Deleting a folder requires moving or deleting all projects within it first
• Shared folders maintain their own permission structure separate from individual user folders
• The ownerUserId parameter is optional when using a User token (defaults to the authenticated user)

Related Documentation

• Projects API Guide
• Authentication Guide
• Team Management

For more detailed folder management tutorials, visit our Help Center or watch our YouTube tutorials.