API Reference Introduction

Purpose and Scope

Dub’s API reference is the developer entry point for managing Dub workspace resources programmatically. The public documentation describes the API as a REST API served over HTTPS at https://api.dub.co, authenticated with an Authorization: Bearer dub_xxxxxx header, and organized around resource families such as links, partners, tracking events, and analytics. In practice, readers usually arrive here with one of three goals: automate link creation, connect attribution data to an application, or understand how the repository’s packages support API-facing workflows outside the hosted dashboard.

This page orients those readers before they move into endpoint-specific reference pages. It does not replace the detailed pages for links, analytics, domains, folders, tracking, partners, commissions, payouts, QR codes, tags, or embed tokens. Instead, it explains the contract shared by those families: authenticated workspace-scoped operations, resource-specific request and response shapes, and tooling surfaces that let developers call or support the API from command-line, package, and application code. The source evidence here is focused on public package boundaries rather than individual endpoint route handlers, so the emphasis is on how API consumers encounter Dub from the repository’s exported surfaces.

Sources: package.json, packages/cli/package.json, packages/cli/src/index.ts

Core API Primitives

The first primitive is the workspace. Dub API keys are tied to a workspace, so API operations act on resources owned by that workspace rather than on a global account. This is why the API reference consistently frames tasks as managing resources in “your Dub workspace.” A server-side API key is the right credential for REST calls that create links, retrieve analytics, or manage other workspace resources. Publishable keys, described separately in the authentication documentation, serve a different role for client-side conversion tracking and should not be treated as a substitute for server-to-server API keys.

The second primitive is the resource family. A family is a related group of operations and schemas: links cover create, retrieve, list, update, upsert, delete, bulk operations, and counts; analytics covers retrieval by supported dimensions; tracking covers lead, sale, and open events; domains and folders organize link infrastructure; partner-program resources cover partners, bounties, commissions, and payouts. The official documentation’s introductory examples point to creating links, creating partners, tracking lead and sale events, and retrieving analytics because those are the highest-level jobs the API enables.

The third primitive is the client surface. Developers can call the REST API directly with cURL or use generated SDKs, while Dub’s own CLI package depends on the published dub package and presents terminal commands that wrap common API-oriented tasks. The CLI package metadata declares the executable name dub, marks the package as public, and depends on libraries for OAuth, prompts, configuration storage, HTTP fetching, validation, and the dub SDK. That combination shows that the CLI is a first-party API consumer rather than a separate backend.

Sources: packages/cli/package.json, packages/cli/src/index.ts

Public Surfaces in the Repository

The root monorepo defines Dub as a private workspace with AGPL licensing at the repository level and scripts for building, testing, formatting, and publishing packages. For API-reference readers, the most important root scripts are the package publishing commands because they show which code surfaces are intentionally distributable: the CLI, embed packages, UI package, utility package, and Tailwind config each have explicit publish scripts. The same root file sets pnpm@9.15.9 as the package manager, so contributors working on API-adjacent packages should use pnpm-based workflows rather than ad hoc npm or yarn commands.

The CLI is the most direct repository bridge from API documentation to an installed developer tool. Its entry point creates a Commander program named dub, describes it as “A CLI for shortening links with the Dub API,” registers version handling, and adds five command groups: login, config, domains, shorten, and links. Those names mirror the API reference’s common user journeys: authenticate, choose workspace or domain configuration, manage domains, create a short link quickly, and perform broader link operations. The CLI also installs signal handlers for SIGINT and SIGTERM, which keeps terminal interruption behavior predictable.

The UI and utility packages are not API clients by themselves, but they are part of the public surface that supports API-driven product experiences. @dub/ui re-exports component families such as buttons, tables, modals, filters, pagination controls, date pickers, UTM builders, link previews, QR-adjacent display components, and layout primitives. @dub/utils re-exports constants and functions. When an API response is displayed in the dashboard, embedded integration, or internal tooling, these packages provide the reusable presentation and formatting layer rather than duplicating component code beside every endpoint consumer.

Sources: package.json, packages/cli/src/index.ts, packages/ui/src/index.tsx, packages/utils/src/index.ts

System-to-Code Mapping

Reader concern	Repository surface	What it tells you
API documentation entry point	Official API docs	REST over HTTPS, https://api.dub.co, Bearer token authentication, and resource families
Terminal usage	packages/cli/src/index.ts	The dub command registers login, config, domains, shorten, and links commands
CLI package contract	packages/cli/package.json	The published package exposes the dub binary from dist/index.js and depends on the dub SDK
Shared interface components	packages/ui/src/index.tsx	Dashboard and integration surfaces reuse exported components, hooks, icons, layout, and content helpers
Shared constants and functions	packages/utils/src/index.ts	Utility code is exported from constants and functions as a package boundary
Operational notifications	packages/email/src/index.ts	Email sending uses Resend when configured, falls back to SMTP, and supports batch sending
Monorepo operations	package.json	Turborepo scripts build, lint, test, format, and publish API-adjacent packages

This mapping matters because the API reference is not only a list of HTTP endpoints. It is also a contract that must be reflected in tooling, dashboard UI, notification flows, and published packages. For example, if a link-management endpoint changes shape, the impact can extend to CLI link commands, dashboard tables, reusable URL utilities, and user-facing emails that report import or payout activity. The repository therefore separates concerns: the API contract is documented externally and consumed internally through packages that have clear build and export boundaries.

Sources: package.json, packages/cli/package.json, packages/email/src/index.ts, packages/ui/src/index.tsx, packages/utils/src/index.ts

Execution Flow for API Consumers

A typical server-to-server integration starts by creating an API key in a Dub workspace, storing it securely in backend configuration, and sending requests to the HTTPS base URL with a Bearer token. From there, the integration chooses a resource family. A marketing automation service might create short links and later retrieve analytics. A partner platform might create partners, track lead and sale events, and reconcile commissions or payouts. A product application might send open events for deep links and use analytics retrieval to report campaign performance back to an internal dashboard.

The CLI follows a similar conceptual flow but packages it as commands. The user invokes dub, authenticates with login, adjusts local settings with config, manages domain state through domains, creates one-off short URLs with shorten, and performs richer link operations through links. The CLI package’s dependency list shows supporting concerns that are common in API clients: configstore for local configuration, prompts and open for interactive login flows, node-fetch for HTTP, zod for validation, ora and chalk for terminal feedback, and the dub SDK for API calls.

Operational workflows can also trigger notifications. The email package exposes sendEmail and sendBatchEmail, selecting Resend when configured and falling back to SMTP when SMTP_HOST and SMTP_PORT are present. If neither provider is configured, it logs that email sending failed because neither service is set up, and the batch function returns a neutral { data: null, error: null } result. This behavior is relevant to API-driven features that notify users after background work, such as imports, payouts, or other asynchronous operations.

Sources: packages/cli/package.json, packages/cli/src/index.ts, packages/email/src/index.ts

Compact Reference

Name	Type	Source-backed details
dub	CLI binary	Declared in packages/cli/package.json as bin.dub pointing to ./dist/index.js
login	CLI command	Registered by the CLI entry point before parsing arguments
config	CLI command	Registered for local CLI configuration workflows
domains	CLI command	Registered for domain-related API workflows
shorten	CLI command	Registered for fast URL-shortening workflows
links	CLI command	Registered for link-management workflows
sendEmail(opts)	Email export	Uses Resend when available, then SMTP fallback, then logs missing provider configuration
sendBatchEmail(emails, options)	Email export	Sends through Resend when available, otherwise maps each email through SMTP fallback
@dub/ui exports	UI package surface	Re-exports component, hook, icon, layout, content, misc, and logo modules from src/index.tsx
@dub/utils exports	Utility package surface	Re-exports ./constants and ./functions
build	Root script	Runs turbo build across the monorepo
test	Root script	Runs turbo run test
publish-cli	Root script	Builds @dub/cli, changes into packages/cli, and runs npm publish

Use this reference as a starting checklist when tracing an API-facing behavior. If the behavior is a documented endpoint, begin with the relevant API family page. If the behavior is a terminal workflow, inspect the CLI command group registered in the entry point. If the behavior affects user-visible dashboard presentation, check whether the UI package already exports a reusable component. If the behavior formats identifiers, URLs, dates, or constants, look through the utility package boundary before adding one-off helpers.

Sources: package.json, packages/cli/package.json, packages/cli/src/index.ts, packages/email/src/index.ts, packages/ui/src/index.tsx, packages/utils/src/index.ts

Relevant Source Files

• package.json — Defines the monorepo as private, declares the AGPL repository license, pins the pnpm package manager, and provides Turborepo scripts for build, lint, test, format, clean, and publishing selected packages.
• packages/cli/src/index.ts — Implements the executable CLI entry point, creates the Commander program named dub, sets the description and version flag, registers command groups, and parses terminal input.
• packages/email/src/index.ts — Exports email sending functions that choose Resend when configured, fall back to SMTP when configured, and provide batch email behavior for notification workflows.
• packages/ui/src/index.tsx — Re-exports the shared UI package surface, including styles, components, hooks, icons, layout helpers, content primitives, miscellaneous utilities, and Dub logos.
• packages/utils/src/index.ts — Defines the public utility package boundary by re-exporting constants and functions.
• packages/cli/package.json — Defines the public CLI package metadata, dub binary, distribution entry points, scripts, dependencies, and MIT package license.

Next Steps

After this introduction, choose the page that matches the resource you need to automate. Start with the Links API if you are creating or managing short URLs, the Track API if you are sending lead, sale, or open events, and the Analytics API if you need reporting data. Use the API Authentication page before implementing production calls, especially to distinguish server-side API keys from publishable keys. If you want a terminal-first workflow, read the CLI reference next; if you are contributing to dashboard behavior around API resources, follow the UI and utils package pages to reuse the existing package boundaries.