GET
/
folders
List Folders
curl --request GET \
  --url https://client.camb.ai/apis/folders \
  --header 'x-api-key: <api-key>'
[
  {
    "team_id": 123,
    "folder_id": 123,
    "folder_name": "<string>",
    "run_count": 1
  }
]

​
Overview

Understanding how folders work in your CAMB.AI workspace is essential for effective project management. Think of folders as digital filing cabinets that organize related tasks, transcriptions, audio files, and other assets. What makes these folders particularly powerful is their universal nature across the entire CAMB.AI platform - every task you create through any API endpoint, whether it’s audio separation, transcription, translation, voice synthesis, or any other processing service, can be organized within these same folder structures.

​
When to Use This Endpoint

This endpoint serves multiple strategic purposes in your workflow management. During initial application setup, you might retrieve all folders to populate navigation menus or project selection interfaces. As your workspace evolves, you’ll frequently use the search functionality to quickly locate specific project containers without manual browsing through extensive folder collections. The filtering capabilities make this endpoint particularly powerful for building responsive user interfaces. Rather than overwhelming users with hundreds of folders, you can implement progressive loading strategies using the limit parameter, or provide real-time search functionality that helps users find exactly what they’re looking for as they type.

​
Key Parameters and Their Strategic Applications

​
Limit Parameter: Balancing Performance and Completeness

The limit parameter operates as your primary tool for controlling response size and optimizing application performance. When you specify a limit between 1 and 100, you’re making a strategic decision about how much data to retrieve in a single request.

​
Search Query: Intelligent Folder Discovery

The search functionality transforms how users interact with large folder collections by implementing intelligent partial matching against folder names. This case-insensitive search mechanism understands that users rarely remember exact folder names, instead supporting natural search patterns that match how people actually think about their projects.

​
Integration with Broader Workspace Management

The List Folders endpoint works most effectively when integrated with other workspace management features. Folder information often serves as the foundation for task creation workflows across every API endpoint in the CAMB.AI platform, where users select organizational containers before initiating any type of processing operation, whether that’s audio separation, transcription, translation, voice synthesis, or other specialized services. This cross-service integration creates powerful organizational possibilities. Consider a multimedia localization project where you might use audio separation to isolate speaker tracks, transcription services to generate text, translation APIs to convert content into multiple languages, and voice synthesis to create dubbed audio. All of these interconnected tasks can be organized within a single project folder, creating a comprehensive workspace that tells the complete story of your content transformation journey.

Authorizations

​
x-api-key
string
header
required

The x-api-key is a custom header required for authenticating requests to our API. Include this header in your request with the appropriate API key value to securely access our endpoints. You can find your API key(s) in the 'API' section of our studio website.

Query Parameters

​
limit
integer | null

Control the maximum number of folder items returned in a single API response to optimize performance and manage data consumption. Set this value between 1 and 100 based on your application's needs - use smaller limits for faster initial loading and pagination scenarios, or larger limits when you need comprehensive folder overviews. This parameter helps balance API response speed with data completeness, ensuring your workspace queries remain responsive even with extensive folder collections.

Required range: 1 <= x <= 100
​
search_query
string | null

Filter folders by entering partial or complete folder names to quickly locate specific organizational containers within your CAMB.AI workspace. The search functionality matches against folder names using case-insensitive partial matching, allowing you to find folders like 'Marketing Projects' by searching for terms like 'market' or 'proj'. This targeted filtering becomes invaluable as your workspace grows, enabling rapid navigation to relevant project folders without scrolling through extensive folder lists.

Required string length: 2 - 255

Response

Successful Response

​
team_id
integer

Unique identifier for the team that owns this folder within the CAMB.AI workspace. This establishes the organizational hierarchy and ensures that folder access permissions align with your team's collaboration settings, allowing team members to share and manage projects collectively while maintaining proper access control.

​
folder_id
integer

Unique system identifier for this specific folder within your CAMB.AI workspace. This ID serves as the primary reference when creating new tasks, organizing existing projects, or performing folder-related operations through the API, ensuring precise folder targeting across all workspace interactions.

​
folder_name
string

Display name for the folder as it appears in your CAMB.AI workspace dashboard. Choose meaningful names that reflect the folder's purpose or project category, such as 'Marketing Audio Projects' or 'Podcast Transcriptions', to help you and your team quickly identify and navigate to the right organizational container for your tasks.

​
run_count
integer

Total number of completed tasks and processing runs currently stored within this folder. This metric provides valuable insight into folder activity levels and helps you monitor project volume, making it easier to assess workspace utilization and identify your most active project categories for better resource planning and organization.

Required range: x >= 0