Folders
Purpose and Scope
Folders are Dub's organizational layer for grouping links inside a workspace. They help teams keep campaigns, departments, clients, or affiliate programs separated without treating every short link as an isolated object. In product usage, a folder can become the boundary for day-to-day link management, analytics review, and access control. In API usage, folders are a first-class resource with create, list, update, and delete operations exposed under the OpenAPI Folders family.
The repository evidence for this page is the OpenAPI path registry for folders. That registry does not implement business logic directly; instead, it assembles the public HTTP surface by importing operation definitions and attaching them to concrete routes. This matters because OpenAPI is the contract that downstream docs, clients, and SDK workflows rely on. When a developer asks, "How do I manage folders programmatically?", the answer begins with the four operations registered in this module. Sources: apps/web/lib/openapi/folders/index.ts
Official Dub docs describe folders as a practical way to limit access to links with role-based access control on higher plans, and as a way to filter analytics by campaign or group. Those product concepts explain why folders exist: they are not just labels, but a workflow primitive for collaboration and reporting. A marketing workspace might keep SMS links, affiliate links, and department-specific campaigns in separate folders so teammates can work in the correct context and analyze performance at the same level of organization.
Relevant Source Files
apps/web/lib/openapi/folders/index.ts- Registers the Folders OpenAPI path object and maps the/foldersand/folders/{id}routes to create, list, update, and delete operation definitions.
System-to-Code Mapping
At the code level, the folder API surface is represented by foldersPaths, exported as a ZodOpenApiPathsObject. That type signals that this module participates in Dub's generated OpenAPI description rather than acting as a request handler by itself. The module imports createFolder, listFolders, updateFolder, and deleteFolder, then places each operation under the route and HTTP method that the public API should expose. Sources: apps/web/lib/openapi/folders/index.ts
This mapping creates a small but important contract. Collection-level operations live at /folders: POST creates a new folder, and GET lists folders for the authenticated workspace. Item-level operations live at /folders/{id}: PATCH updates a specific folder, and DELETE removes a specific folder. The path parameter {id} identifies the folder being changed or deleted, while the collection route works with the workspace's folder set as a whole.
Because the registry is declarative, it keeps the folder API family easy to reason about. Adding or modifying a folder operation should happen through the imported operation definition and this central path map, not by scattering route names throughout unrelated code. That separation helps the OpenAPI generator keep documentation consistent with implementation modules and makes it clear which operations belong to the Folders API family.
API Operations Reference
| Route | Method | Operation module | Purpose |
|---|---|---|---|
/folders | POST | createFolder | Create a folder in the authenticated workspace. |
/folders | GET | listFolders | Retrieve a paginated list of folders for the authenticated workspace. |
/folders/{id} | PATCH | updateFolder | Update a folder identified by id. |
/folders/{id} | DELETE | deleteFolder | Delete a folder identified by id. |
The official API documentation for listing folders describes query parameters such as search, page, and pageSize, with a default page size of 50 and a maximum of 50. That reader-facing contract fits the code structure here: the collection GET /folders operation is the place where filtering and pagination belong. Consumers should treat listing as a workspace-scoped query, then use the returned folder identifiers when updating, deleting, assigning links, or filtering analytics elsewhere in Dub.
Create, update, and delete should be understood as administrative operations on the workspace's organizational model. Creating a folder gives teams a new container for links; updating changes the folder's metadata or configuration as defined by the imported schema; deleting removes that organizational unit. The path map does not show authorization rules directly, but the product documentation frames folders as permission-aware resources, especially when RBAC is enabled for workspaces that need fine-grained teammate access.
Product Workflows
The most common folder workflow starts in the dashboard: create a folder for a campaign, client, department, or partner motion, then add links to it. Once links are grouped, the folder becomes useful beyond visual organization. Teams can filter analytics by folder to compare campaign performance, isolate affiliate traffic, or build reports around a specific marketing channel. This is why folder APIs should be treated as part of the broader link attribution system rather than as a standalone settings feature.
Folders also support collaboration patterns. Official guidance describes workspace owners as having access to created folders, while folder-level RBAC can limit what other teammates see and do. That makes the folder boundary useful when a single Dub workspace contains multiple teams. For example, a central growth team can maintain oversight while individual departments only access the folders relevant to their campaigns. API consumers building internal tooling should preserve that mental model by respecting workspace authentication and folder identifiers.
For analytics, folders provide a human-scale reporting dimension. Instead of filtering by many individual short links, a user can create a folder, add relevant links, and view aggregated click and conversion analytics for that folder. This workflow is especially useful when campaigns contain multiple destination URLs, channels, or partner links. The folder API operations documented here maintain the lifecycle of that grouping layer; analytics APIs and dashboard filters then use the grouping to answer performance questions.
Implementation Details
The folder path registry follows the same shape developers should expect from other Dub OpenAPI families: import each operation definition, export a typed paths object, and attach methods to route keys. This makes apps/web/lib/openapi/folders/index.ts a navigation point for anyone trying to find the folder API surface. If you are tracing behavior, start here to confirm the route and HTTP method, then follow the imported operation module that corresponds to the action you need. Sources: apps/web/lib/openapi/folders/index.ts
A useful way to read this module is as the boundary between product vocabulary and generated API machinery. Product vocabulary says users create folders, list folders, update folders, and delete folders. The OpenAPI registry turns that vocabulary into exact HTTP routes. Because the exported object is typed as ZodOpenApiPathsObject, the surrounding OpenAPI assembly can consume it consistently with the rest of Dub's API reference generation.
Next Steps
If you are integrating with folders, begin with GET /folders to discover existing folder IDs, then use POST /folders when your application needs to create a new organizational unit. Use PATCH /folders/{id} for changes and DELETE /folders/{id} only when the folder should no longer be available as a grouping boundary. After folder lifecycle management is in place, read the analytics and links pages to understand how folders participate in reporting and link organization across Dub.