QR, Tags, and Embed Tokens API

Purpose and Scope

This page documents three smaller API families that sit beside Dub's larger links, analytics, domains, and partner-program APIs: QR code retrieval, tag management, and referral embed-token creation. They are grouped here because each family has a compact OpenAPI path surface, but each still supports an important product workflow. QR codes turn a Dub link into a scannable asset. Tags organize links and partner-program records for filtering and reporting. Embed tokens support secure embedding of Dub referral experiences in third-party surfaces.

In the repository, these APIs are represented as OpenAPI path objects rather than application route handlers. That distinction matters for readers working on SDKs, generated API documentation, or contract changes: the files here describe the public API shape, names, tags, request parameters, response media types, and path-to-operation wiring. Runtime behavior is implemented elsewhere, but these indexes are the source-level contract that tells the OpenAPI assembler which endpoints exist and how they are grouped.

Sources: apps/web/lib/openapi/qr/index.ts, apps/web/lib/openapi/tags/index.ts, apps/web/lib/openapi/embed-tokens/index.ts

Relevant Source Files

apps/web/lib/openapi/qr/index.ts - Defines the getQRCode OpenAPI operation and mounts it as GET /qr through qrCodePaths.
apps/web/lib/openapi/tags/index.ts - Defines the tag API path map by wiring create, list, update, and delete operations onto /tags and /tags/{id}.
apps/web/lib/openapi/embed-tokens/index.ts - Defines the embed-token API path map and mounts the referral embed-token creation operation at POST /tokens/embed/referrals.

API Components

The QR API exposes a single operation named getQRCode. Its summary is Retrieve a QR code, and its description narrows the scope to retrieving a QR code for a link. The operation accepts query parameters defined by getQRCodeQuerySchema, returns a successful 200 response as image/png, and uses a string schema for that image response body. It also spreads the shared openApiErrorResponses object into the response map, which means QR retrieval participates in the repository's common OpenAPI error-response contract rather than defining a private error model in this file.

The QR path map is intentionally minimal: qrCodePaths mounts only /qr with a get method that points at getQRCode. The operation is tagged as QR Codes, and it includes the Speakeasy extension x-speakeasy-name-override set to get. That extension is important when downstream SDK tooling turns OpenAPI operations into generated client methods, because it lets the generated QR-code client use a concise method name without changing the public operation ID.

The Tags API exposes a small CRUD-style collection. The path object maps /tags to post: createTag and get: getTags, then maps /tags/{id} to patch: updateTag and delete: deleteTag. Even though the request schemas and response schemas are delegated to operation modules, this index still establishes the public resource layout: clients create tags on the collection, list tags from the collection, and modify or delete a specific tag by passing an id path parameter. That makes tags a first-class API resource rather than only a dashboard-side convenience.

The embed-token API currently exposes one path: /tokens/embed/referrals with a post method wired to createReferralsEmbedToken. The route name communicates two important boundaries. First, it belongs to the token family rather than the partner or links family. Second, the token is scoped to referrals embedding, not to arbitrary embedded access. For developers building integrations, that means the API should be treated as an authorization bootstrap step for Dub's referral embed surface, not as a general-purpose replacement for normal API authentication.

Sources: apps/web/lib/openapi/qr/index.ts, apps/web/lib/openapi/tags/index.ts, apps/web/lib/openapi/embed-tokens/index.ts

Compact Reference

| --- | --- | --- | --- | --- |

| Tags | /tags/{id} | PATCH | updateTag | Update an existing tag identified by id. |

| Tags | /tags/{id} | DELETE | deleteTag | Delete an existing tag identified by id. |

The QR response contract is the most explicit one in the supplied source. A successful QR request returns content under the image/png media type rather than JSON. API consumers should plan for binary or image handling in the caller, even though the schema is represented as a Zod string in the OpenAPI declaration. This is different from many resource APIs in Dub, where clients typically exchange JSON objects. If you are generating an SDK or writing examples, highlight that the caller receives an image payload and should not expect a tag-like resource object.

The Tags API should be understood as an organizational layer over Dub resources. Official product documentation describes tags as color-coded labels that can be assigned to links, used to group campaigns or clients, and used to filter links and analytics. It also documents partner tags as a flexible way to organize partners by source, status, campaign, relationship, or lifecycle stage. The OpenAPI path map here is the API doorway into that model: it gives clients a way to create, list, update, and delete tags so that tagging workflows can be automated outside the dashboard.

The embed-token endpoint belongs to a different integration pattern. Instead of representing a long-lived business resource like a tag, it creates a token that a third-party site can use when embedding Dub's referral dashboard or referral-related experience. That aligns with Dub's separate embed packages, where the embedded UI needs a safe, scoped way to operate inside another application. Keep this distinction clear in API docs and examples: local tools and normal API keys perform server-side management, while an embed token is a purpose-built credential for an embedded referrals surface.

Sources: apps/web/lib/openapi/qr/index.ts, apps/web/lib/openapi/tags/index.ts, apps/web/lib/openapi/embed-tokens/index.ts

System-to-Code Mapping

All three files export ZodOpenApiPathsObject values. That shared type is the bridge between individual API-family modules and the generated OpenAPI specification. Each path object uses URL strings as keys and HTTP method names as nested keys, mirroring the structure OpenAPI expects for path definitions. When a new operation is added to one of these families, the path index is the place where the operation becomes visible to OpenAPI consumers. If an operation module exists but is not mounted here, it is not part of this path-family export.

The QR module is slightly different because it defines both the operation object and the path map in the same file. The operation is typed as ZodOpenApiOperationObject, imports its query schema from the QR Zod schema module, imports shared error responses, and imports zod/v4 to describe the PNG response content. This makes the QR endpoint self-contained at the contract layer: a reader can see the operation ID, SDK naming override, summary, description, query schema hookup, response content type, shared errors, and OpenAPI tag without following additional operation files.

The Tags and Embed Tokens modules are index-style routers for OpenAPI definitions. They import operations from sibling modules and compose them into a path map. That pattern keeps each operation's detailed schema and description separate while giving the family a concise overview file. For contributors, this means path indexes are good places to review endpoint coverage and HTTP method placement, while operation files are the right places to change request bodies, parameters, examples, summaries, or response schemas.

Sources: apps/web/lib/openapi/qr/index.ts, apps/web/lib/openapi/tags/index.ts, apps/web/lib/openapi/embed-tokens/index.ts

Implementation Details and Reader Guidance

When documenting or consuming the QR endpoint, keep the media type front and center. A generated client method may be named from the Speakeasy override, the OpenAPI operation is still getQRCode, and the response is a PNG image. That combination affects SDK ergonomics, test fixtures, and examples. A useful example should show callers constructing the query parameters required by getQRCodeQuerySchema, then treating the response as image content. Avoid presenting it as a JSON QR-code metadata endpoint unless another source explicitly adds that behavior.

When documenting tags, start with user intent before API mechanics. A tag is a label for organizing records, and the official docs emphasize grouping links by campaigns or clients, filtering link lists, and filtering analytics reports by tag. The API path map then explains how automation supports those workflows: create a tag before assigning it elsewhere, list existing tags for a workspace, update tag details when naming or color conventions change, and delete tags when they are no longer useful. The supplied index does not show assignment endpoints, so keep this page focused on tag resource management.

When documenting embed tokens, explain that token creation is normally a server-side preparatory step. An application that hosts Dub's referrals embed can request a referral embed token, then pass the resulting credential to the embedded experience according to the embed package's expectations. The OpenAPI path name deliberately nests the endpoint under /tokens/embed/referrals, which signals scope and intended use. Do not mix this endpoint with API-key authentication pages except to clarify that it produces a scoped token for an embed workflow rather than serving as the primary API credential.

Execution Flow

A typical QR-code flow starts after a link already exists. The client calls GET /qr with the query parameters described by the QR schema, receives a 200 response with image/png content, and stores or displays that image in a campaign asset, printed material, event page, or dashboard surface. Error handling should follow the shared OpenAPI error responses included in the operation. Because the response is not JSON, clients should also ensure their HTTP library does not automatically parse the response body as an object.

A typical tag-management flow starts by creating a set of organizational labels for a workspace. A client can call POST /tags to create a tag, call GET /tags to retrieve the available labels, and then use the broader Dub product workflows to associate those tags with links or partner records. Later, the client can call PATCH /tags/{id} when a label needs to change or DELETE /tags/{id} when a label should be removed. Analytics filtering by tags becomes useful after tagged links accrue traffic.

A typical referral embed flow starts in the host application's backend. The backend calls POST /tokens/embed/referrals through the Dub API surface, receives a referrals embed token from the operation implemented by createReferralsEmbedToken, and provides that token to the frontend embed integration. This keeps privileged token creation on the server while allowing the frontend to render an embedded referrals experience. For next steps, read the broader Embeds page for package-level integration details and the API Authentication page for the normal API credentials used to call token-creation endpoints.

Sources: apps/web/lib/openapi/qr/index.ts, apps/web/lib/openapi/tags/index.ts, apps/web/lib/openapi/embed-tokens/index.ts

Ask a question...