OpenAPI Specs

Purpose and Scope

Dub’s OpenAPI specification is the source of truth for the public HTTP API surface that powers API documentation and SDK-oriented tooling. In this repository, the specification is not written as a static YAML file in the supplied evidence. Instead, it is assembled in TypeScript with zod-openapi, combining reusable Zod schemas, operation objects, path-family modules, error response components, and API metadata into a single OpenAPI 3.0.3 document. This keeps the API contract close to the same schema system used by application code while still producing a standard OpenAPI document for external consumers.

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

The generated document describes Dub as “the modern link attribution platform for short links, conversion tracking, and affiliate programs,” matching the product framing used in the public docs. That description matters because the API surface is organized around those same product families: links, analytics, events, tags, folders, domains, conversion tracking, customers, partners, commissions, payouts, embed tokens, QR codes, and bounties. The central module makes these areas visible as one coherent API rather than a set of disconnected route definitions.

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

Relevant Source Files

apps/web/lib/openapi/index.ts — assembles the root OpenAPI document with metadata, server configuration, path spreads, shared schemas, bearer-token security, and reusable error responses.
apps/web/lib/openapi/analytics/index.ts — defines the /analytics GET operation, including query parameters, response union variants, the Analytics tag, and bearer-token security.
apps/web/lib/openapi/links/index.ts — maps the Links API route family, including create, list, count, info, update, delete, bulk, and upsert paths.
apps/web/lib/openapi/track/index.ts — maps the Track API route family for lead, sale, and deep-link open conversion events.

System-to-Code Mapping

The root OpenAPI module exports document, created by calling createDocument. That call supplies the OpenAPI version, info metadata, production server URL, paths, components, and security schemes. The production server is declared as https://api.dub.co, which makes the spec directly usable by generated clients and documentation tools that need a base API URL. The info block also contains support contact details and an AGPL-3.0 license URL, so consumers can understand both support routing and the repository’s licensing posture from the generated API contract.

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

Path registration happens by spreading imported path objects into the root paths object. This design gives each API family a local module while preserving one complete OpenAPI document at the boundary. In the supplied evidence, linksPaths, analyticsPath, and trackPaths show the pattern clearly: each family exports a ZodOpenApiPathsObject, and the root document merges those exports with additional families such as domains, folders, customers, partners, commissions, payouts, embed tokens, QR codes, tags, events, and bounties. The result is modular source code with a unified external contract.

Sources: apps/web/lib/openapi/index.ts, apps/web/lib/openapi/analytics/index.ts, apps/web/lib/openapi/links/index.ts, apps/web/lib/openapi/track/index.ts

Shared components are registered in the same root document. The visible schemas include LinkSchema, LinkTagSchema, FolderSchema, DomainSchema, webhookEventSchema, and LinkErrorSchema. These component registrations make common domain objects reusable across operations instead of duplicating shapes in every route. The document also defines a token security scheme of type HTTP bearer with the description “Default authentication mechanism” and an x-speakeasy-example value of DUB_API_KEY, which is a signal that the spec is prepared for SDK-generation workflows as well as human-readable API docs.

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

API Family Examples

The Analytics API module shows how a single operation can describe multiple response shapes. It defines retrieveAnalytics for GET /analytics, with operation id retrieveAnalytics, a Speakeasy name override of retrieve, a summary describing analytics for a link, domain, or authenticated workspace, and query parameters from analyticsQuerySchema. Its 200 response is a union of analytics result families, including count, timeseries, continents, countries, regions, cities, devices, browsers, operating systems, triggers, referers, referer URLs, top links, and top URLs. This mirrors Dub’s analytics product model, where the same endpoint can return different dimensions depending on query parameters.

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

The Links API module is a compact route map for Dub’s core short-link resource. It registers POST /links for creation and GET /links for listing, then adds specialized endpoints for counts and link lookup via /links/count and /links/info. Mutating a specific link is modeled at /links/{linkId} with PATCH and DELETE. Bulk workflows live under /links/bulk with POST, PATCH, and DELETE, while idempotent create-or-update behavior is exposed as PUT /links/upsert. This route layout communicates the supported link-management workflows before a reader even opens the individual operation modules.

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

The Track API module exposes conversion-tracking primitives as explicit paths rather than hiding them behind a generic events endpoint. It maps POST /track/lead, POST /track/sale, and POST /track/open to separate operation definitions. In product terms, this separates leads, sales, and deep-link open events, which are different attribution signals. In OpenAPI terms, it lets each event type have its own request and response schema in its operation file while the path index stays small and predictable.

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

Compact Reference

Area	Export or path	Contract shown in source
Root document	`document`	OpenAPI 3.0.3 document created with `createDocument`
Server	`https://api.dub.co`	Production API server URL
Authentication	`token`	HTTP bearer security scheme with `DUB_API_KEY` Speakeasy example
Analytics	`GET /analytics`	Retrieves analytics for a link, a domain, or the authenticated workspace
Links	`/links`, `/links/{linkId}`, `/links/bulk`, `/links/upsert`	Core link creation, listing, updating, deletion, bulk, and upsert routes
Track	`/track/lead`, `/track/sale`, `/track/open`	Conversion tracking routes for lead, sale, and open events

Implementation Details

When adding or changing a public API operation, follow the existing module boundary: define the operation in the relevant family module, export or include it in that family’s ZodOpenApiPathsObject, and make sure the family is spread into the root document. If a route returns a common object, prefer registering or reusing a named schema component so generated docs and SDKs get stable model names. If an operation participates in authenticated API access, use the bearer-token security pattern shown by the analytics operation and the root token security scheme.

Sources: apps/web/lib/openapi/index.ts, apps/web/lib/openapi/analytics/index.ts

The repository also uses Speakeasy-oriented OpenAPI extensions in the supplied evidence. The root security scheme includes x-speakeasy-example, and the analytics operation includes x-speakeasy-name-override. Those fields do not change HTTP behavior, but they influence generated SDK ergonomics and examples. Treat them as part of the developer-experience layer of the spec: they help external client libraries expose clearer method names and authentication examples while the standard OpenAPI fields continue to describe routes, parameters, responses, and security.

Sources: apps/web/lib/openapi/index.ts, apps/web/lib/openapi/analytics/index.ts

Next Steps

To understand the OpenAPI document from a consumer’s perspective, read the API reference introduction and authentication pages next. To work on a specific resource family, move from this page to the matching API page: Links API for short-link operations, Analytics API for reporting dimensions, or Track API for conversion events. Contributors changing API behavior should update the relevant operation module and verify that the root document still assembles the path family, shared schemas, security scheme, and error responses expected by generated documentation and SDK tooling.

Ask a question...