Folders API

Purpose and Scope

The Folders API is the OpenAPI route family for organizing Dub links into named containers. A folder is useful when a workspace needs to group links by campaign, department, partner motion, or reporting boundary rather than treating every short link as one flat list. The first-party product documentation frames folders as both an organizational feature and an access-control boundary: teams can use folders to limit link visibility through role-based access control, and analytics can be filtered by folder once links have been assigned to one.

In the repository, the Folders API page should be read as a reference for the route surface rather than the full implementation of folder persistence. The source module apps/web/lib/openapi/folders/index.ts declares a ZodOpenApiPathsObject named foldersPaths and wires the four public folder operations into their HTTP paths. That makes this file the API-family index: it is the place where the generated OpenAPI representation learns that collection-level folder operations live at /folders, while single-folder mutations live at /folders/{id}.

Sources: apps/web/lib/openapi/folders/index.ts

Relevant Source Files

• apps/web/lib/openapi/folders/index.ts - Declares the foldersPaths OpenAPI path object, imports the folder operation definitions, and maps create, list, update, and delete behavior to the public Folders API routes.

Sources: apps/web/lib/openapi/folders/index.ts

API Components

The source defines the folder route group by importing four operation modules: createFolder, deleteFolder, listFolders, and updateFolder. Those imported operation definitions are then assigned to HTTP methods in the exported foldersPaths object. This pattern is important because it separates the route-family registry from each operation’s detailed schema. The index file does not duplicate request and response definitions; instead, it composes operation modules into the OpenAPI path tree so the broader API documentation can present folders as one coherent resource family.

The path mapping is compact but expressive. The collection route /folders accepts post for creation and get for listing. The item route /folders/{id} accepts patch for updates and delete for deletion. The {id} path segment communicates that update and delete target an existing folder resource, while create and list operate against the workspace’s folder collection. This mirrors common REST conventions and keeps client behavior predictable across generated documentation, SDKs, and hand-written integrations.

Sources: apps/web/lib/openapi/folders/index.ts

Operation Reference

Use POST /folders when the client needs to create a new organizational container before assigning links to it or before setting up a campaign-specific reporting workflow. Because the route is registered on the collection path, callers should treat folder creation as a workspace-scoped action: the new folder belongs to the authenticated workspace context used by the API request. Official product docs also describe folders as the prerequisite for later analytics filtering, so creation is typically the first step before links are grouped and campaign reports become meaningful.

Use GET /folders when the client needs to discover available folders for selection, filtering, migration, or administration. The official API reference describes this operation as retrieving a paginated list of folders for the authenticated workspace, and its documented query parameters include search, page, and pageSize. From a client-design perspective, that means folder pickers and administration screens should not assume the full folder list is always loaded at once. They should support incremental fetching and search-driven narrowing when the workspace contains many folders.

Use PATCH /folders/{id} when changing metadata or settings for an existing folder. The route registration makes the folder identifier part of the URL, which keeps the target resource unambiguous and leaves the request body for fields that are being changed. This also makes partial-update behavior easier for clients to reason about: a UI can let a user edit folder details, submit only the intended changes to the update operation, and keep the rest of the folder collection stable.

Use DELETE /folders/{id} when removing a folder resource. Because deletion is registered separately from updates, clients should model it as a distinct destructive action rather than a special case of editing. In product workflows, folder deletion should be treated carefully because folders can be part of link organization, access policy, and analytics filtering. The OpenAPI path index confirms that deletion is a first-class API operation, so clients can expose it behind confirmation flows, administrative controls, or automation scripts where appropriate.

Sources: apps/web/lib/openapi/folders/index.ts

System-to-Code Mapping

The Folders API is represented as an exported object rather than as route handlers in this module. The type annotation ZodOpenApiPathsObject indicates that the object is meant for OpenAPI path assembly using the zod-openapi ecosystem. Each value assigned inside foldersPaths is an operation definition imported from a neighboring folder module. As a result, this page’s most reliable source-level contract is the route-to-operation registry: consumers of the generated spec should expect exactly the two route keys and four methods declared here.

This registry style helps keep the API reference maintainable. If the request schema for creating a folder changes, the route index can remain stable while the createFolder operation module evolves. If the API adds a new folder operation, the family index is where the new method or route must be registered before it appears in the assembled OpenAPI paths. That makes apps/web/lib/openapi/folders/index.ts a useful review target when validating whether public folder capabilities have been exposed through the documentation and generated schema.

Sources: apps/web/lib/openapi/folders/index.ts

export const foldersPaths: ZodOpenApiPathsObject = {
  "/folders": {
    post: createFolder,
    get: listFolders,
  },
  "/folders/{id}": {
    patch: updateFolder,
    delete: deleteFolder,
  },
};

Product Workflow Context

Folders are not only an API resource; they support real user workflows in the Dub product. Official docs describe folder RBAC as a way to limit access to links for selected teammates, especially in workspaces where different marketing teams or departments should only see the links relevant to them. When building against the API, that means folder automation should be planned with permission boundaries in mind. A script that creates folders for departments or campaigns may also become part of a broader administrative workflow that assigns members and access levels in the dashboard.

Folders also participate in analytics workflows. The official analytics guide explains that users can filter analytics by folders after creating a folder and adding links to it. For API consumers, this makes the folder lifecycle more than simple CRUD. A folder created through POST /folders can later become a reporting dimension for campaign-specific analysis. A folder listed through GET /folders can populate an analytics filter. A folder updated or deleted through item-level routes can affect how teams navigate existing reporting structures.

Sources: apps/web/lib/openapi/folders/index.ts

Implementation Details and Client Guidance

When implementing a client, model folders as a workspace-scoped collection with item-level operations keyed by folder id. The OpenAPI index uses /folders/{id} rather than a nested path under links, which means folders are exposed as their own resource family. This is the right abstraction for dashboards, CLIs, and internal tools that need to manage folders independently from individual links. Link assignment and analytics filtering can then build on top of the folder identifiers returned by create or list operations.

For list views, prefer pagination-aware interfaces. The official API reference for GET /folders documents page and pageSize, with pageSize capped at 50, and a search parameter for narrowing results. Even though those parameter definitions live in the operation module rather than in the path index shown here, they affect how clients should behave. A robust integration should request one page at a time, expose search when the user is selecting a folder, and avoid assuming folder names are globally unique unless the operation schema explicitly guarantees that elsewhere.

For destructive and administrative actions, make the route shape visible in logs and review flows. PATCH /folders/{id} and DELETE /folders/{id} both depend on a concrete identifier, so a production client should log the folder id it is about to modify and present enough context for a human operator to confirm the action. This is especially important because folders can reflect team boundaries and campaign reporting. Treat create, update, and delete calls as changes to workspace organization rather than as incidental metadata edits.

Sources: apps/web/lib/openapi/folders/index.ts

Next Steps

Start with GET /folders if you are integrating an existing workspace and need to discover current folder identifiers. Use POST /folders when provisioning a new campaign, department, or reporting group. After folders exist, attach links through the link-management workflows and use analytics filtering to evaluate grouped performance. If your workspace uses folder RBAC, coordinate API automation with the dashboard permissions model so folders are both useful for organization and safe as access boundaries.

For broader context, read the pages on links-api-overview, manage-links, and analytics-api next. Folders become most valuable when they connect those three areas: links are the resources being organized, analytics are the reports that can be filtered by that organization, and the API reference defines the stable route surface that external clients rely on.

Sources: apps/web/lib/openapi/folders/index.ts