Skip to main content
Glama
Dub MCP Server
by thenavidm

Dub MCP Server & CLI

npm CI License YouTube X LinkedIn

Dub MCP server and CLI for Codex and AI agents. 61 shared tools for current link, analytics, conversion and partner workflows, private workspace profiles and exact reviewed link batches.

One package provides a task CLI, local stdio MCP and versioned desktop bundle. Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI. Complete setup: navid.me.

The terminal illustrates actual commands, not a recorded provider account session. Node 22+ is required for manual installs; private workspace API access and provider plans/costs remain separate.

Two ways to use it

Command line

dub-cli tools
dub-cli list-links --page-size 5 --account work --agent
dub-cli get-link --link-id YOUR_LINK_ID --account work --agent

MCP server, for your AI app

codex mcp add dub --env DUB_TOKEN_FILE=/absolute/private/dub.txt -- npx -y @thenavidm/dub-mcp-cli@latest

Which one

Where you work

Route

Codex / Cursor / shell agents

Task CLI, local MCP or both

Claude Desktop

Versioned custom extension or manual stdio

Scripts / CI

Shared task CLI and approval/workspace routing

Remote-only clients / current provider guide

Official hosted MCP

Related MCP server: Flodesk MCP Server

Features

Capability

CLI command

MCP tool

Links and native bulk

list-links / create-link / bulk-create-links

list_links / create_link / bulk_create_links

Analytics and events

get-link-stats / list-events

get_link_stats / list_events

Tags, folders and domains

list-tags / list-folders / list-domains

list_tags / list_folders / list_domains

Partners and applications

list-partners / list-program-applications

list_partners / list_program_applications

Financial records

list-commissions / list-payouts

list_commissions / list_payouts

Conversion tracking

track-lead / track-sale / track-open

track_lead / track_sale / track_open

Private PNG/embed output

get-qr-code / create-referrals-embed-token

get_qr_code / create_referrals_embed_token

Exact ordered review/submission

preview-link-batch / submit-link-batch

preview_link_batch / submit_link_batch

Private profiles/native schemas

list-accounts / get-operation-schema

list_accounts / get_operation_schema

Contents

Number

Section

What it covers

1

What you can ask it

Requested link/partner work

2

Quick install

npm binaries and discovery

3

Set up Dub access

Workspace keys, quotas and revocation

4

Connect your client

Codex first and supported clients

5

Check it works

Local checks and deliberate read

6

Output, flags and exit codes

JSON, private outputs and stable exits

7

MCP or CLI and token cost

Measured in Claude Code and Codex

8

Every tool and argument

All 61 tools and 57 native routes

9

Link and partner workflows

Link changes, partners, financial/private output

10

Exact reviewed batches and pagination

Exact approval, partial receipts and native pages

11

Several private accounts

Private workspace selection without fallback

12

Writing safely

Shared confirmation/read-only/audit rules

13

How the two surfaces work

One catalogue, SDK bridge and pinned schema

14

Your data

Private provider payloads, credentials and files

15

Environment variables

Credentials, safety and request tuning

16

Updates and removal

npm/desktop updates and revocation

17

Troubleshooting

Concrete failure outcomes and next actions

18

API coverage and comparisons

Official MCP/CLI/SDK and pinned community

19

Versions and migration

Locked versions and legacy breaking changes

20

FAQ

Twenty provider-specific expanding answers

1. What you can ask it

  • Find the intended workspace's short links and inspect one exact link.

  • Review and create only the approved destination/slug, including native tags and folders.

  • Read eligible analytics/events using the precise date range and filters.

  • Review ordered link/tag/folder tasks, then submit only the matching approved batch.

  • Read partners/applications/commissions/payouts and approve only requested changes.

  • Write one requested QR PNG or temporary referral embed credential into a new private file.

Actual discovery exposes 61 tools: 22 reads/helpers and 39 confirmed operations. Fifty-seven current API operations and four local workflow helpers share one implementation. The old twelve-tool MCP had no declared task CLI; eleven names remain, and unsupported get_workspace is removed. list_accounts is local profile labels, not provider identity.

2. Quick install

npm install -g @thenavidm/dub-mcp-cli@latest
dub-cli --version
dub-cli tools
dub-cli schema create-link
dub-cli login

Node 22+ is required for manual CLI/local MCP. Discovery works without authentication. See INSTALL.md for every advertised client/OS and the versioned desktop bundle. The official dub-cli package installs a different binary, dub; our binary is dub-cli.

3. Set up Dub access

Private workspace access

  1. Sign into the intended Dub workspace. Open Settings → API Keys / tokens. Verify the workspace before copying a key.

  2. Create only the needed all-access, read-only or restricted link/analytics/domain/tag permissions. REST keys are workspace-specific; native read-only and workspace isolation already exist in Dub.

  3. Store the key outside repositories as DUB_API_KEY in private user settings or DUB_TOKEN_FILE pointing to an absolute token-only file. On macOS/Linux use a private 0700 directory and 0600 regular non-symlink file, at most 64 KiB. On Windows restrict ACLs to yourself; POSIX mode checks do not verify ACLs.

  4. Run dub-cli doctor for local settings. Deliberately run doctor --network for one GET /links?pageSize=1; it reports the returned count without echoing the link. This proves that read, not workspace ownership or every permission.

  5. Discover actual link IDs and fields, review the requested change, and approve only that operation or matching reviewed batch. Do not delete links, register domains, track sales or change financial records just to test installation.

REST keys are sent only to https://api.dub.co as Authorization: Bearer. The official hosted MCP accepts OAuth or the documented Mcp-Dub-Token header; do not substitute that header for REST Bearer. Official dub CLI OAuth uses its own private session and scopes. This wrapper never imports those sessions, starts OAuth, loads .env, purchases access or saves a key through login. login prints private setup instructions only.

DUB_ACCOUNTS is a private array of unique {name,api_key,token_file} profiles. A token file overrides only that selected profile's key and caches until process restart. Profiles never fall back to DUB_API_KEY or another account when credentials are missing. Labels do not verify provider ownership. A tenantId filter is customer segmentation within a workspace, not another workspace's authentication.

Plans, quotas and provider effects

The AGPL wrapper is free. Dub subscription limits, partner-program eligibility, domain-registration charges, conversions and financial actions remain provider costs and permissions. Check current plans and API limits.

Documented standard per-key limits are Free 60/minute, Pro 600/minute, Business 1200/minute and Advanced 3000/minute; Enterprise is custom. Analytics/events additionally list Free unavailable, Pro two requests/second, Business four/second and Advanced eight/second. Successful installation does not unlock paid analytics. The default 1100 ms process-wide request-start spacing is conservative for one Free key; other processes/apps share its quota. It is not a guaranteed limiter for all plans or concurrent clients.

No request automatically retries, including 429, redirects, timeouts or 5xx. Respect Retry-After before deliberately repeating a read. Inspect actual provider state before repeating an unknown mutation. Requests are capped at 1 MiB and responses at 5 MiB. Each explicit list call reads one native page: links/customers/commissions support mutually exclusive startingAfter/endingBefore cursors; other families use their documented page/pageSize or limit. Deprecated page parameters remain marked, cannot be mixed with cursors, and require positive integers. There is no invented all_pages option or complete-backup claim.

Native bulk link creation/update/deletion already supports up to 100 items. Bulk create omits custom previews and webhook events, and HTTP 200 can mix successful links with per-link errors. The local reviewed batch is a separate ordered one-to-twenty link/tag/folder workflow, with all payloads checked and exact approval hash before first request. A bulk task can still affect up to 100 records; twenty tasks is not a twenty-record budget.

Domain deletion is irreversible and deletes its links. Partner ban cancels commissions and deletes links; financial changes and customer deletion need explicit user intent. create_commission can return HTTP 202 with a task receipt: acceptance is not completed financial work. Tracking events can affect analytics and commissions. No payout execution endpoint is invented.

Rotation and revocation

Revoke the intended key in the correct workspace, replace private settings/files and restart every process. Native key/user role changes apply at the provider; machine-user keys share their owner's permissions and deleting a machine user revokes its keys. Do not create a machine user merely to test this package. Revoke official OAuth integrations separately. Removing npm/client entries does not revoke keys, undo links/events/commissions, refund a registered domain or remove saved private output files.

4. Connect your client

INSTALL.md leads with Codex and covers Claude Code, Claude Desktop extension/manual stdio, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Cline, Docker and other local stdio clients on macOS/Windows/Linux. Launch npx -y @thenavidm/dub-mcp-cli@latest with private environment settings. GUI/remote processes have their own filesystem and environment; restart/reconnect after settings or versions change.

Remote-only clients use Dub's official hosted MCP. The documented local mcp-remote route is a proxy of that hosted product. Our package supplies local stdio, not a public HTTP relay. Install SKILL.md in your agent's supported skill location if using the CLI; npm does not register a skill automatically.

codex mcp add dub --env DUB_TOKEN_FILE=/absolute/private/dub.txt -- npx -y @thenavidm/dub-mcp-cli@latest

5. Check it works

dub-cli --version
dub-cli tools
dub-cli list-accounts --agent
dub-cli doctor
dub-cli doctor --network
dub-cli list-links --page-size 1 --account work --agent

Local doctor reports profile count/default/policy without loading credentials or claiming authentication. --network opts into exactly one read, with count only. Actual account role/ownership, analytics plan, every endpoint and writes remain separate checks. Never use a destructive or paid call as an install test.

6. Output, flags and exit codes

Provider JSON returns as objects/arrays through both surfaces. The CLI emits JSON on stderr for failures. QR PNGs and generated publicToken credentials go only into exclusive private output files; returned data contains saved-file metadata, not the bytes/key. HTTP 202 commissions return accepted:true/http_status:202/result, not a finished commission. Native bulk-create HTTP 200 can contain per-link errors: inspect every item; CLI exit 0 alone is not per-item success.

Flag

Contract

--agent

Compact JSON and no prompts; never confirms a write

--select a,b.c

Local response field selection; does not reduce provider calls/quota

--confirm

Only the requested mutation or output-file write

--account NAME

Exact private profile

--payload JSON

Complete native body; arrays repeat once per item or use payload_file

--payload-file PATH

Absolute regular non-symlink JSON file, at most 1 MiB

--tasks JSON

Repeat per ordered task object; never pass one whole JSON array

--review-sha256 SHA256

Hash from exact matching local batch review

--output-file PATH

New absolute exclusive private output file; no overwrite

Native body flag names retain the current schema's camelCase, such as --externalId; query/path flags use snake-derived --page-size/--link-id. For nullable fields, unions and top-level commission oneOf bodies prefer complete payload JSON or a private JSON file; help/schema are authoritative.

Exit

Meaning

0

Request/local operation worked; still inspect semantic result/per-link errors/accepted state

1

Unexpected error

2

Invalid input or refused write, an unknown command or a hidden write

3

Resource not found

4

Provider authentication/permission error

5

Other provider/network/API failure

7

Rate limit

10

Missing/broken private configuration

dub-cli list-links --help
dub-cli schema create-commission
dub-cli get-link --link-id YOUR_LINK_ID --account work --agent
dub-cli create-link --payload '{"url":"https://example.com/requested","key":"requested"}' --account work --confirm --agent

7. MCP or CLI and token cost

Surface

What the agent receives

Verified scope

Local MCP

Client-loaded schemas and requested results

Actual full/read-only discovery and shared policy fixtures

Task CLI

Discovered help/schema and selected command results

Actual house SDK bridge, same handlers/guard

Official MCP/CLI

Provider tools and OAuth workflows

Current docs, pinned CLI and controlled request fixture

Measured on 2026-10-05 against 2.0.1, the same day, with Claude Code 2.1.286 on Claude Opus 5.5 (one short prompt with and without the server connected, the difference read from the API's own usage figures) and Codex 0.159.3 on gpt-6.1-sol:

Cost

2.0.1

3.0.0

Claude Code, every tool loaded, every message

86,431

74,231

Claude Code's default, tool search, every message

1,076

1,078

SKILL.md, read once

4,354

4,417

Codex over the CLI, one task, median of five

129,621

110,559

Codex over MCP, the same task, median of five

78,146

78,400

The task was "find the command that creates a short link, and the flags it requires". Every tool loaded costs less because each write's body appeared twice, as its own fields and inside payload, and 3.0.0 writes each repeated part once under $defs. Over the CLI, three 2.0.1 runs ran schema without a command, and every extra step carries the whole conversation forward; every 3.0.0 run asked which and none failed. Over MCP, Codex printed a tool list 1,545 tokens shorter on 3.0.0 (35,747 against 37,292) and cut both to about 10,000; the input totals differ by the model's own reasoning before it printed the list, from 0 to 170 tokens a run. SKILL.md costs 63 more because it now says how approval works over MCP and lists every exit code.

Tool counts, schema characters, another client's results and --select are not an efficiency percentage, and no other offering was measured.

8. Every tool and argument

MCP tool

CLI command

Native route / mode

create_link

dub-cli create-link

POST /links; confirmation required

list_links

dub-cli list-links

GET /links; read/helper

get_links_count

dub-cli get-links-count

GET /links/count; read/helper

get_link

dub-cli get-link

GET /links/info; read/helper

update_link

dub-cli update-link

PATCH /links/{linkId}; confirmation required

delete_link

dub-cli delete-link

DELETE /links/{linkId}; confirmation required

bulk_create_links

dub-cli bulk-create-links

POST /links/bulk; confirmation required

bulk_update_links

dub-cli bulk-update-links

PATCH /links/bulk; confirmation required

bulk_delete_links

dub-cli bulk-delete-links

DELETE /links/bulk; confirmation required

upsert_link

dub-cli upsert-link

PUT /links/upsert; confirmation required

get_link_stats

dub-cli get-link-stats

GET /analytics; read/helper

list_events

dub-cli list-events

GET /events; read/helper

create_tag

dub-cli create-tag

POST /tags; confirmation required

list_tags

dub-cli list-tags

GET /tags; read/helper

update_tag

dub-cli update-tag

PATCH /tags/{id}; confirmation required

delete_tag

dub-cli delete-tag

DELETE /tags/{id}; confirmation required

create_folder

dub-cli create-folder

POST /folders; confirmation required

list_folders

dub-cli list-folders

GET /folders; read/helper

update_folder

dub-cli update-folder

PATCH /folders/{id}; confirmation required

delete_folder

dub-cli delete-folder

DELETE /folders/{id}; confirmation required

create_domain

dub-cli create-domain

POST /domains; confirmation required

list_domains

dub-cli list-domains

GET /domains; read/helper

update_domain

dub-cli update-domain

PATCH /domains/{slug}; confirmation required

delete_domain

dub-cli delete-domain

DELETE /domains/{slug}; confirmation required

register_domain

dub-cli register-domain

POST /domains/register; confirmation required

check_domain_status

dub-cli check-domain-status

GET /domains/status; read/helper

track_lead

dub-cli track-lead

POST /track/lead; confirmation required

track_sale

dub-cli track-sale

POST /track/sale; confirmation required

track_open

dub-cli track-open

POST /track/open; confirmation required

list_customers

dub-cli list-customers

GET /customers; read/helper

get_customer

dub-cli get-customer

GET /customers/{id}; read/helper

update_customer

dub-cli update-customer

PATCH /customers/{id}; confirmation required

delete_customer

dub-cli delete-customer

DELETE /customers/{id}; confirmation required

create_partner

dub-cli create-partner

POST /partners; confirmation required

list_partners

dub-cli list-partners

GET /partners; read/helper

create_partner_link

dub-cli create-partner-link

POST /partners/links; confirmation required

retrieve_partner_links

dub-cli retrieve-partner-links

GET /partners/links; read/helper

upsert_partner_link

dub-cli upsert-partner-link

PUT /partners/links/upsert; confirmation required

retrieve_partner_analytics

dub-cli retrieve-partner-analytics

GET /partners/analytics; read/helper

ban_partner

dub-cli ban-partner

POST /partners/ban; confirmation required

deactivate_partner

dub-cli deactivate-partner

POST /partners/deactivate; confirmation required

list_program_applications

dub-cli list-program-applications

GET /program-applications; read/helper

approve_program_application

dub-cli approve-program-application

POST /program-applications/approve; confirmation required

reject_program_application

dub-cli reject-program-application

POST /program-applications/reject; confirmation required

list_discount_codes

dub-cli list-discount-codes

GET /discount-codes; read/helper

create_discount_code

dub-cli create-discount-code

POST /discount-codes; confirmation required

delete_discount_code

dub-cli delete-discount-code

DELETE /discount-codes/{idOrCode}; confirmation required

create_commission

dub-cli create-commission

POST /commissions; confirmation required

list_commissions

dub-cli list-commissions

GET /commissions; read/helper

update_commission

dub-cli update-commission

PATCH /commissions/{id}; confirmation required

bulk_update_commissions

dub-cli bulk-update-commissions

PATCH /commissions/bulk; confirmation required

list_payouts

dub-cli list-payouts

GET /payouts; read/helper

create_referrals_embed_token

dub-cli create-referrals-embed-token

POST /tokens/embed/referrals; confirmation required

get_qr_code

dub-cli get-qr-code

GET /qr; confirmation required

list_bounty_submissions

dub-cli list-bounty-submissions

GET /bounties/{bountyId}/submissions; read/helper

approve_bounty_submission

dub-cli approve-bounty-submission

POST /bounties/{bountyId}/submissions/{submissionId}/approve; confirmation required

reject_bounty_submission

dub-cli reject-bounty-submission

POST /bounties/{bountyId}/submissions/{submissionId}/reject; confirmation required

list_accounts

dub-cli list-accounts

Local workflow; read/helper

get_operation_schema

dub-cli get-operation-schema

Local workflow; read/helper

preview_link_batch

dub-cli preview-link-batch

Local workflow; read/helper

submit_link_batch

dub-cli submit-link-batch

Local workflow; confirmation required

dub-cli create-link

Create a link for the authenticated workspace.

Argument

Required

Type

Details

url

No; body/guard requirements still apply

string

The destination URL of the short link. maxLength: 32000.

domain

No; body/guard requirements still apply

string

The domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains). maxLength: 190.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

keyLength

No; body/guard requirements still apply

number

The length of the short link slug. Defaults to 7 if not provided. When used with prefix, the total length of the key will be prefix.length + keyLength. minimum: 3. maximum: 190.

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

programId

No; body/guard requirements still apply

['string', 'null']

The ID of the program the short link is associated with.

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner the short link is associated with.

prefix

No; body/guard requirements still apply

string

The prefix of the short link slug for randomly-generated keys (e.g. if prefix is /c/, generated keys will be in the /c/:key format). Will be ignored if key is provided.

trackConversion

No; body/guard requirements still apply

boolean

Whether to track conversions for the short link. Defaults to false if not provided.

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

['string', 'null']

The unique ID existing folder to assign the short link to.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

geo

No; body/guard requirements still apply

['object', 'null']

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

No; body/guard requirements still apply

['string', 'null']

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL. maxLength: 255.

utm_medium

No; body/guard requirements still apply

['string', 'null']

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL. maxLength: 255.

utm_campaign

No; body/guard requirements still apply

['string', 'null']

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL. maxLength: 255.

utm_term

No; body/guard requirements still apply

['string', 'null']

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL. maxLength: 255.

utm_content

No; body/guard requirements still apply

['string', 'null']

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL. maxLength: 255.

ref

No; body/guard requirements still apply

['string', 'null']

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL. maxLength: 255.

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

publicStats

No; body/guard requirements still apply

boolean

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided. Deprecated native compatibility field.

tagId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link. Deprecated native compatibility field.

webhookIds

No; body/guard requirements still apply

['array', 'null']

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data. Deprecated native compatibility field.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.tagIds

input.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagIds anyOf branch 2

input.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.tagNames

input.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagNames anyOf branch 2

input.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.testVariants

input.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.webhookIds

input.webhookIds[]

Native JSON value; inspect the full schema for validation.

input.payload

Argument

Required

Type

Details

url

Yes

string

The destination URL of the short link. maxLength: 32000.

domain

No; body/guard requirements still apply

string

The domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains). maxLength: 190.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

keyLength

No; body/guard requirements still apply

number

The length of the short link slug. Defaults to 7 if not provided. When used with prefix, the total length of the key will be prefix.length + keyLength. minimum: 3. maximum: 190.

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

programId

No; body/guard requirements still apply

['string', 'null']

The ID of the program the short link is associated with.

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner the short link is associated with.

prefix

No; body/guard requirements still apply

string

The prefix of the short link slug for randomly-generated keys (e.g. if prefix is /c/, generated keys will be in the /c/:key format). Will be ignored if key is provided.

trackConversion

No; body/guard requirements still apply

boolean

Whether to track conversions for the short link. Defaults to false if not provided.

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

['string', 'null']

The unique ID existing folder to assign the short link to.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

geo

No; body/guard requirements still apply

['object', 'null']

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

No; body/guard requirements still apply

['string', 'null']

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL. maxLength: 255.

utm_medium

No; body/guard requirements still apply

['string', 'null']

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL. maxLength: 255.

utm_campaign

No; body/guard requirements still apply

['string', 'null']

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL. maxLength: 255.

utm_term

No; body/guard requirements still apply

['string', 'null']

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL. maxLength: 255.

utm_content

No; body/guard requirements still apply

['string', 'null']

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL. maxLength: 255.

ref

No; body/guard requirements still apply

['string', 'null']

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL. maxLength: 255.

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

publicStats

No; body/guard requirements still apply

boolean

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided. Deprecated native compatibility field.

tagId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link. Deprecated native compatibility field.

webhookIds

No; body/guard requirements still apply

['array', 'null']

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data. Deprecated native compatibility field.

input.payload.tagIds

input.payload.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.tagIds anyOf branch 2

input.payload.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.tagNames

input.payload.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.tagNames anyOf branch 2

input.payload.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.testVariants

input.payload.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.payload.webhookIds

input.payload.webhookIds[]

Native JSON value; inspect the full schema for validation.

dub-cli list-links

Retrieve a paginated list of links for the authenticated workspace.

Argument

Required

Type

Details

domain

No; body/guard requirements still apply

string

The domain to filter the links by. E.g. ac.me. If not provided, all links for the workspace will be returned.

tag_id

No; body/guard requirements still apply

string

Deprecated: Use tagIds instead. The tag ID to filter the links by. Deprecated native compatibility field.

tag_ids

No; body/guard requirements still apply

JSON

The tag IDs to filter the links by.

tag_names

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folder_id

No; body/guard requirements still apply

string

The folder ID to filter the links by.

search

No; body/guard requirements still apply

string

The search term to filter the links by. The search term will be matched against the short link slug and the destination url.

user_id

No; body/guard requirements still apply

string

The user ID to filter the links by.

tenant_id

No; body/guard requirements still apply

string

The ID of the tenant that created the link inside your system. If set, will only return links for the specified tenant.

show_archived

No; body/guard requirements still apply

boolean

Whether to include archived links in the response. Defaults to false if not provided. default: false.

with_tags

No; body/guard requirements still apply

boolean

DEPRECATED. Filter for links that have at least one tag assigned to them. default: false. Deprecated native compatibility field.

ending_before

No; body/guard requirements still apply

string

If specified, the query only searches for results before this cursor. Mutually exclusive with startingAfter.

starting_after

No; body/guard requirements still apply

string

If specified, the query only searches for results after this cursor. Mutually exclusive with endingBefore.

page

No; body/guard requirements still apply

integer

DEPRECATED. Use startingAfter instead. maximum: 9007199254740991. exclusiveMinimum: 0. Deprecated native compatibility field.

page_size

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

input.tag_ids

input.tag_ids anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tag_ids anyOf branch 2

input.tag_ids.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.tag_names

input.tag_names anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tag_names anyOf branch 2

input.tag_names.anyOf2[]

Native JSON value; inspect the full schema for validation.

dub-cli get-links-count

Retrieve the number of links for the authenticated workspace.

Argument

Required

Type

Details

domain

No; body/guard requirements still apply

string

The domain to filter the links by. E.g. ac.me. If not provided, all links for the workspace will be returned.

tag_id

No; body/guard requirements still apply

string

Deprecated: Use tagIds instead. The tag ID to filter the links by. Deprecated native compatibility field.

tag_ids

No; body/guard requirements still apply

JSON

The tag IDs to filter the links by.

tag_names

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folder_id

No; body/guard requirements still apply

string

The folder ID to filter the links by.

search

No; body/guard requirements still apply

string

The search term to filter the links by. The search term will be matched against the short link slug and the destination url.

user_id

No; body/guard requirements still apply

string

The user ID to filter the links by.

tenant_id

No; body/guard requirements still apply

string

The ID of the tenant that created the link inside your system. If set, will only return links for the specified tenant.

show_archived

No; body/guard requirements still apply

boolean

Whether to include archived links in the response. Defaults to false if not provided. default: false.

with_tags

No; body/guard requirements still apply

boolean

DEPRECATED. Filter for links that have at least one tag assigned to them. default: false. Deprecated native compatibility field.

group_by

No; body/guard requirements still apply

JSON

The field to group the links by.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

input.tag_ids

input.tag_ids anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tag_ids anyOf branch 2

input.tag_ids.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.tag_names

input.tag_names anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tag_names anyOf branch 2

input.tag_names.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.group_by

input.group_by anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.group_by anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.group_by anyOf branch 3

Native JSON value; inspect the full schema for validation.

input.group_by anyOf branch 4

Native JSON value; inspect the full schema for validation.

dub-cli get-link

Retrieve the info for a link.

Argument

Required

Type

Details

domain

No; body/guard requirements still apply

string

The domain of the link to retrieve. E.g. for d.to/github, the domain is d.to. minLength: 1.

key

No; body/guard requirements still apply

string

The key of the link to retrieve. E.g. for d.to/github, the key is github. minLength: 1.

link_id

No; body/guard requirements still apply

string

The unique ID of the short link.

external_id

No; body/guard requirements still apply

string

This is the ID of the link in the your database.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

dub-cli update-link

Update a link for the authenticated workspace. If there's no change, returns it as it is.

Argument

Required

Type

Details

link_id

Yes

string

The id of the link to update. You may use either linkId (obtained via /links/info endpoint) or externalId prefixed with ext_.

url

No; body/guard requirements still apply

string

The destination URL of the short link. maxLength: 32000.

domain

No; body/guard requirements still apply

string

The domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains). maxLength: 190.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

programId

No; body/guard requirements still apply

['string', 'null']

The ID of the program the short link is associated with.

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner the short link is associated with.

trackConversion

No; body/guard requirements still apply

boolean

Whether to track conversions for the short link. Defaults to false if not provided.

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

['string', 'null']

The unique ID existing folder to assign the short link to.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

JSON

Native field; use the reviewed provider reference.

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

geo

No; body/guard requirements still apply

JSON

Native field; use the reviewed provider reference.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

No; body/guard requirements still apply

['string', 'null']

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL. maxLength: 255.

utm_medium

No; body/guard requirements still apply

['string', 'null']

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL. maxLength: 255.

utm_campaign

No; body/guard requirements still apply

['string', 'null']

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL. maxLength: 255.

utm_term

No; body/guard requirements still apply

['string', 'null']

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL. maxLength: 255.

utm_content

No; body/guard requirements still apply

['string', 'null']

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL. maxLength: 255.

ref

No; body/guard requirements still apply

['string', 'null']

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL. maxLength: 255.

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

publicStats

No; body/guard requirements still apply

boolean

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided. Deprecated native compatibility field.

tagId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link. Deprecated native compatibility field.

webhookIds

No; body/guard requirements still apply

['array', 'null']

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data. Deprecated native compatibility field.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.tagIds

input.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagIds anyOf branch 2

input.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.tagNames

input.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagNames anyOf branch 2

input.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.image

input.image anyOf branch 1

input.image.anyOf1 anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.image.anyOf1 anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.image anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.geo

input.geo allOf branch 1

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

input.testVariants

input.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.webhookIds

input.webhookIds[]

Native JSON value; inspect the full schema for validation.

input.payload

Argument

Required

Type

Details

url

No; body/guard requirements still apply

string

The destination URL of the short link. maxLength: 32000.

domain

No; body/guard requirements still apply

string

The domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains). maxLength: 190.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

programId

No; body/guard requirements still apply

['string', 'null']

The ID of the program the short link is associated with.

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner the short link is associated with.

trackConversion

No; body/guard requirements still apply

boolean

Whether to track conversions for the short link. Defaults to false if not provided.

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

['string', 'null']

The unique ID existing folder to assign the short link to.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

JSON

Native field; use the reviewed provider reference.

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

geo

No; body/guard requirements still apply

JSON

Native field; use the reviewed provider reference.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

No; body/guard requirements still apply

['string', 'null']

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL. maxLength: 255.

utm_medium

No; body/guard requirements still apply

['string', 'null']

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL. maxLength: 255.

utm_campaign

No; body/guard requirements still apply

['string', 'null']

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL. maxLength: 255.

utm_term

No; body/guard requirements still apply

['string', 'null']

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL. maxLength: 255.

utm_content

No; body/guard requirements still apply

['string', 'null']

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL. maxLength: 255.

ref

No; body/guard requirements still apply

['string', 'null']

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL. maxLength: 255.

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

publicStats

No; body/guard requirements still apply

boolean

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided. Deprecated native compatibility field.

tagId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link. Deprecated native compatibility field.

webhookIds

No; body/guard requirements still apply

['array', 'null']

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data. Deprecated native compatibility field.

input.payload.tagIds

input.payload.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.tagIds anyOf branch 2

input.payload.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.tagNames

input.payload.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.tagNames anyOf branch 2

input.payload.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.image

input.payload.image anyOf branch 1

input.payload.image.anyOf1 anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.image.anyOf1 anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.payload.image anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.payload.geo

input.payload.geo allOf branch 1

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

input.payload.testVariants

input.payload.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.payload.webhookIds

input.payload.webhookIds[]

Native JSON value; inspect the full schema for validation.

dub-cli delete-link

Delete a link for the authenticated workspace.

Argument

Required

Type

Details

link_id

Yes

string

The id of the link to delete. You may use either linkId (obtained via /links/info endpoint) or externalId prefixed with ext_.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

dub-cli bulk-create-links

Bulk create up to 100 links for the authenticated workspace.

Argument

Required

Type

Details

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

array

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

input.payload[]

Argument

Required

Type

Details

url

Yes

string

The destination URL of the short link. maxLength: 32000.

domain

No; body/guard requirements still apply

string

The domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains). maxLength: 190.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

keyLength

No; body/guard requirements still apply

number

The length of the short link slug. Defaults to 7 if not provided. When used with prefix, the total length of the key will be prefix.length + keyLength. minimum: 3. maximum: 190.

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

programId

No; body/guard requirements still apply

['string', 'null']

The ID of the program the short link is associated with.

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner the short link is associated with.

prefix

No; body/guard requirements still apply

string

The prefix of the short link slug for randomly-generated keys (e.g. if prefix is /c/, generated keys will be in the /c/:key format). Will be ignored if key is provided.

trackConversion

No; body/guard requirements still apply

boolean

Whether to track conversions for the short link. Defaults to false if not provided.

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

['string', 'null']

The unique ID existing folder to assign the short link to.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

geo

No; body/guard requirements still apply

['object', 'null']

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

No; body/guard requirements still apply

['string', 'null']

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL. maxLength: 255.

utm_medium

No; body/guard requirements still apply

['string', 'null']

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL. maxLength: 255.

utm_campaign

No; body/guard requirements still apply

['string', 'null']

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL. maxLength: 255.

utm_term

No; body/guard requirements still apply

['string', 'null']

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL. maxLength: 255.

utm_content

No; body/guard requirements still apply

['string', 'null']

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL. maxLength: 255.

ref

No; body/guard requirements still apply

['string', 'null']

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL. maxLength: 255.

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

publicStats

No; body/guard requirements still apply

boolean

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided. Deprecated native compatibility field.

tagId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link. Deprecated native compatibility field.

webhookIds

No; body/guard requirements still apply

['array', 'null']

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data. Deprecated native compatibility field.

input.payload[].tagIds

input.payload[].tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload[].tagIds anyOf branch 2

input.payload[].tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload[].tagNames

input.payload[].tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload[].tagNames anyOf branch 2

input.payload[].tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload[].testVariants

input.payload[].testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.payload[].webhookIds

input.payload[].webhookIds[]

Native JSON value; inspect the full schema for validation.

dub-cli bulk-update-links

Bulk update up to 100 links with the same data for the authenticated workspace.

Argument

Required

Type

Details

linkIds

No; body/guard requirements still apply

array

The IDs of the links to update. Takes precedence over externalIds. maxItems: 100. default: [].

externalIds

No; body/guard requirements still apply

array

The external IDs of the links to update as stored in your database. maxItems: 100. default: [].

data

No; body/guard requirements still apply

object

Native field; use the reviewed provider reference.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.linkIds

input.linkIds[]

Native JSON value; inspect the full schema for validation.

input.externalIds

input.externalIds[]

Native JSON value; inspect the full schema for validation.

input.data

Argument

Required

Type

Details

url

No; body/guard requirements still apply

string

The destination URL of the short link. maxLength: 32000.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

programId

No; body/guard requirements still apply

['string', 'null']

The ID of the program the short link is associated with.

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner the short link is associated with.

trackConversion

No; body/guard requirements still apply

boolean

Whether to track conversions for the short link. Defaults to false if not provided.

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

['string', 'null']

The unique ID existing folder to assign the short link to.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

geo

No; body/guard requirements still apply

['object', 'null']

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

No; body/guard requirements still apply

['string', 'null']

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL. maxLength: 255.

utm_medium

No; body/guard requirements still apply

['string', 'null']

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL. maxLength: 255.

utm_campaign

No; body/guard requirements still apply

['string', 'null']

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL. maxLength: 255.

utm_term

No; body/guard requirements still apply

['string', 'null']

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL. maxLength: 255.

utm_content

No; body/guard requirements still apply

['string', 'null']

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL. maxLength: 255.

ref

No; body/guard requirements still apply

['string', 'null']

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL. maxLength: 255.

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

publicStats

No; body/guard requirements still apply

boolean

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided. Deprecated native compatibility field.

tagId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link. Deprecated native compatibility field.

webhookIds

No; body/guard requirements still apply

['array', 'null']

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data. Deprecated native compatibility field.

input.data.tagIds

input.data.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.data.tagIds anyOf branch 2

input.data.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.data.tagNames

input.data.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.data.tagNames anyOf branch 2

input.data.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.data.testVariants

input.data.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.data.webhookIds

input.data.webhookIds[]

Native JSON value; inspect the full schema for validation.

input.payload

Argument

Required

Type

Details

linkIds

No; body/guard requirements still apply

array

The IDs of the links to update. Takes precedence over externalIds. maxItems: 100. default: [].

externalIds

No; body/guard requirements still apply

array

The external IDs of the links to update as stored in your database. maxItems: 100. default: [].

data

Yes

object

Native field; use the reviewed provider reference.

input.payload.linkIds

input.payload.linkIds[]

Native JSON value; inspect the full schema for validation.

input.payload.externalIds

input.payload.externalIds[]

Native JSON value; inspect the full schema for validation.

input.payload.data

Argument

Required

Type

Details

url

No; body/guard requirements still apply

string

The destination URL of the short link. maxLength: 32000.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

programId

No; body/guard requirements still apply

['string', 'null']

The ID of the program the short link is associated with.

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner the short link is associated with.

trackConversion

No; body/guard requirements still apply

boolean

Whether to track conversions for the short link. Defaults to false if not provided.

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

['string', 'null']

The unique ID existing folder to assign the short link to.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

geo

No; body/guard requirements still apply

['object', 'null']

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

No; body/guard requirements still apply

['string', 'null']

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL. maxLength: 255.

utm_medium

No; body/guard requirements still apply

['string', 'null']

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL. maxLength: 255.

utm_campaign

No; body/guard requirements still apply

['string', 'null']

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL. maxLength: 255.

utm_term

No; body/guard requirements still apply

['string', 'null']

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL. maxLength: 255.

utm_content

No; body/guard requirements still apply

['string', 'null']

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL. maxLength: 255.

ref

No; body/guard requirements still apply

['string', 'null']

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL. maxLength: 255.

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

publicStats

No; body/guard requirements still apply

boolean

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided. Deprecated native compatibility field.

tagId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link. Deprecated native compatibility field.

webhookIds

No; body/guard requirements still apply

['array', 'null']

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data. Deprecated native compatibility field.

input.payload.data.tagIds

input.payload.data.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.data.tagIds anyOf branch 2

input.payload.data.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.data.tagNames

input.payload.data.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.data.tagNames anyOf branch 2

input.payload.data.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.data.testVariants

input.payload.data.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.payload.data.webhookIds

input.payload.data.webhookIds[]

Native JSON value; inspect the full schema for validation.

dub-cli bulk-delete-links

Bulk delete up to 100 links for the authenticated workspace.

Argument

Required

Type

Details

link_ids

Yes

array

Comma-separated list of link IDs to delete. Maximum of 100 IDs. Non-existing IDs will be ignored.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

input.link_ids

input.link_ids[]

Native JSON value; inspect the full schema for validation.

dub-cli upsert-link

Upsert a link for the authenticated workspace by its URL. If a link with the same URL already exists, return it (or update it if there are any changes). Otherwise, a new link will be created.

Argument

Required

Type

Details

url

No; body/guard requirements still apply

string

The destination URL of the short link. maxLength: 32000.

domain

No; body/guard requirements still apply

string

The domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains). maxLength: 190.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

keyLength

No; body/guard requirements still apply

number

The length of the short link slug. Defaults to 7 if not provided. When used with prefix, the total length of the key will be prefix.length + keyLength. minimum: 3. maximum: 190.

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

programId

No; body/guard requirements still apply

['string', 'null']

The ID of the program the short link is associated with.

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner the short link is associated with.

prefix

No; body/guard requirements still apply

string

The prefix of the short link slug for randomly-generated keys (e.g. if prefix is /c/, generated keys will be in the /c/:key format). Will be ignored if key is provided.

trackConversion

No; body/guard requirements still apply

boolean

Whether to track conversions for the short link. Defaults to false if not provided.

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

['string', 'null']

The unique ID existing folder to assign the short link to.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

geo

No; body/guard requirements still apply

['object', 'null']

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

No; body/guard requirements still apply

['string', 'null']

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL. maxLength: 255.

utm_medium

No; body/guard requirements still apply

['string', 'null']

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL. maxLength: 255.

utm_campaign

No; body/guard requirements still apply

['string', 'null']

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL. maxLength: 255.

utm_term

No; body/guard requirements still apply

['string', 'null']

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL. maxLength: 255.

utm_content

No; body/guard requirements still apply

['string', 'null']

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL. maxLength: 255.

ref

No; body/guard requirements still apply

['string', 'null']

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL. maxLength: 255.

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

publicStats

No; body/guard requirements still apply

boolean

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided. Deprecated native compatibility field.

tagId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link. Deprecated native compatibility field.

webhookIds

No; body/guard requirements still apply

['array', 'null']

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data. Deprecated native compatibility field.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.tagIds

input.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagIds anyOf branch 2

input.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.tagNames

input.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagNames anyOf branch 2

input.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.testVariants

input.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.webhookIds

input.webhookIds[]

Native JSON value; inspect the full schema for validation.

input.payload

Argument

Required

Type

Details

url

Yes

string

The destination URL of the short link. maxLength: 32000.

domain

No; body/guard requirements still apply

string

The domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains). maxLength: 190.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

keyLength

No; body/guard requirements still apply

number

The length of the short link slug. Defaults to 7 if not provided. When used with prefix, the total length of the key will be prefix.length + keyLength. minimum: 3. maximum: 190.

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

programId

No; body/guard requirements still apply

['string', 'null']

The ID of the program the short link is associated with.

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner the short link is associated with.

prefix

No; body/guard requirements still apply

string

The prefix of the short link slug for randomly-generated keys (e.g. if prefix is /c/, generated keys will be in the /c/:key format). Will be ignored if key is provided.

trackConversion

No; body/guard requirements still apply

boolean

Whether to track conversions for the short link. Defaults to false if not provided.

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

['string', 'null']

The unique ID existing folder to assign the short link to.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

geo

No; body/guard requirements still apply

['object', 'null']

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

No; body/guard requirements still apply

['string', 'null']

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL. maxLength: 255.

utm_medium

No; body/guard requirements still apply

['string', 'null']

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL. maxLength: 255.

utm_campaign

No; body/guard requirements still apply

['string', 'null']

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL. maxLength: 255.

utm_term

No; body/guard requirements still apply

['string', 'null']

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL. maxLength: 255.

utm_content

No; body/guard requirements still apply

['string', 'null']

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL. maxLength: 255.

ref

No; body/guard requirements still apply

['string', 'null']

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL. maxLength: 255.

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

publicStats

No; body/guard requirements still apply

boolean

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided. Deprecated native compatibility field.

tagId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link. Deprecated native compatibility field.

webhookIds

No; body/guard requirements still apply

['array', 'null']

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data. Deprecated native compatibility field.

input.payload.tagIds

input.payload.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.tagIds anyOf branch 2

input.payload.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.tagNames

input.payload.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.tagNames anyOf branch 2

input.payload.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.testVariants

input.payload.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.payload.webhookIds

input.payload.webhookIds[]

Native JSON value; inspect the full schema for validation.

dub-cli get-link-stats

Retrieve analytics for a link, a domain, or the authenticated workspace. The response type depends on the event and type query parameters.

Argument

Required

Type

Details

event

No; body/guard requirements still apply

string

The type of event to retrieve analytics for. Defaults to clicks. enum: ["clicks", "leads", "sales", "composite"]. default: "clicks".

group_by

No; body/guard requirements still apply

string

The parameter to group the analytics data points by. Defaults to count if undefined. enum: ["count", "timeseries", "continents", "regions", "countries", "cities", "devices", "browsers", "os", "trigger", "triggers", "event_names", "referers", "referer_urls", "top_folders", "top_link_tags", "top_domains", "top_links", "top_urls", "top_base_urls", "top_partners", "top_groups", "top_partner_tags", "utm_sources", "utm_mediums", "utm_campaigns", "utm_terms", "utm_contents"]. default: "count".

domain

No; body/guard requirements still apply

string

The domain to filter analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: dub.co, dub.co,google.com, -spam.com.

key

No; body/guard requirements still apply

string

The slug of the short link to retrieve analytics for. Must be used along with the corresponding domain of the short link to fetch analytics for a specific short link.

link_id

No; body/guard requirements still apply

string

The unique ID of the link to retrieve analytics for.Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: link_123, link_123,link_456, -link_789.

external_id

No; body/guard requirements still apply

string

The ID of the link in the your database. Must be prefixed with 'ext_' when passed as a query parameter.

tenant_id

No; body/guard requirements still apply

string

The ID of the tenant that created the link inside your system. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: tenant_123, tenant_123,tenant_456, -tenant_789.

tag_id

No; body/guard requirements still apply

string

The tag ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: tag_123, tag_123,tag_456, -tag_789.

folder_id

No; body/guard requirements still apply

string

The folder ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: folder_123, folder_123,folder_456, -folder_789. If not provided, return analytics for all links.

partner_tag_id

No; body/guard requirements still apply

string

The partner tag ID(s) to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: ptag_123, ptag_123,ptag_456, -ptag_789.

group_id

No; body/guard requirements still apply

string

The group ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: grp_123, grp_123,grp_456, -grp_789.

partner_id

No; body/guard requirements still apply

string

The ID of the partner to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: pn_123, pn_123,pn_456, -pn_789.

customer_id

No; body/guard requirements still apply

string

The ID of the customer to retrieve analytics for.

interval

No; body/guard requirements still apply

string

The interval to retrieve analytics for. If undefined, defaults to 24h. enum: ["24h", "7d", "30d", "90d", "1y", "mtd", "qtd", "ytd", "all"].

start

No; body/guard requirements still apply

string

The start date and time when to retrieve analytics from. If set, takes precedence over interval.

end

No; body/guard requirements still apply

string

The end date and time when to retrieve analytics from. If not provided, defaults to the current date. If set along with start, takes precedence over interval.

timezone

No; body/guard requirements still apply

string

The IANA time zone code for aligning timeseries granularity (e.g. America/New_York). Defaults to UTC. default: "UTC".

country

No; body/guard requirements still apply

string

The country to retrieve analytics for. Must be passed as a 2-letter ISO 3166-1 country code (see https://d.to/geo). Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: US, US,BR,FR, -US.

city

No; body/guard requirements still apply

string

The city to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: New York, New York,London, -New York.

region

No; body/guard requirements still apply

string

The ISO 3166-2 region code to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: NY, NY,CA, -NY.

continent

No; body/guard requirements still apply

string

The continent to retrieve analytics for. Valid values: AF, AN, AS, EU, NA, OC, SA. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: NA, NA,EU, -AS.

device

No; body/guard requirements still apply

string

The device to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Desktop, Mobile,Tablet, -Mobile.

browser

No; body/guard requirements still apply

string

The browser to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Chrome, Chrome,Firefox,Safari, -IE.

os

No; body/guard requirements still apply

string

The OS to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Windows, Mac,Windows,Linux, -Windows.

trigger

No; body/guard requirements still apply

string

The trigger to retrieve analytics for. Valid values: qr, link, pageview. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: qr, qr,link, -qr. If undefined, returns all trigger types.

event_name

No; body/guard requirements still apply

string

The conversion event name to retrieve analytics for. Only available for lead and sale events. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Sign up, Sign up,Purchase, -Sign up.

referer

No; body/guard requirements still apply

string

The referer hostname to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: google.com, google.com,twitter.com, -facebook.com.

referer_url

No; body/guard requirements still apply

string

The full referer URL to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: https://google.com, https://google.com,https://twitter.com, -https://spam.com.

url

No; body/guard requirements still apply

string

The destination URL to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: https://example.com, https://example.com,https://other.com, -https://spam.com.

utm_source

No; body/guard requirements still apply

string

The UTM source to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: google, google,twitter, -spam.

utm_medium

No; body/guard requirements still apply

string

The UTM medium to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: cpc, cpc,social, -email.

utm_campaign

No; body/guard requirements still apply

string

The UTM campaign to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: summer_sale, summer_sale,winter_sale, -old_campaign.

utm_term

No; body/guard requirements still apply

string

The UTM term to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

utm_content

No; body/guard requirements still apply

string

The UTM content to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

root

No; body/guard requirements still apply

boolean

Filter for root domains. If true, filter for domains only. If false, filter for links only. If undefined, return both.

sale_type

No; body/guard requirements still apply

string

Filter sales by type: 'new' for first-time purchases, 'recurring' for repeat purchases. If undefined, returns both. enum: ["new", "recurring"].

query

No; body/guard requirements still apply

string

Search the events by a custom metadata value. Only available for lead and sale events. Examples: metadata['key']:'value' maxLength: 10000.

program_id

No; body/guard requirements still apply

string

Deprecated: This is automatically inferred from your workspace's defaultProgramId. The ID of the program to retrieve analytics for. Deprecated native compatibility field.

tag_ids

No; body/guard requirements still apply

string

Deprecated: Use tagId instead. The tag IDs to retrieve analytics for. Deprecated native compatibility field.

qr

No; body/guard requirements still apply

boolean

Deprecated: Use the trigger field instead. Filter for QR code scans. If true, filter for QR codes only. If false, filter for links only. If undefined, return both. Deprecated native compatibility field.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

list_events

dub-cli list-events

Retrieve a paginated list of events for the authenticated workspace.

Argument

Required

Type

Details

event

No; body/guard requirements still apply

string

The type of event to retrieve analytics for. Defaults to 'clicks'. enum: ["clicks", "leads", "sales"]. default: "clicks".

domain

No; body/guard requirements still apply

string

The domain to filter analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: dub.co, dub.co,google.com, -spam.com.

key

No; body/guard requirements still apply

string

The slug of the short link to retrieve analytics for. Must be used along with the corresponding domain of the short link to fetch analytics for a specific short link.

link_id

No; body/guard requirements still apply

string

The unique ID of the link to retrieve analytics for.Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: link_123, link_123,link_456, -link_789.

external_id

No; body/guard requirements still apply

string

The ID of the link in the your database. Must be prefixed with 'ext_' when passed as a query parameter.

tenant_id

No; body/guard requirements still apply

string

The ID of the tenant that created the link inside your system. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: tenant_123, tenant_123,tenant_456, -tenant_789.

tag_id

No; body/guard requirements still apply

string

The tag ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: tag_123, tag_123,tag_456, -tag_789.

folder_id

No; body/guard requirements still apply

string

The folder ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: folder_123, folder_123,folder_456, -folder_789. If not provided, return analytics for all links.

partner_tag_id

No; body/guard requirements still apply

string

The partner tag ID(s) to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: ptag_123, ptag_123,ptag_456, -ptag_789.

group_id

No; body/guard requirements still apply

string

The group ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: grp_123, grp_123,grp_456, -grp_789.

partner_id

No; body/guard requirements still apply

string

The ID of the partner to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: pn_123, pn_123,pn_456, -pn_789.

customer_id

No; body/guard requirements still apply

string

The ID of the customer to retrieve analytics for.

interval

No; body/guard requirements still apply

string

The interval to retrieve analytics for. If undefined, defaults to 24h. enum: ["24h", "7d", "30d", "90d", "1y", "mtd", "qtd", "ytd", "all"].

start

No; body/guard requirements still apply

string

The start date and time when to retrieve analytics from. If set, takes precedence over interval.

end

No; body/guard requirements still apply

string

The end date and time when to retrieve analytics from. If not provided, defaults to the current date. If set along with start, takes precedence over interval.

timezone

No; body/guard requirements still apply

string

The IANA time zone code for aligning timeseries granularity (e.g. America/New_York). Defaults to UTC. default: "UTC".

country

No; body/guard requirements still apply

string

The country to retrieve analytics for. Must be passed as a 2-letter ISO 3166-1 country code (see https://d.to/geo). Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: US, US,BR,FR, -US.

city

No; body/guard requirements still apply

string

The city to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: New York, New York,London, -New York.

region

No; body/guard requirements still apply

string

The ISO 3166-2 region code to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: NY, NY,CA, -NY.

continent

No; body/guard requirements still apply

string

The continent to retrieve analytics for. Valid values: AF, AN, AS, EU, NA, OC, SA. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: NA, NA,EU, -AS.

device

No; body/guard requirements still apply

string

The device to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Desktop, Mobile,Tablet, -Mobile.

browser

No; body/guard requirements still apply

string

The browser to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Chrome, Chrome,Firefox,Safari, -IE.

os

No; body/guard requirements still apply

string

The OS to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Windows, Mac,Windows,Linux, -Windows.

trigger

No; body/guard requirements still apply

string

The trigger to retrieve analytics for. Valid values: qr, link, pageview. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: qr, qr,link, -qr. If undefined, returns all trigger types.

event_name

No; body/guard requirements still apply

string

The conversion event name to retrieve analytics for. Only available for lead and sale events. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Sign up, Sign up,Purchase, -Sign up.

referer

No; body/guard requirements still apply

string

The referer hostname to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: google.com, google.com,twitter.com, -facebook.com.

referer_url

No; body/guard requirements still apply

string

The full referer URL to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: https://google.com, https://google.com,https://twitter.com, -https://spam.com.

url

No; body/guard requirements still apply

string

The destination URL to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: https://example.com, https://example.com,https://other.com, -https://spam.com.

utm_source

No; body/guard requirements still apply

string

The UTM source to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: google, google,twitter, -spam.

utm_medium

No; body/guard requirements still apply

string

The UTM medium to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: cpc, cpc,social, -email.

utm_campaign

No; body/guard requirements still apply

string

The UTM campaign to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: summer_sale, summer_sale,winter_sale, -old_campaign.

utm_term

No; body/guard requirements still apply

string

The UTM term to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

utm_content

No; body/guard requirements still apply

string

The UTM content to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

root

No; body/guard requirements still apply

boolean

Filter for root domains. If true, filter for domains only. If false, filter for links only. If undefined, return both.

sale_type

No; body/guard requirements still apply

string

Filter sales by type: 'new' for first-time purchases, 'recurring' for repeat purchases. If undefined, returns both. enum: ["new", "recurring"].

query

No; body/guard requirements still apply

string

Search the events by a custom metadata value. Only available for lead and sale events. Examples: metadata['key']:'value' maxLength: 10000.

program_id

No; body/guard requirements still apply

string

Deprecated: This is automatically inferred from your workspace's defaultProgramId. The ID of the program to retrieve analytics for. Deprecated native compatibility field.

tag_ids

No; body/guard requirements still apply

string

Deprecated: Use tagId instead. The tag IDs to retrieve analytics for. Deprecated native compatibility field.

qr

No; body/guard requirements still apply

boolean

Deprecated: Use the trigger field instead. Filter for QR code scans. If true, filter for QR codes only. If false, filter for links only. If undefined, return both. Deprecated native compatibility field.

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0. default: 1.

limit

No; body/guard requirements still apply

integer

The number of items per page. maximum: 1000. exclusiveMinimum: 0. default: 100.

sort_order

No; body/guard requirements still apply

string

The sort order. The default is desc. enum: ["asc", "desc"]. default: "desc".

sort_by

No; body/guard requirements still apply

string

The field to sort the events by. The default is timestamp. enum: ["timestamp"]. default: "timestamp".

order

No; body/guard requirements still apply

string

DEPRECATED. Use sortOrder instead. enum: ["asc", "desc"]. default: "desc". Deprecated native compatibility field.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

create_tag

dub-cli create-tag

Create a tag for the authenticated workspace.

Argument

Required

Type

Details

name

No; body/guard requirements still apply

string

The name of the tag to create. minLength: 1. maxLength: 190.

color

No; body/guard requirements still apply

string

The color of the tag. If not provided, a random color will be used from the list: red, yellow, green, blue, purple, brown, gray. enum: ["red", "yellow", "green", "blue", "purple", "brown", "gray", "pink"].

tag

No; body/guard requirements still apply

string

The name of the tag to create. minLength: 1. maxLength: 190. Deprecated native compatibility field.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

name

No; body/guard requirements still apply

string

The name of the tag to create. minLength: 1. maxLength: 190.

color

No; body/guard requirements still apply

string

The color of the tag. If not provided, a random color will be used from the list: red, yellow, green, blue, purple, brown, gray. enum: ["red", "yellow", "green", "blue", "purple", "brown", "gray", "pink"].

tag

No; body/guard requirements still apply

string

The name of the tag to create. minLength: 1. maxLength: 190. Deprecated native compatibility field.

list_tags

dub-cli list-tags

Retrieve a paginated list of tags for the authenticated workspace.

Argument

Required

Type

Details

sort_by

No; body/guard requirements still apply

string

The field to sort the tags by. enum: ["name", "createdAt"]. default: "name".

sort_order

No; body/guard requirements still apply

string

The order to sort the tags by. enum: ["asc", "desc"]. default: "asc".

search

No; body/guard requirements still apply

string

The search term to filter the tags by.

ids

No; body/guard requirements still apply

JSON

IDs of tags to filter by.

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

page_size

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

input.ids

input.ids anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.ids anyOf branch 2

input.ids.anyOf2[]

Native JSON value; inspect the full schema for validation.

update_tag

dub-cli update-tag

Update a tag in the workspace.

Argument

Required

Type

Details

id

Yes

string

The ID of the tag to update.

name

No; body/guard requirements still apply

string

The name of the tag to create. minLength: 1. maxLength: 190.

color

No; body/guard requirements still apply

string

The color of the tag. If not provided, a random color will be used from the list: red, yellow, green, blue, purple, brown, gray. enum: ["red", "yellow", "green", "blue", "purple", "brown", "gray", "pink"].

tag

No; body/guard requirements still apply

string

The name of the tag to create. minLength: 1. maxLength: 190. Deprecated native compatibility field.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

name

No; body/guard requirements still apply

string

The name of the tag to create. minLength: 1. maxLength: 190.

color

No; body/guard requirements still apply

string

The color of the tag. If not provided, a random color will be used from the list: red, yellow, green, blue, purple, brown, gray. enum: ["red", "yellow", "green", "blue", "purple", "brown", "gray", "pink"].

tag

No; body/guard requirements still apply

string

The name of the tag to create. minLength: 1. maxLength: 190. Deprecated native compatibility field.

delete_tag

dub-cli delete-tag

Delete a tag from the workspace. All existing links will still work, but they will no longer be associated with this tag.

Argument

Required

Type

Details

id

Yes

string

The ID of the tag to delete.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

create_folder

dub-cli create-folder

Create a folder for the authenticated workspace.

Argument

Required

Type

Details

name

No; body/guard requirements still apply

string

The name of the folder. maxLength: 190.

description

No; body/guard requirements still apply

['string', 'null']

The description of the folder. maxLength: 500.

accessLevel

No; body/guard requirements still apply

['string', 'null']

The workspace-level access level settings for the folder. Default is write which allows full access to the folder for all team members. The other options are read (view-only access) and null (no access) and are only available on Business plans and above. enum: ["write", "read", null]. default: "write".

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

name

Yes

string

The name of the folder. maxLength: 190.

description

No; body/guard requirements still apply

['string', 'null']

The description of the folder. maxLength: 500.

accessLevel

No; body/guard requirements still apply

['string', 'null']

The workspace-level access level settings for the folder. Default is write which allows full access to the folder for all team members. The other options are read (view-only access) and null (no access) and are only available on Business plans and above. enum: ["write", "read", null]. default: "write".

list_folders

dub-cli list-folders

Retrieve a paginated list of folders for the authenticated workspace.

Argument

Required

Type

Details

search

No; body/guard requirements still apply

string

The search term to filter the folders by.

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

page_size

No; body/guard requirements still apply

integer

The number of items per page. maximum: 50. exclusiveMinimum: 0. default: 50.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

update_folder

dub-cli update-folder

Update a folder in the workspace.

Argument

Required

Type

Details

id

Yes

string

The ID of the folder to update.

name

No; body/guard requirements still apply

string

The name of the folder. maxLength: 190.

description

No; body/guard requirements still apply

['string', 'null']

The description of the folder. maxLength: 500.

accessLevel

No; body/guard requirements still apply

['string', 'null']

The access level of the folder within the workspace. enum: ["write", "read", null].

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

name

No; body/guard requirements still apply

string

The name of the folder. maxLength: 190.

description

No; body/guard requirements still apply

['string', 'null']

The description of the folder. maxLength: 500.

accessLevel

No; body/guard requirements still apply

['string', 'null']

The access level of the folder within the workspace. enum: ["write", "read", null].

delete_folder

dub-cli delete-folder

Delete a folder from the workspace. All existing links will still work, but they will no longer be associated with this folder.

Argument

Required

Type

Details

id

Yes

string

The ID of the folder to delete.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

create_domain

dub-cli create-domain

Create a domain for the authenticated workspace.

Argument

Required

Type

Details

slug

No; body/guard requirements still apply

string

Name of the domain. minLength: 1. maxLength: 190.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

Redirect users to a specific URL when any link under this domain has expired. maxLength: 32000.

notFoundUrl

No; body/guard requirements still apply

['string', 'null']

Redirect users to a specific URL when a link under this domain doesn't exist. maxLength: 32000.

archived

No; body/guard requirements still apply

boolean

Whether to archive this domain. false will unarchive a previously archived domain. default: false.

placeholder

No; body/guard requirements still apply

['string', 'null']

Provide context to your teammates in the link creation modal by showing them an example of a link to be shortened. maxLength: 100.

logo

No; body/guard requirements still apply

JSON

Native field; use the reviewed provider reference.

assetLinks

No; body/guard requirements still apply

['string', 'null']

assetLinks.json configuration file (for deep link support on Android).

appleAppSiteAssociation

No; body/guard requirements still apply

['string', 'null']

apple-app-site-association configuration file (for deep link support on iOS).

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.logo

input.logo anyOf branch 1

input.logo.anyOf1 anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.logo.anyOf1 anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.logo.anyOf1 anyOf branch 3

Native JSON value; inspect the full schema for validation.

input.logo anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.payload

Argument

Required

Type

Details

slug

Yes

string

Name of the domain. minLength: 1. maxLength: 190.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

Redirect users to a specific URL when any link under this domain has expired. maxLength: 32000.

notFoundUrl

No; body/guard requirements still apply

['string', 'null']

Redirect users to a specific URL when a link under this domain doesn't exist. maxLength: 32000.

archived

No; body/guard requirements still apply

boolean

Whether to archive this domain. false will unarchive a previously archived domain. default: false.

placeholder

No; body/guard requirements still apply

['string', 'null']

Provide context to your teammates in the link creation modal by showing them an example of a link to be shortened. maxLength: 100.

logo

No; body/guard requirements still apply

JSON

Native field; use the reviewed provider reference.

assetLinks

No; body/guard requirements still apply

['string', 'null']

assetLinks.json configuration file (for deep link support on Android).

appleAppSiteAssociation

No; body/guard requirements still apply

['string', 'null']

apple-app-site-association configuration file (for deep link support on iOS).

input.payload.logo

input.payload.logo anyOf branch 1

input.payload.logo.anyOf1 anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.logo.anyOf1 anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.payload.logo.anyOf1 anyOf branch 3

Native JSON value; inspect the full schema for validation.

input.payload.logo anyOf branch 2

Native JSON value; inspect the full schema for validation.

list_domains

dub-cli list-domains

Retrieve a paginated list of domains for the authenticated workspace.

Argument

Required

Type

Details

archived

No; body/guard requirements still apply

boolean

Whether to include archived domains in the response. Defaults to false if not provided. default: false.

search

No; body/guard requirements still apply

string

The search term to filter the domains by.

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

page_size

No; body/guard requirements still apply

integer

The number of items per page. maximum: 50. exclusiveMinimum: 0. default: 50.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

update_domain

dub-cli update-domain

Update a domain for the authenticated workspace.

Argument

Required

Type

Details

slug

Yes

string

Name of the domain. minLength: 1. maxLength: 190.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

Redirect users to a specific URL when any link under this domain has expired. maxLength: 32000.

notFoundUrl

No; body/guard requirements still apply

['string', 'null']

Redirect users to a specific URL when a link under this domain doesn't exist. maxLength: 32000.

archived

No; body/guard requirements still apply

boolean

Whether to archive this domain. false will unarchive a previously archived domain. default: false.

placeholder

No; body/guard requirements still apply

['string', 'null']

Provide context to your teammates in the link creation modal by showing them an example of a link to be shortened. maxLength: 100.

logo

No; body/guard requirements still apply

JSON

Native field; use the reviewed provider reference.

assetLinks

No; body/guard requirements still apply

['string', 'null']

assetLinks.json configuration file (for deep link support on Android).

appleAppSiteAssociation

No; body/guard requirements still apply

['string', 'null']

apple-app-site-association configuration file (for deep link support on iOS).

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.logo

input.logo anyOf branch 1

input.logo.anyOf1 anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.logo.anyOf1 anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.logo.anyOf1 anyOf branch 3

Native JSON value; inspect the full schema for validation.

input.logo anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.payload

Argument

Required

Type

Details

slug

No; body/guard requirements still apply

string

Name of the domain. minLength: 1. maxLength: 190.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

Redirect users to a specific URL when any link under this domain has expired. maxLength: 32000.

notFoundUrl

No; body/guard requirements still apply

['string', 'null']

Redirect users to a specific URL when a link under this domain doesn't exist. maxLength: 32000.

archived

No; body/guard requirements still apply

boolean

Whether to archive this domain. false will unarchive a previously archived domain. default: false.

placeholder

No; body/guard requirements still apply

['string', 'null']

Provide context to your teammates in the link creation modal by showing them an example of a link to be shortened. maxLength: 100.

logo

No; body/guard requirements still apply

JSON

Native field; use the reviewed provider reference.

assetLinks

No; body/guard requirements still apply

['string', 'null']

assetLinks.json configuration file (for deep link support on Android).

appleAppSiteAssociation

No; body/guard requirements still apply

['string', 'null']

apple-app-site-association configuration file (for deep link support on iOS).

input.payload.logo

input.payload.logo anyOf branch 1

input.payload.logo.anyOf1 anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.logo.anyOf1 anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.payload.logo.anyOf1 anyOf branch 3

Native JSON value; inspect the full schema for validation.

input.payload.logo anyOf branch 2

Native JSON value; inspect the full schema for validation.

delete_domain

dub-cli delete-domain

Delete a domain from a workspace. It cannot be undone. This will also delete all the links associated with the domain.

Argument

Required

Type

Details

slug

Yes

string

The domain name.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

register_domain

dub-cli register-domain

Register a domain for the authenticated workspace. Only available for Enterprise Plans.

Argument

Required

Type

Details

domain

No; body/guard requirements still apply

string

The domain to claim. We only support .link domains for now. minLength: 1. pattern: ".*\\.link$".

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

domain

Yes

string

The domain to claim. We only support .link domains for now. minLength: 1. pattern: ".*\\.link$".

check_domain_status

dub-cli check-domain-status

Check if a domain name is available for purchase. You can check multiple domains at once.

Argument

Required

Type

Details

domains

Yes

JSON

The domains to search. We only support .link domains for now.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

input.domains

input.domains anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.domains anyOf branch 2

input.domains.anyOf2[]

Native JSON value; inspect the full schema for validation.

track_lead

dub-cli track-lead

Track a lead for a short link.

Argument

Required

Type

Details

clickId

No; body/guard requirements still apply

string

The unique ID of the click that the lead conversion event is attributed to. You can read this value from dub_id cookie. [For deferred lead tracking]: If an empty string is provided, Dub will try to find an existing customer with the provided customerExternalId and use the clickId from the customer if found.

eventName

No; body/guard requirements still apply

string

The name of the lead event to track. Can also be used as a unique identifier to associate a given lead event for a customer for a subsequent sale event (via the leadEventName prop in /track/sale). minLength: 1. maxLength: 255.

customerExternalId

No; body/guard requirements still apply

string

The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer. minLength: 1. maxLength: 100.

customerName

No; body/guard requirements still apply

['string', 'null']

The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”). maxLength: 100. default: null.

customerEmail

No; body/guard requirements still apply

['string', 'null']

The email address of the customer. maxLength: 100. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". default: null. format: "email".

customerAvatar

No; body/guard requirements still apply

['string', 'null']

The avatar URL of the customer. default: null.

mode

No; body/guard requirements still apply

string

The mode to use for tracking the lead event. async will not block the request; wait will block the request until the lead event is fully recorded in Dub; deferred will defer the lead event creation to a subsequent request. enum: ["async", "wait", "deferred"]. default: "async".

eventQuantity

No; body/guard requirements still apply

['integer', 'null']

The numerical value associated with this lead event (e.g., number of provisioned seats in a free trial). If defined as N, the lead event will be tracked N times. maximum: 100. exclusiveMinimum: 0.

metadata

No; body/guard requirements still apply

['object', 'null']

Additional metadata to be stored with the lead event. Max 10,000 characters. default: null.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

clickId

Yes

string

The unique ID of the click that the lead conversion event is attributed to. You can read this value from dub_id cookie. [For deferred lead tracking]: If an empty string is provided, Dub will try to find an existing customer with the provided customerExternalId and use the clickId from the customer if found.

eventName

Yes

string

The name of the lead event to track. Can also be used as a unique identifier to associate a given lead event for a customer for a subsequent sale event (via the leadEventName prop in /track/sale). minLength: 1. maxLength: 255.

customerExternalId

Yes

string

The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer. minLength: 1. maxLength: 100.

customerName

No; body/guard requirements still apply

['string', 'null']

The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”). maxLength: 100. default: null.

customerEmail

No; body/guard requirements still apply

['string', 'null']

The email address of the customer. maxLength: 100. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". default: null. format: "email".

customerAvatar

No; body/guard requirements still apply

['string', 'null']

The avatar URL of the customer. default: null.

mode

No; body/guard requirements still apply

string

The mode to use for tracking the lead event. async will not block the request; wait will block the request until the lead event is fully recorded in Dub; deferred will defer the lead event creation to a subsequent request. enum: ["async", "wait", "deferred"]. default: "async".

eventQuantity

No; body/guard requirements still apply

['integer', 'null']

The numerical value associated with this lead event (e.g., number of provisioned seats in a free trial). If defined as N, the lead event will be tracked N times. maximum: 100. exclusiveMinimum: 0.

metadata

No; body/guard requirements still apply

['object', 'null']

Additional metadata to be stored with the lead event. Max 10,000 characters. default: null.

track_sale

dub-cli track-sale

Track a sale for a short link.

Argument

Required

Type

Details

customerExternalId

No; body/guard requirements still apply

string

The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer. minLength: 1. maxLength: 100.

amount

No; body/guard requirements still apply

integer

The amount of the sale in cents (for all two-decimal currencies). If the sale is in a zero-decimal currency, pass the full integer value (e.g. 1580 JPY). Learn more: https://d.to/currency minimum: 0. maximum: 9007199254740991.

currency

No; body/guard requirements still apply

string

The currency of the sale. Accepts ISO 4217 currency codes. Sales will be automatically converted and stored as USD at the latest exchange rates. Learn more: https://d.to/currency default: "usd".

eventName

No; body/guard requirements still apply

string

The name of the sale event. Recommended format: Invoice paid or Subscription created. maxLength: 255. default: "Purchase".

paymentProcessor

No; body/guard requirements still apply

string

The payment processor via which the sale was made. enum: ["stripe", "shopify", "polar", "paddle", "apple", "revenuecat", "lemonsqueezy", "dub", "custom"]. default: "custom".

invoiceId

No; body/guard requirements still apply

['string', 'null']

The invoice ID of the sale. Can be used as a idempotency key – only one sale event can be recorded for a given invoice ID. default: null.

metadata

No; body/guard requirements still apply

['object', 'null']

Additional metadata to be stored with the sale event. Max 10,000 characters when stringified. default: null.

leadEventName

No; body/guard requirements still apply

['string', 'null']

The name of the lead event that occurred before the sale (case-sensitive). This is used to associate the sale event with a particular lead event (instead of the latest lead event for a link-customer combination, which is the default behavior). For direct sale tracking, this field can also be used to specify the lead event name. default: null.

clickId

No; body/guard requirements still apply

['string', 'null']

[For direct sale tracking]: The unique ID of the click that the sale conversion event is attributed to. You can read this value from dub_id cookie.

customerName

No; body/guard requirements still apply

['string', 'null']

[For direct sale tracking]: The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”). maxLength: 100. default: null.

customerEmail

No; body/guard requirements still apply

['string', 'null']

[For direct sale tracking]: The email address of the customer. maxLength: 100. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". default: null. format: "email".

customerAvatar

No; body/guard requirements still apply

['string', 'null']

[For direct sale tracking]: The avatar URL of the customer. default: null.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

customerExternalId

Yes

string

The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer. minLength: 1. maxLength: 100.

amount

Yes

integer

The amount of the sale in cents (for all two-decimal currencies). If the sale is in a zero-decimal currency, pass the full integer value (e.g. 1580 JPY). Learn more: https://d.to/currency minimum: 0. maximum: 9007199254740991.

currency

No; body/guard requirements still apply

string

The currency of the sale. Accepts ISO 4217 currency codes. Sales will be automatically converted and stored as USD at the latest exchange rates. Learn more: https://d.to/currency default: "usd".

eventName

No; body/guard requirements still apply

string

The name of the sale event. Recommended format: Invoice paid or Subscription created. maxLength: 255. default: "Purchase".

paymentProcessor

No; body/guard requirements still apply

string

The payment processor via which the sale was made. enum: ["stripe", "shopify", "polar", "paddle", "apple", "revenuecat", "lemonsqueezy", "dub", "custom"]. default: "custom".

invoiceId

No; body/guard requirements still apply

['string', 'null']

The invoice ID of the sale. Can be used as a idempotency key – only one sale event can be recorded for a given invoice ID. default: null.

metadata

No; body/guard requirements still apply

['object', 'null']

Additional metadata to be stored with the sale event. Max 10,000 characters when stringified. default: null.

leadEventName

No; body/guard requirements still apply

['string', 'null']

The name of the lead event that occurred before the sale (case-sensitive). This is used to associate the sale event with a particular lead event (instead of the latest lead event for a link-customer combination, which is the default behavior). For direct sale tracking, this field can also be used to specify the lead event name. default: null.

clickId

No; body/guard requirements still apply

['string', 'null']

[For direct sale tracking]: The unique ID of the click that the sale conversion event is attributed to. You can read this value from dub_id cookie.

customerName

No; body/guard requirements still apply

['string', 'null']

[For direct sale tracking]: The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”). maxLength: 100. default: null.

customerEmail

No; body/guard requirements still apply

['string', 'null']

[For direct sale tracking]: The email address of the customer. maxLength: 100. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". default: null. format: "email".

customerAvatar

No; body/guard requirements still apply

['string', 'null']

[For direct sale tracking]: The avatar URL of the customer. default: null.

track_open

dub-cli track-open

This endpoint is used to track when a user opens your app via a Dub-powered deep link (for both iOS and Android).

Argument

Required

Type

Details

deepLink

No; body/guard requirements still apply

string

The deep link that brought the user to the app. If left blank, Dub will fallback to probabilistic tracking by using the dubDomain parameter to check if there is an associated click event for the user's IP address. Learn more: https://d.to/ddl maxLength: 32000.

dubDomain

No; body/guard requirements still apply

string

Your deep link custom domain on Dub (e.g. acme.link). This is used in probabilistic tracking to check if there is an associated click event for the user's IP address. Learn more: https://d.to/ddl

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

deepLink

No; body/guard requirements still apply

string

The deep link that brought the user to the app. If left blank, Dub will fallback to probabilistic tracking by using the dubDomain parameter to check if there is an associated click event for the user's IP address. Learn more: https://d.to/ddl maxLength: 32000.

dubDomain

No; body/guard requirements still apply

string

Your deep link custom domain on Dub (e.g. acme.link). This is used in probabilistic tracking to check if there is an associated click event for the user's IP address. Learn more: https://d.to/ddl

list_customers

dub-cli list-customers

Retrieve a paginated list of customers for the authenticated workspace.

Argument

Required

Type

Details

email

No; body/guard requirements still apply

string

A case-sensitive filter on the list based on the customer's email field. The value must be a string. Takes precedence over externalId.

external_id

No; body/guard requirements still apply

string

A case-sensitive filter on the list based on the customer's externalId field. The value must be a string. Takes precedence over search.

search

No; body/guard requirements still apply

string

A search query to filter customers by email, name, or customer ID (cus_...). If email or externalId is provided, this will be ignored.

country

No; body/guard requirements still apply

string

A filter on the list based on the customer's country field.

link_id

No; body/guard requirements still apply

string

A filter on the list based on the customer's linkId field (the referral link ID).

program_id

No; body/guard requirements still apply

string

Program ID to filter by.

partner_id

No; body/guard requirements still apply

string

Partner ID to filter by.

include_expanded_fields

No; body/guard requirements still apply

boolean

Whether to include expanded fields on the customer (link, partner, discount).

sort_by

No; body/guard requirements still apply

string

The field to sort the customers by. The default is createdAt. enum: ["createdAt", "saleAmount", "firstSaleAt", "subscriptionCanceledAt"]. default: "createdAt".

sort_order

No; body/guard requirements still apply

string

The sort order. The default is desc. enum: ["asc", "desc"]. default: "desc".

ending_before

No; body/guard requirements still apply

string

If specified, the query only searches for results before this cursor. Mutually exclusive with startingAfter.

starting_after

No; body/guard requirements still apply

string

If specified, the query only searches for results after this cursor. Mutually exclusive with endingBefore.

page

No; body/guard requirements still apply

integer

DEPRECATED. Use startingAfter instead. maximum: 9007199254740991. exclusiveMinimum: 0. Deprecated native compatibility field.

page_size

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

get_customer

dub-cli get-customer

Retrieve a customer by ID for the authenticated workspace. To retrieve a customer by external ID, prefix the ID with ext_.

Argument

Required

Type

Details

id

Yes

string

The unique ID of the customer. You may use either the customer's id on Dub (obtained via /customers endpoint) or their externalId (unique ID within your system, prefixed with ext_, e.g. ext_123).

include_expanded_fields

No; body/guard requirements still apply

boolean

Whether to include expanded fields on the customer (link, partner, discount).

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

update_customer

dub-cli update-customer

Update a customer for the authenticated workspace.

Argument

Required

Type

Details

id

Yes

string

The unique ID of the customer. You may use either the customer's id on Dub (obtained via /customers endpoint) or their externalId (unique ID within your system, prefixed with ext_, e.g. ext_123).

include_expanded_fields

No; body/guard requirements still apply

boolean

Whether to include expanded fields on the customer (link, partner, discount).

email

No; body/guard requirements still apply

['string', 'null']

The customer's email address. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". format: "email".

name

No; body/guard requirements still apply

['string', 'null']

The customer's name. If not provided, the email address will be used, and if email is not provided, a random name will be generated.

avatar

No; body/guard requirements still apply

['string', 'null']

The customer's avatar URL. If not provided, a random avatar will be generated. format: "uri".

externalId

No; body/guard requirements still apply

string

The customer's unique identifier your database. This is useful for associating subsequent conversion events from Dub's API to your internal systems.

stripeCustomerId

No; body/guard requirements still apply

['string', 'null']

The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.

country

No; body/guard requirements still apply

string

The customer's country in ISO 3166-1 alpha-2 format. Updating this field will only affect the customer's country in Dub's system (and has no effect on existing conversion events).

subscriptionCanceledAt

No; body/guard requirements still apply

['string', 'null']

The date the customer canceled their subscription. Set to a timestamp to mark the subscription as canceled, or null to clear it (e.g. if they resubscribe).

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

email

No; body/guard requirements still apply

['string', 'null']

The customer's email address. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". format: "email".

name

No; body/guard requirements still apply

['string', 'null']

The customer's name. If not provided, the email address will be used, and if email is not provided, a random name will be generated.

avatar

No; body/guard requirements still apply

['string', 'null']

The customer's avatar URL. If not provided, a random avatar will be generated. format: "uri".

externalId

No; body/guard requirements still apply

string

The customer's unique identifier your database. This is useful for associating subsequent conversion events from Dub's API to your internal systems.

stripeCustomerId

No; body/guard requirements still apply

['string', 'null']

The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.

country

No; body/guard requirements still apply

string

The customer's country in ISO 3166-1 alpha-2 format. Updating this field will only affect the customer's country in Dub's system (and has no effect on existing conversion events).

subscriptionCanceledAt

No; body/guard requirements still apply

['string', 'null']

The date the customer canceled their subscription. Set to a timestamp to mark the subscription as canceled, or null to clear it (e.g. if they resubscribe).

delete_customer

dub-cli delete-customer

Delete a customer from a workspace.

Argument

Required

Type

Details

id

Yes

string

The unique ID of the customer. You may use either the customer's id on Dub (obtained via /customers endpoint) or their externalId (unique ID within your system, prefixed with ext_, e.g. ext_123).

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

create_partner

dub-cli create-partner

Creates or updates a partner record (upsert behavior). If a partner with the same email already exists, their program enrollment will be updated with the provided tenantId. If no existing partner is found, a new partner will be created using the supplied information.

Argument

Required

Type

Details

name

No; body/guard requirements still apply

['string', 'null']

The partner's full name. If undefined, the partner's email will be used in lieu of their name (e.g. john@acme.com) maxLength: 100.

email

No; body/guard requirements still apply

string

The partner's email address. Partners will be able to claim their profile by signing up at partners.dub.co with this email. maxLength: 190. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". format: "email".

username

No; body/guard requirements still apply

['string', 'null']

The partner's unique username in your system (max 100 characters). This will be used to create a short link for the partner using your program's default domain. If not provided, Dub will try to generate a username from the partner's name or email. maxLength: 100.

image

No; body/guard requirements still apply

['string', 'null']

The partner's avatar image. If not provided, a default avatar will be used.

tenantId

No; body/guard requirements still apply

string

The partner's unique ID in your system. Useful for retrieving the partner's links and stats later on. If not provided, the partner will be created as a standalone partner.

groupId

No; body/guard requirements still apply

string

The group ID to add the partner to. If not provided, the partner will be added to the default group.

country

No; body/guard requirements still apply

['string', 'null']

The partner's country of residence. Must be passed as a 2-letter ISO 3166-1 country code. See https://d.to/geo for more information.

description

No; body/guard requirements still apply

['string', 'null']

A brief description of the partner and their background. Max 5,000 characters. maxLength: 5000.

linkProps

No; body/guard requirements still apply

object

Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.linkProps

Argument

Required

Type

Details

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

prefix

No; body/guard requirements still apply

string

Path prefix for each default referral link slug (e.g. /c/ → https://{domain}/c/{identity}). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. c/jane-a7f2).

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

input.linkProps.tagIds

input.linkProps.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.linkProps.tagIds anyOf branch 2

input.linkProps.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.linkProps.tagNames

input.linkProps.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.linkProps.tagNames anyOf branch 2

input.linkProps.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.linkProps.testVariants

input.linkProps.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.payload

Argument

Required

Type

Details

name

No; body/guard requirements still apply

['string', 'null']

The partner's full name. If undefined, the partner's email will be used in lieu of their name (e.g. john@acme.com) maxLength: 100.

email

Yes

string

The partner's email address. Partners will be able to claim their profile by signing up at partners.dub.co with this email. maxLength: 190. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". format: "email".

username

No; body/guard requirements still apply

['string', 'null']

The partner's unique username in your system (max 100 characters). This will be used to create a short link for the partner using your program's default domain. If not provided, Dub will try to generate a username from the partner's name or email. maxLength: 100.

image

No; body/guard requirements still apply

['string', 'null']

The partner's avatar image. If not provided, a default avatar will be used.

tenantId

No; body/guard requirements still apply

string

The partner's unique ID in your system. Useful for retrieving the partner's links and stats later on. If not provided, the partner will be created as a standalone partner.

groupId

No; body/guard requirements still apply

string

The group ID to add the partner to. If not provided, the partner will be added to the default group.

country

No; body/guard requirements still apply

['string', 'null']

The partner's country of residence. Must be passed as a 2-letter ISO 3166-1 country code. See https://d.to/geo for more information.

description

No; body/guard requirements still apply

['string', 'null']

A brief description of the partner and their background. Max 5,000 characters. maxLength: 5000.

linkProps

No; body/guard requirements still apply

object

Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.

input.payload.linkProps

Argument

Required

Type

Details

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

prefix

No; body/guard requirements still apply

string

Path prefix for each default referral link slug (e.g. /c/ → https://{domain}/c/{identity}). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. c/jane-a7f2).

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

input.payload.linkProps.tagIds

input.payload.linkProps.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.linkProps.tagIds anyOf branch 2

input.payload.linkProps.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.linkProps.tagNames

input.payload.linkProps.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.linkProps.tagNames anyOf branch 2

input.payload.linkProps.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.linkProps.testVariants

input.payload.linkProps.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

list_partners

dub-cli list-partners

List all partners for a partner program.

Argument

Required

Type

Details

group_id

No; body/guard requirements still apply

string

A filter on the list based on the partner's groupId field.

status

No; body/guard requirements still apply

string

A filter on the list based on the partner's status field. enum: ["pending", "approved", "rejected", "invited", "declined", "deactivated", "banned", "archived"].

country

No; body/guard requirements still apply

string

A filter on the list based on the partner's country field.

sort_by

No; body/guard requirements still apply

string

The field to sort the partners by. The default is totalSaleAmount. enum: ["createdAt", "totalClicks", "totalLeads", "totalConversions", "totalSaleAmount", "totalCommissions", "netRevenue", "earningsPerClick", "averageLifetimeValue", "clickToLeadRate", "clickToConversionRate", "leadToConversionRate", "returnOnAdSpend"]. default: "totalSaleAmount".

sort_order

No; body/guard requirements still apply

string

The sort order. The default is desc. enum: ["asc", "desc"]. default: "desc".

email

No; body/guard requirements still apply

string

Filter the partner list based on the partner's email. The value must be a string. Takes precedence over search.

tenant_id

No; body/guard requirements still apply

string

Filter the partner list based on the partner's tenantId. The value must be a string. Combines with the other filters.

search

No; body/guard requirements still apply

string

A search query to filter partners by ID, name, email, company name, description, social platforms, or referral links. Partial matches are supported.

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

page_size

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

dub-cli create-partner-link

Create a link for a partner that is enrolled in your program.

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

url

No; body/guard requirements still apply

['string', 'null']

The URL to shorten (if not provided, the program's default URL will be used). maxLength: 32000.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

linkProps

No; body/guard requirements still apply

object

Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.linkProps

Argument

Required

Type

Details

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

prefix

No; body/guard requirements still apply

string

Path prefix for each default referral link slug (e.g. /c/ → https://{domain}/c/{identity}). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. c/jane-a7f2).

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

input.linkProps.tagIds

input.linkProps.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.linkProps.tagIds anyOf branch 2

input.linkProps.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.linkProps.tagNames

input.linkProps.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.linkProps.tagNames anyOf branch 2

input.linkProps.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.linkProps.testVariants

input.linkProps.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.payload

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

url

No; body/guard requirements still apply

['string', 'null']

The URL to shorten (if not provided, the program's default URL will be used). maxLength: 32000.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

linkProps

No; body/guard requirements still apply

object

Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.

input.payload.linkProps

Argument

Required

Type

Details

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

prefix

No; body/guard requirements still apply

string

Path prefix for each default referral link slug (e.g. /c/ → https://{domain}/c/{identity}). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. c/jane-a7f2).

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

input.payload.linkProps.tagIds

input.payload.linkProps.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.linkProps.tagIds anyOf branch 2

input.payload.linkProps.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.linkProps.tagNames

input.payload.linkProps.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.linkProps.tagNames anyOf branch 2

input.payload.linkProps.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.linkProps.testVariants

input.payload.linkProps.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

dub-cli retrieve-partner-links

Retrieve a partner's links by their partner ID or tenant ID.

Argument

Required

Type

Details

partner_id

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenant_id

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

dub-cli upsert-partner-link

Upsert a link for a partner that is enrolled in your program. If a link with the same URL already exists, return it (or update it if there are any changes). Otherwise, a new link will be created.

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

url

No; body/guard requirements still apply

string

The URL to upsert for. maxLength: 32000.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

linkProps

No; body/guard requirements still apply

object

Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.linkProps

Argument

Required

Type

Details

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

prefix

No; body/guard requirements still apply

string

Path prefix for each default referral link slug (e.g. /c/ → https://{domain}/c/{identity}). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. c/jane-a7f2).

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

input.linkProps.tagIds

input.linkProps.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.linkProps.tagIds anyOf branch 2

input.linkProps.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.linkProps.tagNames

input.linkProps.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.linkProps.tagNames anyOf branch 2

input.linkProps.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.linkProps.testVariants

input.linkProps.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.payload

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

url

Yes

string

The URL to upsert for. maxLength: 32000.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

linkProps

No; body/guard requirements still apply

object

Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.

input.payload.linkProps

Argument

Required

Type

Details

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

prefix

No; body/guard requirements still apply

string

Path prefix for each default referral link slug (e.g. /c/ → https://{domain}/c/{identity}). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. c/jane-a7f2).

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

input.payload.linkProps.tagIds

input.payload.linkProps.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.linkProps.tagIds anyOf branch 2

input.payload.linkProps.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.linkProps.tagNames

input.payload.linkProps.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.linkProps.tagNames anyOf branch 2

input.payload.linkProps.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.linkProps.testVariants

input.payload.linkProps.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

retrieve_partner_analytics

dub-cli retrieve-partner-analytics

Retrieve analytics for a partner within a program. The response type vary based on the groupBy query parameter.

Argument

Required

Type

Details

partner_id

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenant_id

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

interval

No; body/guard requirements still apply

string

The interval to retrieve analytics for. If undefined, defaults to 24h. enum: ["24h", "7d", "30d", "90d", "1y", "mtd", "qtd", "ytd", "all"].

start

No; body/guard requirements still apply

string

The start date and time when to retrieve analytics from. If set, takes precedence over interval.

end

No; body/guard requirements still apply

string

The end date and time when to retrieve analytics from. If not provided, defaults to the current date. If set along with start, takes precedence over interval.

timezone

No; body/guard requirements still apply

string

The IANA time zone code for aligning timeseries granularity (e.g. America/New_York). Defaults to UTC. default: "UTC".

query

No; body/guard requirements still apply

string

Search the events by a custom metadata value. Only available for lead and sale events. Examples: metadata['key']:'value' maxLength: 10000.

group_by

No; body/guard requirements still apply

string

The parameter to group the analytics data points by. Defaults to count if undefined. enum: ["top_links", "timeseries", "count"]. default: "count".

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

ban_partner

dub-cli ban-partner

Ban a partner from your program. This will disable all links and mark all commissions as canceled.

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

reason

No; body/guard requirements still apply

string

The reason for banning the partner. enum: ["tos_violation", "inappropriate_content", "fake_traffic", "fraud", "spam", "brand_abuse"].

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

reason

Yes

string

The reason for banning the partner. enum: ["tos_violation", "inappropriate_content", "fake_traffic", "fraud", "spam", "brand_abuse"].

deactivate_partner

dub-cli deactivate-partner

This will deactivate the partner from your program and disable all their active links. Their commissions and payouts will remain intact. You can reactivate them later if needed.

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

list_program_applications

dub-cli list-program-applications

Retrieve a paginated list of applications for your partner program. Filter by status to list pending, approved, or rejected applications.

Argument

Required

Type

Details

country

No; body/guard requirements still apply

string

A filter on the list based on the partner's country field.

group_id

No; body/guard requirements still apply

string

A filter on the list based on the partner's groupId field.

sort_order

No; body/guard requirements still apply

string

The sort order. The default is desc. enum: ["asc", "desc"]. default: "desc".

search

No; body/guard requirements still apply

string

Filter applications by name, email, or company name. Partial matches are supported. An exact partner ID is also matched.

status

No; body/guard requirements still apply

string

Filter applications by status. One of pending, approved, or rejected. Defaults to pending. enum: ["pending", "approved", "rejected"]. default: "pending".

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

page_size

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

approve_program_application

dub-cli approve-program-application

Approve a pending partner application to your program. The partner will be enrolled in the specified group and notified of the approval.

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

string

The ID of the partner to approve.

groupId

No; body/guard requirements still apply

['string', 'null']

The ID of the group to assign the partner to. If not provided, the partner will be assigned to the group they applied to, or the program's default group if no application group is set.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

partnerId

Yes

string

The ID of the partner to approve.

groupId

No; body/guard requirements still apply

['string', 'null']

The ID of the group to assign the partner to. If not provided, the partner will be assigned to the group they applied to, or the program's default group if no application group is set.

reject_program_application

dub-cli reject-program-application

Reject a pending partner application to your program. The partner will be notified via email that their application was not approved.

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

string

The ID of the partner to reject.

rejectionReason

No; body/guard requirements still apply

string

The reason for rejecting the partner application. This will be shared with the partner via email. enum: ["needsMoreDetail", "doesNotMeetRequirements", "notTheRightFit", "other"].

rejectionNote

No; body/guard requirements still apply

string

Additional details about the rejection. This will be shared with the partner via email. maxLength: 500.

reapplicationTimeframe

No; body/guard requirements still apply

string

The mode for reapplying for the program. instant: The partner can reapply immediately. standard: The partner can reapply after 30 days. never: The partner can never reapply for the program. Defaults to standard if undefined. enum: ["instant", "standard", "never"]. default: "standard".

flagForFraud

No; body/guard requirements still apply

boolean

Whether to flag the partner for fraud review by the Dub team. Cannot be combined with reapplicationTimeframe: instant.

flagForFraudReason

No; body/guard requirements still apply

string

The reason for flagging the partner for fraud. Required when flagForFraud is true. maxLength: 2000.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

partnerId

Yes

string

The ID of the partner to reject.

rejectionReason

No; body/guard requirements still apply

string

The reason for rejecting the partner application. This will be shared with the partner via email. enum: ["needsMoreDetail", "doesNotMeetRequirements", "notTheRightFit", "other"].

rejectionNote

No; body/guard requirements still apply

string

Additional details about the rejection. This will be shared with the partner via email. maxLength: 500.

reapplicationTimeframe

No; body/guard requirements still apply

string

The mode for reapplying for the program. instant: The partner can reapply immediately. standard: The partner can reapply after 30 days. never: The partner can never reapply for the program. Defaults to standard if undefined. enum: ["instant", "standard", "never"]. default: "standard".

flagForFraud

No; body/guard requirements still apply

boolean

Whether to flag the partner for fraud review by the Dub team. Cannot be combined with reapplicationTimeframe: instant.

flagForFraudReason

No; body/guard requirements still apply

string

The reason for flagging the partner for fraud. Required when flagForFraud is true. maxLength: 2000.

list_discount_codes

dub-cli list-discount-codes

Retrieve a paginated list of discount codes in a program or filtered by partner, discount, or code.

Argument

Required

Type

Details

partner_id

No; body/guard requirements still apply

string

The ID of the partner to retrieve discount codes for. If omitted, returns discount codes for the whole program.

discount_id

No; body/guard requirements still apply

string

Filter discount codes by discount ID.

code

No; body/guard requirements still apply

string

Filter discount codes by the alphanumeric code (e.g. PARTNER10OFF).

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

page_size

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

create_discount_code

dub-cli create-discount-code

Create a discount code for a partner. The partner's group must already have a discount assigned to it, and the discount code must be associated with a link that is not already linked with another discount code.

Argument

Required

Type

Details

code

No; body/guard requirements still apply

string

The discount code to create. If omitted, a unique code will be generated automatically from the partner's name. Stripe and Shopify codes can only contain letters, numbers, dashes, and underscores. Custom provider codes can contain any characters. maxLength: 100.

partnerId

No; body/guard requirements still apply

string

The ID of the partner to create a discount code for.

linkId

No; body/guard requirements still apply

string

The ID of the partner's referral link to associate this discount code with. Each link can only have one discount code.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

code

No; body/guard requirements still apply

string

The discount code to create. If omitted, a unique code will be generated automatically from the partner's name. Stripe and Shopify codes can only contain letters, numbers, dashes, and underscores. Custom provider codes can contain any characters. maxLength: 100.

partnerId

Yes

string

The ID of the partner to create a discount code for.

linkId

Yes

string

The ID of the partner's referral link to associate this discount code with. Each link can only have one discount code.

delete_discount_code

dub-cli delete-discount-code

Delete a discount code for a partner by its unique ID or alphanumeric code. This will also disable the code in your connected discount provider (Stripe, Shopify, or custom via disccount.deleted webhook).

Argument

Required

Type

Details

id_or_code

Yes

string

The unique ID (e.g. dcode_...) or alphanumeric code (e.g. ABC123) of the discount code to delete.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

create_commission

dub-cli create-commission

Create one or more commissions (custom, lead or sale) for a partner. Custom commissions accept a negative amount to create a clawback. Commission creation is processed asynchronously – use the GET /commissions endpoint or webhooks to be notified when the commission is created.

Argument

Required

Type

Details

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

input.payload oneOf branch 1

Argument

Required

Type

Details

type

Yes

string

Native field; use the reviewed provider reference. enum: ["custom"].

partnerId

Yes

string

The ID of the partner to create the commission for.

amount

Yes

number

The commission earnings amount in cents. Use a negative amount to create a clawback.

date

No; body/guard requirements still apply

['string', 'null']

If not provided, the current date will be used.

description

No; body/guard requirements still apply

['string', 'null']

The description of the commission. Required for clawbacks (negative amount). May be a known clawback reason (order_canceled, fraud, terms_violation, tracking_error, payment_failed, ineligible_partner, duplicate_commission) or an arbitrary string (max 190 characters). maxLength: 190.

input.payload oneOf branch 2

Argument

Required

Type

Details

type

Yes

string

Native field; use the reviewed provider reference. enum: ["lead"].

partnerId

Yes

string

The ID of the partner to create the commission for.

customerId

No; body/guard requirements still apply

['string', 'null']

The customer ID to associate the commission with. Useful if the customer was already created in a prior operation and you want to associate the commission with it.

customer

No; body/guard requirements still apply

['object', 'null']

The full customer object to associate the commission with. Useful for creating the customer on demand.

linkId

No; body/guard requirements still apply

['string', 'null']

The partner link ID to associate the commission with. If not provided, default to the link with the most revenue.

date

No; body/guard requirements still apply

['string', 'null']

The date and time of the lead event. If not provided, defaults to the current date and time.

lead

No; body/guard requirements still apply

['object', 'null']

The lead event object to associate the commission with.

leadEventDate

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use date instead. The date and time of the lead event. If not provided, defaults to the current date and time. Deprecated native compatibility field.

leadEventName

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use lead.eventName instead. The name of the lead event. If not provided, defaults to 'Sign up'. default: "Sign up". Deprecated native compatibility field.

input.payload.oneOf2.customer

Argument

Required

Type

Details

email

No; body/guard requirements still apply

['string', 'null']

The customer's email address. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". format: "email".

name

No; body/guard requirements still apply

['string', 'null']

The customer's name. If not provided, the email address will be used, and if email is not provided, a random name will be generated.

avatar

No; body/guard requirements still apply

['string', 'null']

The customer's avatar URL. If not provided, a random avatar will be generated. format: "uri".

externalId

Yes

string

The customer's unique identifier your database. This is useful for associating subsequent conversion events from Dub's API to your internal systems.

stripeCustomerId

No; body/guard requirements still apply

['string', 'null']

The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.

country

Yes

string

The customer's country in ISO 3166-1 alpha-2 format. Updating this field will only affect the customer's country in Dub's system (and has no effect on existing conversion events).

input.payload.oneOf2.lead

Argument

Required

Type

Details

eventName

No; body/guard requirements still apply

['string', 'null']

The name of the lead event to track. If not provided, defaults to 'Sign up'. minLength: 1. maxLength: 255.

metadata

No; body/guard requirements still apply

['object', 'null']

Additional metadata to be stored with the lead event. Max 10,000 characters. default: null.

input.payload oneOf branch 3

Argument

Required

Type

Details

type

Yes

string

Native field; use the reviewed provider reference. enum: ["sale"].

partnerId

Yes

string

The ID of the partner to create the commission for.

customerId

No; body/guard requirements still apply

['string', 'null']

The customer ID to associate the commission with. Useful if the customer was already created in a prior operation and you want to associate the commission with it.

customer

No; body/guard requirements still apply

['object', 'null']

The full customer object to associate the commission with. Useful for creating the customer on demand.

linkId

No; body/guard requirements still apply

['string', 'null']

The partner link ID to associate the commission with. If neither linkId nor discountCode is provided, default to the link with the most revenue.

discountCode

No; body/guard requirements still apply

['string', 'null']

The partner discount code to resolve the associated link. Use this when the link ID is unknown. Cannot be provided together with linkId. minLength: 1.

importStripeInvoices

No; body/guard requirements still apply

['boolean', 'null']

When true, import all unimported paid Stripe invoices for the customer and create a commission for each. When false, create a single manual sale event using sale.amount (or deprecated saleAmount). default: false.

date

No; body/guard requirements still apply

['string', 'null']

Only used when importStripeInvoices is false. The date of the manual sale event. Defaults to the current date and time if not provided.

sale

No; body/guard requirements still apply

['object', 'null']

The sale event object to associate the commission with.

saleEventDate

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use date instead. Deprecated native compatibility field.

saleAmount

No; body/guard requirements still apply

['number', 'null']

Deprecated: Use sale.amount instead. Deprecated native compatibility field.

invoiceId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use sale.invoiceId instead. Deprecated native compatibility field.

productId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use sale.metadata.productId instead. Deprecated native compatibility field.

input.payload.oneOf3.customer

Argument

Required

Type

Details

email

No; body/guard requirements still apply

['string', 'null']

The customer's email address. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". format: "email".

name

No; body/guard requirements still apply

['string', 'null']

The customer's name. If not provided, the email address will be used, and if email is not provided, a random name will be generated.

avatar

No; body/guard requirements still apply

['string', 'null']

The customer's avatar URL. If not provided, a random avatar will be generated. format: "uri".

externalId

Yes

string

The customer's unique identifier your database. This is useful for associating subsequent conversion events from Dub's API to your internal systems.

stripeCustomerId

No; body/guard requirements still apply

['string', 'null']

The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.

country

Yes

string

The customer's country in ISO 3166-1 alpha-2 format. Updating this field will only affect the customer's country in Dub's system (and has no effect on existing conversion events).

input.payload.oneOf3.sale

Argument

Required

Type

Details

amount

No; body/guard requirements still apply

['number', 'null']

The amount of the sale in cents (for all two-decimal currencies). If the sale is in a zero-decimal currency, pass the full integer value (e.g. 1580 JPY). Learn more: https://d.to/currency

currency

No; body/guard requirements still apply

string

The currency of the sale. Accepts ISO 4217 currency codes. Sales will be automatically converted and stored as USD at the latest exchange rates. Learn more: https://d.to/currency default: "usd".

eventName

No; body/guard requirements still apply

string

The name of the sale event. Recommended format: Invoice paid or Subscription created. maxLength: 255. default: "Purchase".

paymentProcessor

No; body/guard requirements still apply

string

The payment processor via which the sale was made. enum: ["stripe", "shopify", "polar", "paddle", "apple", "revenuecat", "lemonsqueezy", "dub", "custom"]. default: "custom".

invoiceId

No; body/guard requirements still apply

['string', 'null']

The invoice ID of the sale. Can be used as a idempotency key – only one sale event can be recorded for a given invoice ID. default: null.

metadata

No; body/guard requirements still apply

['object', 'null']

Additional metadata to be stored with the sale event. Max 10,000 characters when stringified. default: null.

list_commissions

dub-cli list-commissions

Retrieve a paginated list of commissions for your partner program.

Argument

Required

Type

Details

type

No; body/guard requirements still apply

string

Filter the list of commissions by type. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: - "sale" - "sale,lead" - "-click" enum: ["click", "lead", "sale", "referral", "custom"].

customer_id

No; body/guard requirements still apply

string

Filter the list of commissions by the associated customer.

payout_id

No; body/guard requirements still apply

string

Filter the list of commissions by the associated payout.

bounty_submission_id

No; body/guard requirements still apply

string

Filter the list of commissions by the associated bounty submission.

partner_id

No; body/guard requirements still apply

string

Filter the list of commissions by the associated partner. When specified, takes precedence over tenantId. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: - "partner_abc" - "partner_abc,partner_xyz" - "-partner_abc"

tenant_id

No; body/guard requirements still apply

string

Filter the list of commissions by the associated partner's tenantId (their unique ID within your database).

group_id

No; body/guard requirements still apply

string

Filter the list of commissions by the associated partner group. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: - "group_abc" - "group_abc,group_xyz" - "-group_abc"

partner_tag_id

No; body/guard requirements still apply

string

Filter the list of commissions by the associated partner tag. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: - "ptag_abc" - "ptag_abc,ptag_xyz" - "-ptag_abc"

invoice_id

No; body/guard requirements still apply

string

Filter the list of commissions by the associated invoice. Since invoiceId is unique on a per-program basis, this will only return one commission per invoice.

status

No; body/guard requirements still apply

string

Filter the list of commissions by their corresponding status. enum: ["pending", "processed", "paid", "refunded", "duplicate", "fraud", "canceled", "hold"].

sort_by

No; body/guard requirements still apply

string

The field to sort the list of commissions by. enum: ["createdAt", "amount"]. default: "createdAt".

sort_order

No; body/guard requirements still apply

string

The sort order for the list of commissions. enum: ["asc", "desc"]. default: "desc".

interval

No; body/guard requirements still apply

string

The interval to retrieve commissions for. enum: ["24h", "7d", "30d", "90d", "1y", "mtd", "qtd", "ytd", "all"]. default: "all".

start

No; body/guard requirements still apply

string

The start date of the date range to filter the commissions by.

end

No; body/guard requirements still apply

string

The end date of the date range to filter the commissions by.

timezone

No; body/guard requirements still apply

string

Native field; use the reviewed provider reference.

query

No; body/guard requirements still apply

string

Filter by lead or sale event metadata. Top-level keys only. Compares string values only : numeric and boolean metadata values are not matched. Examples: - "metadata['key']='value'" - "metadata['key']!='value'" maxLength: 10000.

ending_before

No; body/guard requirements still apply

string

If specified, the query only searches for results before this cursor. Mutually exclusive with startingAfter.

starting_after

No; body/guard requirements still apply

string

If specified, the query only searches for results after this cursor. Mutually exclusive with endingBefore.

page

No; body/guard requirements still apply

integer

DEPRECATED. Use startingAfter instead. maximum: 9007199254740991. exclusiveMinimum: 0. Deprecated native compatibility field.

page_size

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

update_commission

dub-cli update-commission

Update an existing commission amount. This is useful for handling refunds (partial or full) or fraudulent sales.

Argument

Required

Type

Details

id

Yes

string

The commission's unique ID on Dub.

earnings

No; body/guard requirements still apply

number

The new earnings amount for the commission. Paid commissions cannot be updated. If provided, will override the earnings calculated based on the sale amount and currency. minimum: 0.

saleAmount

No; body/guard requirements still apply

number

The new absolute amount for the sale. Paid commissions cannot be updated. minimum: 0.

modifySaleAmount

No; body/guard requirements still apply

number

Modify the current sale amount: use positive values to increase the amount, negative values to decrease it. Takes precedence over saleAmount. Paid commissions cannot be updated.

currency

No; body/guard requirements still apply

string

The currency of the sale amount to update. Accepts ISO 4217 currency codes. default: "usd".

status

No; body/guard requirements still apply

string

Useful for marking a commission as pending, refunded, duplicate, canceled, or fraudulent. Takes precedence over saleAmount and modifySaleAmount. When a commission is marked as pending, refunded, duplicate, canceled, or fraudulent, it will be omitted from the payout, and the payout amount will be recalculated accordingly. Paid commissions cannot be updated. enum: ["pending", "refunded", "duplicate", "canceled", "fraud"].

amount

No; body/guard requirements still apply

number

Deprecated. Use saleAmount instead. minimum: 0. Deprecated native compatibility field.

modifyAmount

No; body/guard requirements still apply

number

Deprecated. Use modifySaleAmount instead. Deprecated native compatibility field.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

earnings

No; body/guard requirements still apply

number

The new earnings amount for the commission. Paid commissions cannot be updated. If provided, will override the earnings calculated based on the sale amount and currency. minimum: 0.

saleAmount

No; body/guard requirements still apply

number

The new absolute amount for the sale. Paid commissions cannot be updated. minimum: 0.

modifySaleAmount

No; body/guard requirements still apply

number

Modify the current sale amount: use positive values to increase the amount, negative values to decrease it. Takes precedence over saleAmount. Paid commissions cannot be updated.

currency

No; body/guard requirements still apply

string

The currency of the sale amount to update. Accepts ISO 4217 currency codes. default: "usd".

status

No; body/guard requirements still apply

string

Useful for marking a commission as pending, refunded, duplicate, canceled, or fraudulent. Takes precedence over saleAmount and modifySaleAmount. When a commission is marked as pending, refunded, duplicate, canceled, or fraudulent, it will be omitted from the payout, and the payout amount will be recalculated accordingly. Paid commissions cannot be updated. enum: ["pending", "refunded", "duplicate", "canceled", "fraud"].

amount

No; body/guard requirements still apply

number

Deprecated. Use saleAmount instead. minimum: 0. Deprecated native compatibility field.

modifyAmount

No; body/guard requirements still apply

number

Deprecated. Use modifySaleAmount instead. Deprecated native compatibility field.

bulk_update_commissions

dub-cli bulk-update-commissions

Bulk update up to 100 commissions with the same status.

Argument

Required

Type

Details

commissionIds

No; body/guard requirements still apply

array

Native field; use the reviewed provider reference. minItems: 1. maxItems: 100.

status

No; body/guard requirements still apply

string

The status to apply to every commission in the batch. enum: ["pending", "refunded", "duplicate", "canceled", "fraud"].

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.commissionIds

input.commissionIds[]

Native JSON value; inspect the full schema for validation.

input.payload

Argument

Required

Type

Details

commissionIds

Yes

array

Native field; use the reviewed provider reference. minItems: 1. maxItems: 100.

status

Yes

string

The status to apply to every commission in the batch. enum: ["pending", "refunded", "duplicate", "canceled", "fraud"].

input.payload.commissionIds

input.payload.commissionIds[]

Native JSON value; inspect the full schema for validation.

list_payouts

dub-cli list-payouts

Retrieve a paginated list of payouts for your partner program.

Argument

Required

Type

Details

status

No; body/guard requirements still apply

string

Filter the list of payouts by their corresponding status. enum: ["pending", "processing", "processed", "sent", "completed", "failed", "canceled"].

partner_id

No; body/guard requirements still apply

string

Filter the list of payouts by the associated partner. When specified, takes precedence over tenantId.

tenant_id

No; body/guard requirements still apply

string

Filter the list of payouts by the associated partner's tenantId (their unique ID within your database).

invoice_id

No; body/guard requirements still apply

string

Filter the list of payouts by invoice ID (the unique ID of the invoice you receive for each batch payout you process on Dub). Pending payouts will not have an invoice ID.

group_id

No; body/guard requirements still apply

string

Filter the list of payouts by the associated partner group. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: group_abc, group_abc,group_xyz, -group_abc.

sort_by

No; body/guard requirements still apply

string

The field to sort the list of payouts by. enum: ["amount", "initiatedAt", "paidAt"]. default: "amount".

sort_order

No; body/guard requirements still apply

string

The sort order for the list of payouts. enum: ["asc", "desc"]. default: "desc".

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

page_size

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

create_referrals_embed_token

dub-cli create-referrals-embed-token

Create a referrals embed token for the given partner/tenant. The endpoint first attempts to locate an existing enrollment using the provided tenantId. If no enrollment is found, it resolves the partner by email and creates a new enrollment as needed. This results in an upsert-style flow that guarantees a valid enrollment and returns a usable embed token.

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

string

Native field; use the reviewed provider reference.

tenantId

No; body/guard requirements still apply

string

Native field; use the reviewed provider reference.

partner

No; body/guard requirements still apply

object

Native field; use the reviewed provider reference.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

output_file

Yes

string

Required absolute new private file. Exclusive 0600 creation; never overwrites or echoes PNG/embed credentials. minLength: 1.

input.partner

Argument

Required

Type

Details

name

No; body/guard requirements still apply

['string', 'null']

The partner's full name. If undefined, the partner's email will be used in lieu of their name (e.g. john@acme.com) maxLength: 100.

email

Yes

string

The partner's email address. Partners will be able to claim their profile by signing up at partners.dub.co with this email. maxLength: 190. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". format: "email".

username

No; body/guard requirements still apply

['string', 'null']

The partner's unique username in your system (max 100 characters). This will be used to create a short link for the partner using your program's default domain. If not provided, Dub will try to generate a username from the partner's name or email. maxLength: 100.

image

No; body/guard requirements still apply

['string', 'null']

The partner's avatar image. If not provided, a default avatar will be used.

tenantId

No; body/guard requirements still apply

string

The partner's unique ID in your system. Useful for retrieving the partner's links and stats later on. If not provided, the partner will be created as a standalone partner.

groupId

No; body/guard requirements still apply

string

The group ID to add the partner to. If not provided, the partner will be added to the default group.

country

No; body/guard requirements still apply

['string', 'null']

The partner's country of residence. Must be passed as a 2-letter ISO 3166-1 country code. See https://d.to/geo for more information.

description

No; body/guard requirements still apply

['string', 'null']

A brief description of the partner and their background. Max 5,000 characters. maxLength: 5000.

linkProps

No; body/guard requirements still apply

object

Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.

input.partner.linkProps

Argument

Required

Type

Details

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

prefix

No; body/guard requirements still apply

string

Path prefix for each default referral link slug (e.g. /c/ → https://{domain}/c/{identity}). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. c/jane-a7f2).

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

input.partner.linkProps.tagIds

input.partner.linkProps.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.partner.linkProps.tagIds anyOf branch 2

input.partner.linkProps.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.partner.linkProps.tagNames

input.partner.linkProps.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.partner.linkProps.tagNames anyOf branch 2

input.partner.linkProps.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.partner.linkProps.testVariants

input.partner.linkProps.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.payload

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

string

Native field; use the reviewed provider reference.

tenantId

No; body/guard requirements still apply

string

Native field; use the reviewed provider reference.

partner

No; body/guard requirements still apply

object

Native field; use the reviewed provider reference.

input.payload.partner

Argument

Required

Type

Details

name

No; body/guard requirements still apply

['string', 'null']

The partner's full name. If undefined, the partner's email will be used in lieu of their name (e.g. john@acme.com) maxLength: 100.

email

Yes

string

The partner's email address. Partners will be able to claim their profile by signing up at partners.dub.co with this email. maxLength: 190. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". format: "email".

username

No; body/guard requirements still apply

['string', 'null']

The partner's unique username in your system (max 100 characters). This will be used to create a short link for the partner using your program's default domain. If not provided, Dub will try to generate a username from the partner's name or email. maxLength: 100.

image

No; body/guard requirements still apply

['string', 'null']

The partner's avatar image. If not provided, a default avatar will be used.

tenantId

No; body/guard requirements still apply

string

The partner's unique ID in your system. Useful for retrieving the partner's links and stats later on. If not provided, the partner will be created as a standalone partner.

groupId

No; body/guard requirements still apply

string

The group ID to add the partner to. If not provided, the partner will be added to the default group.

country

No; body/guard requirements still apply

['string', 'null']

The partner's country of residence. Must be passed as a 2-letter ISO 3166-1 country code. See https://d.to/geo for more information.

description

No; body/guard requirements still apply

['string', 'null']

A brief description of the partner and their background. Max 5,000 characters. maxLength: 5000.

linkProps

No; body/guard requirements still apply

object

Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.

input.payload.partner.linkProps

Argument

Required

Type

Details

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

prefix

No; body/guard requirements still apply

string

Path prefix for each default referral link slug (e.g. /c/ → https://{domain}/c/{identity}). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. c/jane-a7f2).

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

input.payload.partner.linkProps.tagIds

input.payload.partner.linkProps.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.partner.linkProps.tagIds anyOf branch 2

input.payload.partner.linkProps.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.partner.linkProps.tagNames

input.payload.partner.linkProps.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.payload.partner.linkProps.tagNames anyOf branch 2

input.payload.partner.linkProps.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.payload.partner.linkProps.testVariants

input.payload.partner.linkProps.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

get_qr_code

dub-cli get-qr-code

Retrieve a QR code for a link.

Argument

Required

Type

Details

url

Yes

string

The URL to generate a QR code for. maxLength: 32000.

logo

No; body/guard requirements still apply

string

The logo to include in the QR code. Can only be used with a paid plan on Dub.

size

No; body/guard requirements still apply

number

The size of the QR code in pixels. Defaults to 600 if not provided. default: 600.

level

No; body/guard requirements still apply

string

The level of error correction to use for the QR code. Defaults to L if not provided. enum: ["L", "M", "Q", "H"]. default: "L".

fg_color

No; body/guard requirements still apply

string

The foreground color of the QR code in hex format. Defaults to #000000 if not provided. default: "#000000".

bg_color

No; body/guard requirements still apply

string

The background color of the QR code in hex format. Defaults to #ffffff if not provided. default: "#FFFFFF".

hide_logo

No; body/guard requirements still apply

boolean

Whether to hide the logo in the QR code. Can only be used with a paid plan on Dub. default: false.

margin

No; body/guard requirements still apply

number

The size of the margin around the QR code. Defaults to 2 if not provided. default: 2.

include_margin

No; body/guard requirements still apply

boolean

DEPRECATED: Margin is included by default. Use the margin prop to customize the margin size. default: true. Deprecated native compatibility field.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

output_file

Yes

string

Required absolute new private file. Exclusive 0600 creation; never overwrites or echoes PNG/embed credentials. minLength: 1.

list_bounty_submissions

dub-cli list-bounty-submissions

List all submissions for a specific bounty in your partner program.

Argument

Required

Type

Details

bounty_id

Yes

string

The unique ID of the bounty on Dub. Can be found in the URL of the bounty page, prefixed with bnty_.

status

No; body/guard requirements still apply

string

The status of the submissions to list. enum: ["draft", "submitted", "approved", "rejected"].

group_id

No; body/guard requirements still apply

string

The ID of the group to list submissions for.

partner_id

No; body/guard requirements still apply

string

The ID of the partner to list submissions for.

sort_by

No; body/guard requirements still apply

string

The field to sort the submissions by. enum: ["completedAt", "performanceCount", "socialMetricCount"]. default: "completedAt".

sort_order

No; body/guard requirements still apply

string

The order to sort the submissions by. enum: ["asc", "desc"]. default: "asc".

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

page_size

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

approve_bounty_submission

dub-cli approve-bounty-submission

Approve a bounty submission. Optionally specify a custom reward amount.

Argument

Required

Type

Details

bounty_id

Yes

string

The ID of the bounty

submission_id

Yes

string

The ID of the bounty submission

rewardAmount

No; body/guard requirements still apply

['number', 'null']

The reward amount for the performance-based bounty. Applicable if the bounty reward amount is not set.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

rewardAmount

No; body/guard requirements still apply

['number', 'null']

The reward amount for the performance-based bounty. Applicable if the bounty reward amount is not set.

reject_bounty_submission

dub-cli reject-bounty-submission

Reject a bounty submission with a specified reason and optional note.

Argument

Required

Type

Details

bounty_id

Yes

string

The ID of the bounty

submission_id

Yes

string

The ID of the bounty submission

rejectionReason

No; body/guard requirements still apply

string

The reason for rejecting the submission. enum: ["invalidProof", "duplicateSubmission", "outOfTimeWindow", "didNotMeetCriteria", "other"].

rejectionNote

No; body/guard requirements still apply

string

The note for rejecting the submission. maxLength: 5000.

account

No; body/guard requirements still apply

string

Exact configured private workspace profile label; not a tenant or provider account ID.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

payload

No; body/guard requirements still apply

object

Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file.

payload_file

No; body/guard requirements still apply

string

Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1.

input.payload

Argument

Required

Type

Details

rejectionReason

No; body/guard requirements still apply

string

The reason for rejecting the submission. enum: ["invalidProof", "duplicateSubmission", "outOfTimeWindow", "didNotMeetCriteria", "other"].

rejectionNote

No; body/guard requirements still apply

string

The note for rejecting the submission. maxLength: 5000.

list_accounts

dub-cli list-accounts

Local profile labels/default/auth method only. No keys, token paths, provider identity or network request.

Native JSON value; inspect the full schema for validation.

get_operation_schema

dub-cli get-operation-schema

Local reviewed method/path/query/body schema and provenance for one native tool. No credentials or provider request.

Argument

Required

Type

Details

operation

Yes

string

Exact native tool name, e.g. create_link or approve_program_application. enum: ["create_link", "list_links", "get_links_count", "get_link", "update_link", "delete_link", "bulk_create_links", "bulk_update_links", "bulk_delete_links", "upsert_link", "get_link_stats", "list_events", "create_tag", "list_tags", "update_tag", "delete_tag", "create_folder", "list_folders", "update_folder", "delete_folder", "create_domain", "list_domains", "update_domain", "delete_domain", "register_domain", "check_domain_status", "track_lead", "track_sale", "track_open", "list_customers", "get_customer", "update_customer", "delete_customer", "create_partner", "list_partners", "create_partner_link", "retrieve_partner_links", "upsert_partner_link", "retrieve_partner_analytics", "ban_partner", "deactivate_partner", "list_program_applications", "approve_program_application", "reject_program_application", "list_discount_codes", "create_discount_code", "delete_discount_code", "create_commission", "list_commissions", "update_commission", "bulk_update_commissions", "list_payouts", "create_referrals_embed_token", "get_qr_code", "list_bounty_submissions", "approve_bounty_submission", "reject_bounty_submission"].

dub-cli preview-link-batch

Local validation and SHA-256 of exact ordered link/tag/folder work, selected profile label and reviewed schema. No provider reads, key load, identity check, price or rollback guarantee.

Argument

Required

Type

Details

tasks

Yes

array

One to twenty ordered link/tag/folder operations. CLI repeats --tasks with individual JSON objects; native bulk work still counts all affected records. minItems: 1. maxItems: 20.

account

No; body/guard requirements still apply

string

Exact selected private workspace profile; binds label, not key ownership.

input.tasks

input.tasks[]

Argument

Required

Type

Details

tool

Yes

string

Native field; use the reviewed provider reference. enum: ["create_link", "update_link", "delete_link", "bulk_create_links", "bulk_update_links", "bulk_delete_links", "upsert_link", "create_tag", "update_tag", "delete_tag", "create_folder", "update_folder", "delete_folder"].

arguments

Yes

object

Native tool arguments only; no account, confirm or payload_file. Use inline complete payload/native fields.

dub-cli submit-link-batch

Confirmed one-to-twenty ordered link/tag/folder tasks. Prevalidate all and verify exact hash before first request. Stop on first failure with known results/failed index/unattempted indices; no retries, rollback or implicit continuation.

Argument

Required

Type

Details

tasks

Yes

array

One to twenty ordered link/tag/folder operations. CLI repeats --tasks with individual JSON objects; native bulk work still counts all affected records. minItems: 1. maxItems: 20.

account

No; body/guard requirements still apply

string

Exact selected private workspace profile; binds label, not key ownership.

confirm

No; body/guard requirements still apply

boolean

Set true only when the user asked for exactly this action.

review_sha256

Yes

string

Exact preview_link_batch hash for identical requests, profile label, schema and order. pattern: "^[a-f0-9]{64}$".

input.tasks

input.tasks[]

Argument

Required

Type

Details

tool

Yes

string

Native field; use the reviewed provider reference. enum: ["create_link", "update_link", "delete_link", "bulk_create_links", "bulk_update_links", "bulk_delete_links", "upsert_link", "create_tag", "update_tag", "delete_tag", "create_folder", "update_folder", "delete_folder"].

arguments

Yes

object

Native tool arguments only; no account, confirm or payload_file. Use inline complete payload/native fields.

Native request contracts

The reviewed snapshot contains every current native route. Query/path flags map back to their native names below; body JSON retains native keys. Body requirements apply to either body flags or payload/file. Response union/plan/provider rules are not overridden by local schema acceptance.

POST /links

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

url

Yes

string

The destination URL of the short link. maxLength: 32000.

domain

No; body/guard requirements still apply

string

The domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains). maxLength: 190.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

keyLength

No; body/guard requirements still apply

number

The length of the short link slug. Defaults to 7 if not provided. When used with prefix, the total length of the key will be prefix.length + keyLength. minimum: 3. maximum: 190.

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

programId

No; body/guard requirements still apply

['string', 'null']

The ID of the program the short link is associated with.

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner the short link is associated with.

prefix

No; body/guard requirements still apply

string

The prefix of the short link slug for randomly-generated keys (e.g. if prefix is /c/, generated keys will be in the /c/:key format). Will be ignored if key is provided.

trackConversion

No; body/guard requirements still apply

boolean

Whether to track conversions for the short link. Defaults to false if not provided.

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

['string', 'null']

The unique ID existing folder to assign the short link to.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

geo

No; body/guard requirements still apply

['object', 'null']

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

No; body/guard requirements still apply

['string', 'null']

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL. maxLength: 255.

utm_medium

No; body/guard requirements still apply

['string', 'null']

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL. maxLength: 255.

utm_campaign

No; body/guard requirements still apply

['string', 'null']

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL. maxLength: 255.

utm_term

No; body/guard requirements still apply

['string', 'null']

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL. maxLength: 255.

utm_content

No; body/guard requirements still apply

['string', 'null']

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL. maxLength: 255.

ref

No; body/guard requirements still apply

['string', 'null']

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL. maxLength: 255.

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

publicStats

No; body/guard requirements still apply

boolean

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided. Deprecated native compatibility field.

tagId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link. Deprecated native compatibility field.

webhookIds

No; body/guard requirements still apply

['array', 'null']

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data. Deprecated native compatibility field.

input.tagIds

input.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagIds anyOf branch 2

input.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.tagNames

input.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagNames anyOf branch 2

input.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.testVariants

input.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.webhookIds

input.webhookIds[]

Native JSON value; inspect the full schema for validation.

GET /links

Argument

Required

Type

Details

domain

No; body/guard requirements still apply

string

The domain to filter the links by. E.g. ac.me. If not provided, all links for the workspace will be returned.

tagId

No; body/guard requirements still apply

string

Deprecated: Use tagIds instead. The tag ID to filter the links by. Deprecated native compatibility field.

tagIds

No; body/guard requirements still apply

JSON

The tag IDs to filter the links by.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

string

The folder ID to filter the links by.

search

No; body/guard requirements still apply

string

The search term to filter the links by. The search term will be matched against the short link slug and the destination url.

userId

No; body/guard requirements still apply

string

The user ID to filter the links by.

tenantId

No; body/guard requirements still apply

string

The ID of the tenant that created the link inside your system. If set, will only return links for the specified tenant.

showArchived

No; body/guard requirements still apply

boolean

Whether to include archived links in the response. Defaults to false if not provided. default: false.

withTags

No; body/guard requirements still apply

boolean

DEPRECATED. Filter for links that have at least one tag assigned to them. default: false. Deprecated native compatibility field.

endingBefore

No; body/guard requirements still apply

string

If specified, the query only searches for results before this cursor. Mutually exclusive with startingAfter.

startingAfter

No; body/guard requirements still apply

string

If specified, the query only searches for results after this cursor. Mutually exclusive with endingBefore.

page

No; body/guard requirements still apply

integer

DEPRECATED. Use startingAfter instead. maximum: 9007199254740991. exclusiveMinimum: 0. Deprecated native compatibility field.

pageSize

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

input.tagIds

input.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagIds anyOf branch 2

input.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.tagNames

input.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagNames anyOf branch 2

input.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

No native JSON request body.

GET /links/count

Argument

Required

Type

Details

domain

No; body/guard requirements still apply

string

The domain to filter the links by. E.g. ac.me. If not provided, all links for the workspace will be returned.

tagId

No; body/guard requirements still apply

string

Deprecated: Use tagIds instead. The tag ID to filter the links by. Deprecated native compatibility field.

tagIds

No; body/guard requirements still apply

JSON

The tag IDs to filter the links by.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

string

The folder ID to filter the links by.

search

No; body/guard requirements still apply

string

The search term to filter the links by. The search term will be matched against the short link slug and the destination url.

userId

No; body/guard requirements still apply

string

The user ID to filter the links by.

tenantId

No; body/guard requirements still apply

string

The ID of the tenant that created the link inside your system. If set, will only return links for the specified tenant.

showArchived

No; body/guard requirements still apply

boolean

Whether to include archived links in the response. Defaults to false if not provided. default: false.

withTags

No; body/guard requirements still apply

boolean

DEPRECATED. Filter for links that have at least one tag assigned to them. default: false. Deprecated native compatibility field.

groupBy

No; body/guard requirements still apply

JSON

The field to group the links by.

input.tagIds

input.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagIds anyOf branch 2

input.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.tagNames

input.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagNames anyOf branch 2

input.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.groupBy

input.groupBy anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.groupBy anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.groupBy anyOf branch 3

Native JSON value; inspect the full schema for validation.

input.groupBy anyOf branch 4

Native JSON value; inspect the full schema for validation.

No native JSON request body.

GET /links/info

Argument

Required

Type

Details

domain

No; body/guard requirements still apply

string

The domain of the link to retrieve. E.g. for d.to/github, the domain is d.to. minLength: 1.

key

No; body/guard requirements still apply

string

The key of the link to retrieve. E.g. for d.to/github, the key is github. minLength: 1.

linkId

No; body/guard requirements still apply

string

The unique ID of the short link.

externalId

No; body/guard requirements still apply

string

This is the ID of the link in the your database.

No native JSON request body.

PATCH /links/{linkId}

Argument

Required

Type

Details

linkId

Yes

string

The id of the link to update. You may use either linkId (obtained via /links/info endpoint) or externalId prefixed with ext_.

Argument

Required

Type

Details

url

No; body/guard requirements still apply

string

The destination URL of the short link. maxLength: 32000.

domain

No; body/guard requirements still apply

string

The domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains). maxLength: 190.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

programId

No; body/guard requirements still apply

['string', 'null']

The ID of the program the short link is associated with.

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner the short link is associated with.

trackConversion

No; body/guard requirements still apply

boolean

Whether to track conversions for the short link. Defaults to false if not provided.

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

['string', 'null']

The unique ID existing folder to assign the short link to.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

JSON

Native field; use the reviewed provider reference.

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

geo

No; body/guard requirements still apply

JSON

Native field; use the reviewed provider reference.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

No; body/guard requirements still apply

['string', 'null']

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL. maxLength: 255.

utm_medium

No; body/guard requirements still apply

['string', 'null']

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL. maxLength: 255.

utm_campaign

No; body/guard requirements still apply

['string', 'null']

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL. maxLength: 255.

utm_term

No; body/guard requirements still apply

['string', 'null']

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL. maxLength: 255.

utm_content

No; body/guard requirements still apply

['string', 'null']

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL. maxLength: 255.

ref

No; body/guard requirements still apply

['string', 'null']

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL. maxLength: 255.

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

publicStats

No; body/guard requirements still apply

boolean

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided. Deprecated native compatibility field.

tagId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link. Deprecated native compatibility field.

webhookIds

No; body/guard requirements still apply

['array', 'null']

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data. Deprecated native compatibility field.

input.tagIds

input.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagIds anyOf branch 2

input.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.tagNames

input.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagNames anyOf branch 2

input.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.image

input.image anyOf branch 1

input.image.anyOf1 anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.image.anyOf1 anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.image anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.geo

input.geo allOf branch 1

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

input.testVariants

input.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.webhookIds

input.webhookIds[]

Native JSON value; inspect the full schema for validation.

DELETE /links/{linkId}

Argument

Required

Type

Details

linkId

Yes

string

The id of the link to delete. You may use either linkId (obtained via /links/info endpoint) or externalId prefixed with ext_.

No native JSON request body.

POST /links/bulk

Native JSON value; inspect the full schema for validation.

input[]

Argument

Required

Type

Details

url

Yes

string

The destination URL of the short link. maxLength: 32000.

domain

No; body/guard requirements still apply

string

The domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains). maxLength: 190.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

keyLength

No; body/guard requirements still apply

number

The length of the short link slug. Defaults to 7 if not provided. When used with prefix, the total length of the key will be prefix.length + keyLength. minimum: 3. maximum: 190.

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

programId

No; body/guard requirements still apply

['string', 'null']

The ID of the program the short link is associated with.

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner the short link is associated with.

prefix

No; body/guard requirements still apply

string

The prefix of the short link slug for randomly-generated keys (e.g. if prefix is /c/, generated keys will be in the /c/:key format). Will be ignored if key is provided.

trackConversion

No; body/guard requirements still apply

boolean

Whether to track conversions for the short link. Defaults to false if not provided.

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

['string', 'null']

The unique ID existing folder to assign the short link to.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

geo

No; body/guard requirements still apply

['object', 'null']

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

No; body/guard requirements still apply

['string', 'null']

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL. maxLength: 255.

utm_medium

No; body/guard requirements still apply

['string', 'null']

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL. maxLength: 255.

utm_campaign

No; body/guard requirements still apply

['string', 'null']

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL. maxLength: 255.

utm_term

No; body/guard requirements still apply

['string', 'null']

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL. maxLength: 255.

utm_content

No; body/guard requirements still apply

['string', 'null']

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL. maxLength: 255.

ref

No; body/guard requirements still apply

['string', 'null']

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL. maxLength: 255.

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

publicStats

No; body/guard requirements still apply

boolean

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided. Deprecated native compatibility field.

tagId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link. Deprecated native compatibility field.

webhookIds

No; body/guard requirements still apply

['array', 'null']

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data. Deprecated native compatibility field.

input[].tagIds

input[].tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input[].tagIds anyOf branch 2

input[].tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input[].tagNames

input[].tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input[].tagNames anyOf branch 2

input[].tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input[].testVariants

input[].testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input[].webhookIds

input[].webhookIds[]

Native JSON value; inspect the full schema for validation.

PATCH /links/bulk

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

linkIds

No; body/guard requirements still apply

array

The IDs of the links to update. Takes precedence over externalIds. maxItems: 100. default: [].

externalIds

No; body/guard requirements still apply

array

The external IDs of the links to update as stored in your database. maxItems: 100. default: [].

data

Yes

object

Native field; use the reviewed provider reference.

input.linkIds

input.linkIds[]

Native JSON value; inspect the full schema for validation.

input.externalIds

input.externalIds[]

Native JSON value; inspect the full schema for validation.

input.data

Argument

Required

Type

Details

url

No; body/guard requirements still apply

string

The destination URL of the short link. maxLength: 32000.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

programId

No; body/guard requirements still apply

['string', 'null']

The ID of the program the short link is associated with.

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner the short link is associated with.

trackConversion

No; body/guard requirements still apply

boolean

Whether to track conversions for the short link. Defaults to false if not provided.

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

['string', 'null']

The unique ID existing folder to assign the short link to.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

geo

No; body/guard requirements still apply

['object', 'null']

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

No; body/guard requirements still apply

['string', 'null']

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL. maxLength: 255.

utm_medium

No; body/guard requirements still apply

['string', 'null']

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL. maxLength: 255.

utm_campaign

No; body/guard requirements still apply

['string', 'null']

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL. maxLength: 255.

utm_term

No; body/guard requirements still apply

['string', 'null']

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL. maxLength: 255.

utm_content

No; body/guard requirements still apply

['string', 'null']

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL. maxLength: 255.

ref

No; body/guard requirements still apply

['string', 'null']

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL. maxLength: 255.

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

publicStats

No; body/guard requirements still apply

boolean

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided. Deprecated native compatibility field.

tagId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link. Deprecated native compatibility field.

webhookIds

No; body/guard requirements still apply

['array', 'null']

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data. Deprecated native compatibility field.

input.data.tagIds

input.data.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.data.tagIds anyOf branch 2

input.data.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.data.tagNames

input.data.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.data.tagNames anyOf branch 2

input.data.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.data.testVariants

input.data.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.data.webhookIds

input.data.webhookIds[]

Native JSON value; inspect the full schema for validation.

DELETE /links/bulk

Argument

Required

Type

Details

linkIds

Yes

array

Comma-separated list of link IDs to delete. Maximum of 100 IDs. Non-existing IDs will be ignored.

input.linkIds

input.linkIds[]

Native JSON value; inspect the full schema for validation.

No native JSON request body.

PUT /links/upsert

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

url

Yes

string

The destination URL of the short link. maxLength: 32000.

domain

No; body/guard requirements still apply

string

The domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains). maxLength: 190.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

keyLength

No; body/guard requirements still apply

number

The length of the short link slug. Defaults to 7 if not provided. When used with prefix, the total length of the key will be prefix.length + keyLength. minimum: 3. maximum: 190.

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

programId

No; body/guard requirements still apply

['string', 'null']

The ID of the program the short link is associated with.

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner the short link is associated with.

prefix

No; body/guard requirements still apply

string

The prefix of the short link slug for randomly-generated keys (e.g. if prefix is /c/, generated keys will be in the /c/:key format). Will be ignored if key is provided.

trackConversion

No; body/guard requirements still apply

boolean

Whether to track conversions for the short link. Defaults to false if not provided.

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

folderId

No; body/guard requirements still apply

['string', 'null']

The unique ID existing folder to assign the short link to.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

geo

No; body/guard requirements still apply

['object', 'null']

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source

No; body/guard requirements still apply

['string', 'null']

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL. maxLength: 255.

utm_medium

No; body/guard requirements still apply

['string', 'null']

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL. maxLength: 255.

utm_campaign

No; body/guard requirements still apply

['string', 'null']

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL. maxLength: 255.

utm_term

No; body/guard requirements still apply

['string', 'null']

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL. maxLength: 255.

utm_content

No; body/guard requirements still apply

['string', 'null']

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL. maxLength: 255.

ref

No; body/guard requirements still apply

['string', 'null']

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL. maxLength: 255.

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

publicStats

No; body/guard requirements still apply

boolean

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided. Deprecated native compatibility field.

tagId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link. Deprecated native compatibility field.

webhookIds

No; body/guard requirements still apply

['array', 'null']

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data. Deprecated native compatibility field.

input.tagIds

input.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagIds anyOf branch 2

input.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.tagNames

input.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.tagNames anyOf branch 2

input.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.testVariants

input.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

input.webhookIds

input.webhookIds[]

Native JSON value; inspect the full schema for validation.

retrieveAnalytics

GET /analytics

Argument

Required

Type

Details

event

No; body/guard requirements still apply

string

The type of event to retrieve analytics for. Defaults to clicks. enum: ["clicks", "leads", "sales", "composite"]. default: "clicks".

groupBy

No; body/guard requirements still apply

string

The parameter to group the analytics data points by. Defaults to count if undefined. enum: ["count", "timeseries", "continents", "regions", "countries", "cities", "devices", "browsers", "os", "trigger", "triggers", "event_names", "referers", "referer_urls", "top_folders", "top_link_tags", "top_domains", "top_links", "top_urls", "top_base_urls", "top_partners", "top_groups", "top_partner_tags", "utm_sources", "utm_mediums", "utm_campaigns", "utm_terms", "utm_contents"]. default: "count".

domain

No; body/guard requirements still apply

string

The domain to filter analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: dub.co, dub.co,google.com, -spam.com.

key

No; body/guard requirements still apply

string

The slug of the short link to retrieve analytics for. Must be used along with the corresponding domain of the short link to fetch analytics for a specific short link.

linkId

No; body/guard requirements still apply

string

The unique ID of the link to retrieve analytics for.Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: link_123, link_123,link_456, -link_789.

externalId

No; body/guard requirements still apply

string

The ID of the link in the your database. Must be prefixed with 'ext_' when passed as a query parameter.

tenantId

No; body/guard requirements still apply

string

The ID of the tenant that created the link inside your system. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: tenant_123, tenant_123,tenant_456, -tenant_789.

tagId

No; body/guard requirements still apply

string

The tag ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: tag_123, tag_123,tag_456, -tag_789.

folderId

No; body/guard requirements still apply

string

The folder ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: folder_123, folder_123,folder_456, -folder_789. If not provided, return analytics for all links.

partnerTagId

No; body/guard requirements still apply

string

The partner tag ID(s) to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: ptag_123, ptag_123,ptag_456, -ptag_789.

groupId

No; body/guard requirements still apply

string

The group ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: grp_123, grp_123,grp_456, -grp_789.

partnerId

No; body/guard requirements still apply

string

The ID of the partner to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: pn_123, pn_123,pn_456, -pn_789.

customerId

No; body/guard requirements still apply

string

The ID of the customer to retrieve analytics for.

interval

No; body/guard requirements still apply

string

The interval to retrieve analytics for. If undefined, defaults to 24h. enum: ["24h", "7d", "30d", "90d", "1y", "mtd", "qtd", "ytd", "all"].

start

No; body/guard requirements still apply

string

The start date and time when to retrieve analytics from. If set, takes precedence over interval.

end

No; body/guard requirements still apply

string

The end date and time when to retrieve analytics from. If not provided, defaults to the current date. If set along with start, takes precedence over interval.

timezone

No; body/guard requirements still apply

string

The IANA time zone code for aligning timeseries granularity (e.g. America/New_York). Defaults to UTC. default: "UTC".

country

No; body/guard requirements still apply

string

The country to retrieve analytics for. Must be passed as a 2-letter ISO 3166-1 country code (see https://d.to/geo). Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: US, US,BR,FR, -US.

city

No; body/guard requirements still apply

string

The city to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: New York, New York,London, -New York.

region

No; body/guard requirements still apply

string

The ISO 3166-2 region code to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: NY, NY,CA, -NY.

continent

No; body/guard requirements still apply

string

The continent to retrieve analytics for. Valid values: AF, AN, AS, EU, NA, OC, SA. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: NA, NA,EU, -AS.

device

No; body/guard requirements still apply

string

The device to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Desktop, Mobile,Tablet, -Mobile.

browser

No; body/guard requirements still apply

string

The browser to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Chrome, Chrome,Firefox,Safari, -IE.

os

No; body/guard requirements still apply

string

The OS to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Windows, Mac,Windows,Linux, -Windows.

trigger

No; body/guard requirements still apply

string

The trigger to retrieve analytics for. Valid values: qr, link, pageview. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: qr, qr,link, -qr. If undefined, returns all trigger types.

eventName

No; body/guard requirements still apply

string

The conversion event name to retrieve analytics for. Only available for lead and sale events. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Sign up, Sign up,Purchase, -Sign up.

referer

No; body/guard requirements still apply

string

The referer hostname to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: google.com, google.com,twitter.com, -facebook.com.

refererUrl

No; body/guard requirements still apply

string

The full referer URL to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: https://google.com, https://google.com,https://twitter.com, -https://spam.com.

url

No; body/guard requirements still apply

string

The destination URL to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: https://example.com, https://example.com,https://other.com, -https://spam.com.

utm_source

No; body/guard requirements still apply

string

The UTM source to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: google, google,twitter, -spam.

utm_medium

No; body/guard requirements still apply

string

The UTM medium to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: cpc, cpc,social, -email.

utm_campaign

No; body/guard requirements still apply

string

The UTM campaign to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: summer_sale, summer_sale,winter_sale, -old_campaign.

utm_term

No; body/guard requirements still apply

string

The UTM term to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

utm_content

No; body/guard requirements still apply

string

The UTM content to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

root

No; body/guard requirements still apply

boolean

Filter for root domains. If true, filter for domains only. If false, filter for links only. If undefined, return both.

saleType

No; body/guard requirements still apply

string

Filter sales by type: 'new' for first-time purchases, 'recurring' for repeat purchases. If undefined, returns both. enum: ["new", "recurring"].

query

No; body/guard requirements still apply

string

Search the events by a custom metadata value. Only available for lead and sale events. Examples: metadata['key']:'value' maxLength: 10000.

programId

No; body/guard requirements still apply

string

Deprecated: This is automatically inferred from your workspace's defaultProgramId. The ID of the program to retrieve analytics for. Deprecated native compatibility field.

tagIds

No; body/guard requirements still apply

string

Deprecated: Use tagId instead. The tag IDs to retrieve analytics for. Deprecated native compatibility field.

qr

No; body/guard requirements still apply

boolean

Deprecated: Use the trigger field instead. Filter for QR code scans. If true, filter for QR codes only. If false, filter for links only. If undefined, return both. Deprecated native compatibility field.

No native JSON request body.

listEvents

GET /events

Argument

Required

Type

Details

event

No; body/guard requirements still apply

string

The type of event to retrieve analytics for. Defaults to 'clicks'. enum: ["clicks", "leads", "sales"]. default: "clicks".

domain

No; body/guard requirements still apply

string

The domain to filter analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: dub.co, dub.co,google.com, -spam.com.

key

No; body/guard requirements still apply

string

The slug of the short link to retrieve analytics for. Must be used along with the corresponding domain of the short link to fetch analytics for a specific short link.

linkId

No; body/guard requirements still apply

string

The unique ID of the link to retrieve analytics for.Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: link_123, link_123,link_456, -link_789.

externalId

No; body/guard requirements still apply

string

The ID of the link in the your database. Must be prefixed with 'ext_' when passed as a query parameter.

tenantId

No; body/guard requirements still apply

string

The ID of the tenant that created the link inside your system. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: tenant_123, tenant_123,tenant_456, -tenant_789.

tagId

No; body/guard requirements still apply

string

The tag ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: tag_123, tag_123,tag_456, -tag_789.

folderId

No; body/guard requirements still apply

string

The folder ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: folder_123, folder_123,folder_456, -folder_789. If not provided, return analytics for all links.

partnerTagId

No; body/guard requirements still apply

string

The partner tag ID(s) to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: ptag_123, ptag_123,ptag_456, -ptag_789.

groupId

No; body/guard requirements still apply

string

The group ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: grp_123, grp_123,grp_456, -grp_789.

partnerId

No; body/guard requirements still apply

string

The ID of the partner to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: pn_123, pn_123,pn_456, -pn_789.

customerId

No; body/guard requirements still apply

string

The ID of the customer to retrieve analytics for.

interval

No; body/guard requirements still apply

string

The interval to retrieve analytics for. If undefined, defaults to 24h. enum: ["24h", "7d", "30d", "90d", "1y", "mtd", "qtd", "ytd", "all"].

start

No; body/guard requirements still apply

string

The start date and time when to retrieve analytics from. If set, takes precedence over interval.

end

No; body/guard requirements still apply

string

The end date and time when to retrieve analytics from. If not provided, defaults to the current date. If set along with start, takes precedence over interval.

timezone

No; body/guard requirements still apply

string

The IANA time zone code for aligning timeseries granularity (e.g. America/New_York). Defaults to UTC. default: "UTC".

country

No; body/guard requirements still apply

string

The country to retrieve analytics for. Must be passed as a 2-letter ISO 3166-1 country code (see https://d.to/geo). Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: US, US,BR,FR, -US.

city

No; body/guard requirements still apply

string

The city to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: New York, New York,London, -New York.

region

No; body/guard requirements still apply

string

The ISO 3166-2 region code to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: NY, NY,CA, -NY.

continent

No; body/guard requirements still apply

string

The continent to retrieve analytics for. Valid values: AF, AN, AS, EU, NA, OC, SA. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: NA, NA,EU, -AS.

device

No; body/guard requirements still apply

string

The device to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Desktop, Mobile,Tablet, -Mobile.

browser

No; body/guard requirements still apply

string

The browser to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Chrome, Chrome,Firefox,Safari, -IE.

os

No; body/guard requirements still apply

string

The OS to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Windows, Mac,Windows,Linux, -Windows.

trigger

No; body/guard requirements still apply

string

The trigger to retrieve analytics for. Valid values: qr, link, pageview. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: qr, qr,link, -qr. If undefined, returns all trigger types.

eventName

No; body/guard requirements still apply

string

The conversion event name to retrieve analytics for. Only available for lead and sale events. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Sign up, Sign up,Purchase, -Sign up.

referer

No; body/guard requirements still apply

string

The referer hostname to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: google.com, google.com,twitter.com, -facebook.com.

refererUrl

No; body/guard requirements still apply

string

The full referer URL to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: https://google.com, https://google.com,https://twitter.com, -https://spam.com.

url

No; body/guard requirements still apply

string

The destination URL to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: https://example.com, https://example.com,https://other.com, -https://spam.com.

utm_source

No; body/guard requirements still apply

string

The UTM source to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: google, google,twitter, -spam.

utm_medium

No; body/guard requirements still apply

string

The UTM medium to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: cpc, cpc,social, -email.

utm_campaign

No; body/guard requirements still apply

string

The UTM campaign to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: summer_sale, summer_sale,winter_sale, -old_campaign.

utm_term

No; body/guard requirements still apply

string

The UTM term to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

utm_content

No; body/guard requirements still apply

string

The UTM content to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

root

No; body/guard requirements still apply

boolean

Filter for root domains. If true, filter for domains only. If false, filter for links only. If undefined, return both.

saleType

No; body/guard requirements still apply

string

Filter sales by type: 'new' for first-time purchases, 'recurring' for repeat purchases. If undefined, returns both. enum: ["new", "recurring"].

query

No; body/guard requirements still apply

string

Search the events by a custom metadata value. Only available for lead and sale events. Examples: metadata['key']:'value' maxLength: 10000.

programId

No; body/guard requirements still apply

string

Deprecated: This is automatically inferred from your workspace's defaultProgramId. The ID of the program to retrieve analytics for. Deprecated native compatibility field.

tagIds

No; body/guard requirements still apply

string

Deprecated: Use tagId instead. The tag IDs to retrieve analytics for. Deprecated native compatibility field.

qr

No; body/guard requirements still apply

boolean

Deprecated: Use the trigger field instead. Filter for QR code scans. If true, filter for QR codes only. If false, filter for links only. If undefined, return both. Deprecated native compatibility field.

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0. default: 1.

limit

No; body/guard requirements still apply

integer

The number of items per page. maximum: 1000. exclusiveMinimum: 0. default: 100.

sortOrder

No; body/guard requirements still apply

string

The sort order. The default is desc. enum: ["asc", "desc"]. default: "desc".

sortBy

No; body/guard requirements still apply

string

The field to sort the events by. The default is timestamp. enum: ["timestamp"]. default: "timestamp".

order

No; body/guard requirements still apply

string

DEPRECATED. Use sortOrder instead. enum: ["asc", "desc"]. default: "desc". Deprecated native compatibility field.

No native JSON request body.

createTag

POST /tags

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

name

No; body/guard requirements still apply

string

The name of the tag to create. minLength: 1. maxLength: 190.

color

No; body/guard requirements still apply

string

The color of the tag. If not provided, a random color will be used from the list: red, yellow, green, blue, purple, brown, gray. enum: ["red", "yellow", "green", "blue", "purple", "brown", "gray", "pink"].

tag

No; body/guard requirements still apply

string

The name of the tag to create. minLength: 1. maxLength: 190. Deprecated native compatibility field.

getTags

GET /tags

Argument

Required

Type

Details

sortBy

No; body/guard requirements still apply

string

The field to sort the tags by. enum: ["name", "createdAt"]. default: "name".

sortOrder

No; body/guard requirements still apply

string

The order to sort the tags by. enum: ["asc", "desc"]. default: "asc".

search

No; body/guard requirements still apply

string

The search term to filter the tags by.

ids

No; body/guard requirements still apply

JSON

IDs of tags to filter by.

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

pageSize

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

input.ids

input.ids anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.ids anyOf branch 2

input.ids.anyOf2[]

Native JSON value; inspect the full schema for validation.

No native JSON request body.

updateTag

PATCH /tags/{id}

Argument

Required

Type

Details

id

Yes

string

The ID of the tag to update.

Argument

Required

Type

Details

name

No; body/guard requirements still apply

string

The name of the tag to create. minLength: 1. maxLength: 190.

color

No; body/guard requirements still apply

string

The color of the tag. If not provided, a random color will be used from the list: red, yellow, green, blue, purple, brown, gray. enum: ["red", "yellow", "green", "blue", "purple", "brown", "gray", "pink"].

tag

No; body/guard requirements still apply

string

The name of the tag to create. minLength: 1. maxLength: 190. Deprecated native compatibility field.

deleteTag

DELETE /tags/{id}

Argument

Required

Type

Details

id

Yes

string

The ID of the tag to delete.

No native JSON request body.

createFolder

POST /folders

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

name

Yes

string

The name of the folder. maxLength: 190.

description

No; body/guard requirements still apply

['string', 'null']

The description of the folder. maxLength: 500.

accessLevel

No; body/guard requirements still apply

['string', 'null']

The workspace-level access level settings for the folder. Default is write which allows full access to the folder for all team members. The other options are read (view-only access) and null (no access) and are only available on Business plans and above. enum: ["write", "read", null]. default: "write".

listFolders

GET /folders

Argument

Required

Type

Details

search

No; body/guard requirements still apply

string

The search term to filter the folders by.

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

pageSize

No; body/guard requirements still apply

integer

The number of items per page. maximum: 50. exclusiveMinimum: 0. default: 50.

No native JSON request body.

updateFolder

PATCH /folders/{id}

Argument

Required

Type

Details

id

Yes

string

The ID of the folder to update.

Argument

Required

Type

Details

name

No; body/guard requirements still apply

string

The name of the folder. maxLength: 190.

description

No; body/guard requirements still apply

['string', 'null']

The description of the folder. maxLength: 500.

accessLevel

No; body/guard requirements still apply

['string', 'null']

The access level of the folder within the workspace. enum: ["write", "read", null].

deleteFolder

DELETE /folders/{id}

Argument

Required

Type

Details

id

Yes

string

The ID of the folder to delete.

No native JSON request body.

createDomain

POST /domains

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

slug

Yes

string

Name of the domain. minLength: 1. maxLength: 190.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

Redirect users to a specific URL when any link under this domain has expired. maxLength: 32000.

notFoundUrl

No; body/guard requirements still apply

['string', 'null']

Redirect users to a specific URL when a link under this domain doesn't exist. maxLength: 32000.

archived

No; body/guard requirements still apply

boolean

Whether to archive this domain. false will unarchive a previously archived domain. default: false.

placeholder

No; body/guard requirements still apply

['string', 'null']

Provide context to your teammates in the link creation modal by showing them an example of a link to be shortened. maxLength: 100.

logo

No; body/guard requirements still apply

JSON

Native field; use the reviewed provider reference.

assetLinks

No; body/guard requirements still apply

['string', 'null']

assetLinks.json configuration file (for deep link support on Android).

appleAppSiteAssociation

No; body/guard requirements still apply

['string', 'null']

apple-app-site-association configuration file (for deep link support on iOS).

input.logo

input.logo anyOf branch 1

input.logo.anyOf1 anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.logo.anyOf1 anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.logo.anyOf1 anyOf branch 3

Native JSON value; inspect the full schema for validation.

input.logo anyOf branch 2

Native JSON value; inspect the full schema for validation.

listDomains

GET /domains

Argument

Required

Type

Details

archived

No; body/guard requirements still apply

boolean

Whether to include archived domains in the response. Defaults to false if not provided. default: false.

search

No; body/guard requirements still apply

string

The search term to filter the domains by.

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

pageSize

No; body/guard requirements still apply

integer

The number of items per page. maximum: 50. exclusiveMinimum: 0. default: 50.

No native JSON request body.

updateDomain

PATCH /domains/{slug}

Argument

Required

Type

Details

slug

Yes

string

The domain name.

Argument

Required

Type

Details

slug

No; body/guard requirements still apply

string

Name of the domain. minLength: 1. maxLength: 190.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

Redirect users to a specific URL when any link under this domain has expired. maxLength: 32000.

notFoundUrl

No; body/guard requirements still apply

['string', 'null']

Redirect users to a specific URL when a link under this domain doesn't exist. maxLength: 32000.

archived

No; body/guard requirements still apply

boolean

Whether to archive this domain. false will unarchive a previously archived domain. default: false.

placeholder

No; body/guard requirements still apply

['string', 'null']

Provide context to your teammates in the link creation modal by showing them an example of a link to be shortened. maxLength: 100.

logo

No; body/guard requirements still apply

JSON

Native field; use the reviewed provider reference.

assetLinks

No; body/guard requirements still apply

['string', 'null']

assetLinks.json configuration file (for deep link support on Android).

appleAppSiteAssociation

No; body/guard requirements still apply

['string', 'null']

apple-app-site-association configuration file (for deep link support on iOS).

input.logo

input.logo anyOf branch 1

input.logo.anyOf1 anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.logo.anyOf1 anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.logo.anyOf1 anyOf branch 3

Native JSON value; inspect the full schema for validation.

input.logo anyOf branch 2

Native JSON value; inspect the full schema for validation.

deleteDomain

DELETE /domains/{slug}

Argument

Required

Type

Details

slug

Yes

string

The domain name.

No native JSON request body.

registerDomain

POST /domains/register

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

domain

Yes

string

The domain to claim. We only support .link domains for now. minLength: 1. pattern: ".*\\.link$".

checkDomainStatus

GET /domains/status

Argument

Required

Type

Details

domains

Yes

JSON

The domains to search. We only support .link domains for now.

input.domains

input.domains anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.domains anyOf branch 2

input.domains.anyOf2[]

Native JSON value; inspect the full schema for validation.

No native JSON request body.

trackLead

POST /track/lead

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

clickId

Yes

string

The unique ID of the click that the lead conversion event is attributed to. You can read this value from dub_id cookie. [For deferred lead tracking]: If an empty string is provided, Dub will try to find an existing customer with the provided customerExternalId and use the clickId from the customer if found.

eventName

Yes

string

The name of the lead event to track. Can also be used as a unique identifier to associate a given lead event for a customer for a subsequent sale event (via the leadEventName prop in /track/sale). minLength: 1. maxLength: 255.

customerExternalId

Yes

string

The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer. minLength: 1. maxLength: 100.

customerName

No; body/guard requirements still apply

['string', 'null']

The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”). maxLength: 100. default: null.

customerEmail

No; body/guard requirements still apply

['string', 'null']

The email address of the customer. maxLength: 100. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". default: null. format: "email".

customerAvatar

No; body/guard requirements still apply

['string', 'null']

The avatar URL of the customer. default: null.

mode

No; body/guard requirements still apply

string

The mode to use for tracking the lead event. async will not block the request; wait will block the request until the lead event is fully recorded in Dub; deferred will defer the lead event creation to a subsequent request. enum: ["async", "wait", "deferred"]. default: "async".

eventQuantity

No; body/guard requirements still apply

['integer', 'null']

The numerical value associated with this lead event (e.g., number of provisioned seats in a free trial). If defined as N, the lead event will be tracked N times. maximum: 100. exclusiveMinimum: 0.

metadata

No; body/guard requirements still apply

['object', 'null']

Additional metadata to be stored with the lead event. Max 10,000 characters. default: null.

trackSale

POST /track/sale

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

customerExternalId

Yes

string

The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer. minLength: 1. maxLength: 100.

amount

Yes

integer

The amount of the sale in cents (for all two-decimal currencies). If the sale is in a zero-decimal currency, pass the full integer value (e.g. 1580 JPY). Learn more: https://d.to/currency minimum: 0. maximum: 9007199254740991.

currency

No; body/guard requirements still apply

string

The currency of the sale. Accepts ISO 4217 currency codes. Sales will be automatically converted and stored as USD at the latest exchange rates. Learn more: https://d.to/currency default: "usd".

eventName

No; body/guard requirements still apply

string

The name of the sale event. Recommended format: Invoice paid or Subscription created. maxLength: 255. default: "Purchase".

paymentProcessor

No; body/guard requirements still apply

string

The payment processor via which the sale was made. enum: ["stripe", "shopify", "polar", "paddle", "apple", "revenuecat", "lemonsqueezy", "dub", "custom"]. default: "custom".

invoiceId

No; body/guard requirements still apply

['string', 'null']

The invoice ID of the sale. Can be used as a idempotency key – only one sale event can be recorded for a given invoice ID. default: null.

metadata

No; body/guard requirements still apply

['object', 'null']

Additional metadata to be stored with the sale event. Max 10,000 characters when stringified. default: null.

leadEventName

No; body/guard requirements still apply

['string', 'null']

The name of the lead event that occurred before the sale (case-sensitive). This is used to associate the sale event with a particular lead event (instead of the latest lead event for a link-customer combination, which is the default behavior). For direct sale tracking, this field can also be used to specify the lead event name. default: null.

clickId

No; body/guard requirements still apply

['string', 'null']

[For direct sale tracking]: The unique ID of the click that the sale conversion event is attributed to. You can read this value from dub_id cookie.

customerName

No; body/guard requirements still apply

['string', 'null']

[For direct sale tracking]: The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”). maxLength: 100. default: null.

customerEmail

No; body/guard requirements still apply

['string', 'null']

[For direct sale tracking]: The email address of the customer. maxLength: 100. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". default: null. format: "email".

customerAvatar

No; body/guard requirements still apply

['string', 'null']

[For direct sale tracking]: The avatar URL of the customer. default: null.

trackOpen

POST /track/open

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

deepLink

No; body/guard requirements still apply

string

The deep link that brought the user to the app. If left blank, Dub will fallback to probabilistic tracking by using the dubDomain parameter to check if there is an associated click event for the user's IP address. Learn more: https://d.to/ddl maxLength: 32000.

dubDomain

No; body/guard requirements still apply

string

Your deep link custom domain on Dub (e.g. acme.link). This is used in probabilistic tracking to check if there is an associated click event for the user's IP address. Learn more: https://d.to/ddl

getCustomers

GET /customers

Argument

Required

Type

Details

email

No; body/guard requirements still apply

string

A case-sensitive filter on the list based on the customer's email field. The value must be a string. Takes precedence over externalId.

externalId

No; body/guard requirements still apply

string

A case-sensitive filter on the list based on the customer's externalId field. The value must be a string. Takes precedence over search.

search

No; body/guard requirements still apply

string

A search query to filter customers by email, name, or customer ID (cus_...). If email or externalId is provided, this will be ignored.

country

No; body/guard requirements still apply

string

A filter on the list based on the customer's country field.

linkId

No; body/guard requirements still apply

string

A filter on the list based on the customer's linkId field (the referral link ID).

programId

No; body/guard requirements still apply

string

Program ID to filter by.

partnerId

No; body/guard requirements still apply

string

Partner ID to filter by.

includeExpandedFields

No; body/guard requirements still apply

boolean

Whether to include expanded fields on the customer (link, partner, discount).

sortBy

No; body/guard requirements still apply

string

The field to sort the customers by. The default is createdAt. enum: ["createdAt", "saleAmount", "firstSaleAt", "subscriptionCanceledAt"]. default: "createdAt".

sortOrder

No; body/guard requirements still apply

string

The sort order. The default is desc. enum: ["asc", "desc"]. default: "desc".

endingBefore

No; body/guard requirements still apply

string

If specified, the query only searches for results before this cursor. Mutually exclusive with startingAfter.

startingAfter

No; body/guard requirements still apply

string

If specified, the query only searches for results after this cursor. Mutually exclusive with endingBefore.

page

No; body/guard requirements still apply

integer

DEPRECATED. Use startingAfter instead. maximum: 9007199254740991. exclusiveMinimum: 0. Deprecated native compatibility field.

pageSize

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

No native JSON request body.

getCustomer

GET /customers/{id}

Argument

Required

Type

Details

id

Yes

string

The unique ID of the customer. You may use either the customer's id on Dub (obtained via /customers endpoint) or their externalId (unique ID within your system, prefixed with ext_, e.g. ext_123).

includeExpandedFields

No; body/guard requirements still apply

boolean

Whether to include expanded fields on the customer (link, partner, discount).

No native JSON request body.

updateCustomer

PATCH /customers/{id}

Argument

Required

Type

Details

id

Yes

string

The unique ID of the customer. You may use either the customer's id on Dub (obtained via /customers endpoint) or their externalId (unique ID within your system, prefixed with ext_, e.g. ext_123).

includeExpandedFields

No; body/guard requirements still apply

boolean

Whether to include expanded fields on the customer (link, partner, discount).

Argument

Required

Type

Details

email

No; body/guard requirements still apply

['string', 'null']

The customer's email address. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". format: "email".

name

No; body/guard requirements still apply

['string', 'null']

The customer's name. If not provided, the email address will be used, and if email is not provided, a random name will be generated.

avatar

No; body/guard requirements still apply

['string', 'null']

The customer's avatar URL. If not provided, a random avatar will be generated. format: "uri".

externalId

No; body/guard requirements still apply

string

The customer's unique identifier your database. This is useful for associating subsequent conversion events from Dub's API to your internal systems.

stripeCustomerId

No; body/guard requirements still apply

['string', 'null']

The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.

country

No; body/guard requirements still apply

string

The customer's country in ISO 3166-1 alpha-2 format. Updating this field will only affect the customer's country in Dub's system (and has no effect on existing conversion events).

subscriptionCanceledAt

No; body/guard requirements still apply

['string', 'null']

The date the customer canceled their subscription. Set to a timestamp to mark the subscription as canceled, or null to clear it (e.g. if they resubscribe).

deleteCustomer

DELETE /customers/{id}

Argument

Required

Type

Details

id

Yes

string

The unique ID of the customer. You may use either the customer's id on Dub (obtained via /customers endpoint) or their externalId (unique ID within your system, prefixed with ext_, e.g. ext_123).

No native JSON request body.

createPartner

POST /partners

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

name

No; body/guard requirements still apply

['string', 'null']

The partner's full name. If undefined, the partner's email will be used in lieu of their name (e.g. john@acme.com) maxLength: 100.

email

Yes

string

The partner's email address. Partners will be able to claim their profile by signing up at partners.dub.co with this email. maxLength: 190. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". format: "email".

username

No; body/guard requirements still apply

['string', 'null']

The partner's unique username in your system (max 100 characters). This will be used to create a short link for the partner using your program's default domain. If not provided, Dub will try to generate a username from the partner's name or email. maxLength: 100.

image

No; body/guard requirements still apply

['string', 'null']

The partner's avatar image. If not provided, a default avatar will be used.

tenantId

No; body/guard requirements still apply

string

The partner's unique ID in your system. Useful for retrieving the partner's links and stats later on. If not provided, the partner will be created as a standalone partner.

groupId

No; body/guard requirements still apply

string

The group ID to add the partner to. If not provided, the partner will be added to the default group.

country

No; body/guard requirements still apply

['string', 'null']

The partner's country of residence. Must be passed as a 2-letter ISO 3166-1 country code. See https://d.to/geo for more information.

description

No; body/guard requirements still apply

['string', 'null']

A brief description of the partner and their background. Max 5,000 characters. maxLength: 5000.

linkProps

No; body/guard requirements still apply

object

Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.

input.linkProps

Argument

Required

Type

Details

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

prefix

No; body/guard requirements still apply

string

Path prefix for each default referral link slug (e.g. /c/ → https://{domain}/c/{identity}). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. c/jane-a7f2).

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

input.linkProps.tagIds

input.linkProps.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.linkProps.tagIds anyOf branch 2

input.linkProps.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.linkProps.tagNames

input.linkProps.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.linkProps.tagNames anyOf branch 2

input.linkProps.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.linkProps.testVariants

input.linkProps.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

listPartners

GET /partners

Argument

Required

Type

Details

groupId

No; body/guard requirements still apply

string

A filter on the list based on the partner's groupId field.

status

No; body/guard requirements still apply

string

A filter on the list based on the partner's status field. enum: ["pending", "approved", "rejected", "invited", "declined", "deactivated", "banned", "archived"].

country

No; body/guard requirements still apply

string

A filter on the list based on the partner's country field.

sortBy

No; body/guard requirements still apply

string

The field to sort the partners by. The default is totalSaleAmount. enum: ["createdAt", "totalClicks", "totalLeads", "totalConversions", "totalSaleAmount", "totalCommissions", "netRevenue", "earningsPerClick", "averageLifetimeValue", "clickToLeadRate", "clickToConversionRate", "leadToConversionRate", "returnOnAdSpend"]. default: "totalSaleAmount".

sortOrder

No; body/guard requirements still apply

string

The sort order. The default is desc. enum: ["asc", "desc"]. default: "desc".

email

No; body/guard requirements still apply

string

Filter the partner list based on the partner's email. The value must be a string. Takes precedence over search.

tenantId

No; body/guard requirements still apply

string

Filter the partner list based on the partner's tenantId. The value must be a string. Combines with the other filters.

search

No; body/guard requirements still apply

string

A search query to filter partners by ID, name, email, company name, description, social platforms, or referral links. Partial matches are supported.

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

pageSize

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

No native JSON request body.

POST /partners/links

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

url

No; body/guard requirements still apply

['string', 'null']

The URL to shorten (if not provided, the program's default URL will be used). maxLength: 32000.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

linkProps

No; body/guard requirements still apply

object

Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.

input.linkProps

Argument

Required

Type

Details

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

prefix

No; body/guard requirements still apply

string

Path prefix for each default referral link slug (e.g. /c/ → https://{domain}/c/{identity}). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. c/jane-a7f2).

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

input.linkProps.tagIds

input.linkProps.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.linkProps.tagIds anyOf branch 2

input.linkProps.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.linkProps.tagNames

input.linkProps.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.linkProps.tagNames anyOf branch 2

input.linkProps.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.linkProps.testVariants

input.linkProps.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

GET /partners/links

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

No native JSON request body.

PUT /partners/links/upsert

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

url

Yes

string

The URL to upsert for. maxLength: 32000.

key

No; body/guard requirements still apply

string

The short link slug. If not provided, a random 7-character slug will be generated. maxLength: 190.

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

linkProps

No; body/guard requirements still apply

object

Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.

input.linkProps

Argument

Required

Type

Details

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

prefix

No; body/guard requirements still apply

string

Path prefix for each default referral link slug (e.g. /c/ → https://{domain}/c/{identity}). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. c/jane-a7f2).

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

input.linkProps.tagIds

input.linkProps.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.linkProps.tagIds anyOf branch 2

input.linkProps.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.linkProps.tagNames

input.linkProps.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.linkProps.tagNames anyOf branch 2

input.linkProps.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.linkProps.testVariants

input.linkProps.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

retrievePartnerAnalytics

GET /partners/analytics

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

interval

No; body/guard requirements still apply

string

The interval to retrieve analytics for. If undefined, defaults to 24h. enum: ["24h", "7d", "30d", "90d", "1y", "mtd", "qtd", "ytd", "all"].

start

No; body/guard requirements still apply

string

The start date and time when to retrieve analytics from. If set, takes precedence over interval.

end

No; body/guard requirements still apply

string

The end date and time when to retrieve analytics from. If not provided, defaults to the current date. If set along with start, takes precedence over interval.

timezone

No; body/guard requirements still apply

string

The IANA time zone code for aligning timeseries granularity (e.g. America/New_York). Defaults to UTC. default: "UTC".

query

No; body/guard requirements still apply

string

Search the events by a custom metadata value. Only available for lead and sale events. Examples: metadata['key']:'value' maxLength: 10000.

groupBy

No; body/guard requirements still apply

string

The parameter to group the analytics data points by. Defaults to count if undefined. enum: ["top_links", "timeseries", "count"]. default: "count".

No native JSON request body.

banPartner

POST /partners/ban

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

reason

Yes

string

The reason for banning the partner. enum: ["tos_violation", "inappropriate_content", "fake_traffic", "fraud", "spam", "brand_abuse"].

deactivatePartner

POST /partners/deactivate

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner to create a link for. Will take precedence over tenantId if provided.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the partner in your system. If both partnerId and tenantId are not provided, an error will be thrown.

listProgramApplications

GET /program-applications

Argument

Required

Type

Details

country

No; body/guard requirements still apply

string

A filter on the list based on the partner's country field.

groupId

No; body/guard requirements still apply

string

A filter on the list based on the partner's groupId field.

sortOrder

No; body/guard requirements still apply

string

The sort order. The default is desc. enum: ["asc", "desc"]. default: "desc".

search

No; body/guard requirements still apply

string

Filter applications by name, email, or company name. Partial matches are supported. An exact partner ID is also matched.

status

No; body/guard requirements still apply

string

Filter applications by status. One of pending, approved, or rejected. Defaults to pending. enum: ["pending", "approved", "rejected"]. default: "pending".

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

pageSize

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

No native JSON request body.

approveProgramApplication

POST /program-applications/approve

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

partnerId

Yes

string

The ID of the partner to approve.

groupId

No; body/guard requirements still apply

['string', 'null']

The ID of the group to assign the partner to. If not provided, the partner will be assigned to the group they applied to, or the program's default group if no application group is set.

rejectProgramApplication

POST /program-applications/reject

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

partnerId

Yes

string

The ID of the partner to reject.

rejectionReason

No; body/guard requirements still apply

string

The reason for rejecting the partner application. This will be shared with the partner via email. enum: ["needsMoreDetail", "doesNotMeetRequirements", "notTheRightFit", "other"].

rejectionNote

No; body/guard requirements still apply

string

Additional details about the rejection. This will be shared with the partner via email. maxLength: 500.

reapplicationTimeframe

No; body/guard requirements still apply

string

The mode for reapplying for the program. instant: The partner can reapply immediately. standard: The partner can reapply after 30 days. never: The partner can never reapply for the program. Defaults to standard if undefined. enum: ["instant", "standard", "never"]. default: "standard".

flagForFraud

No; body/guard requirements still apply

boolean

Whether to flag the partner for fraud review by the Dub team. Cannot be combined with reapplicationTimeframe: instant.

flagForFraudReason

No; body/guard requirements still apply

string

The reason for flagging the partner for fraud. Required when flagForFraud is true. maxLength: 2000.

listDiscountCodes

GET /discount-codes

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

string

The ID of the partner to retrieve discount codes for. If omitted, returns discount codes for the whole program.

discountId

No; body/guard requirements still apply

string

Filter discount codes by discount ID.

code

No; body/guard requirements still apply

string

Filter discount codes by the alphanumeric code (e.g. PARTNER10OFF).

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

pageSize

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

No native JSON request body.

createDiscountCode

POST /discount-codes

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

code

No; body/guard requirements still apply

string

The discount code to create. If omitted, a unique code will be generated automatically from the partner's name. Stripe and Shopify codes can only contain letters, numbers, dashes, and underscores. Custom provider codes can contain any characters. maxLength: 100.

partnerId

Yes

string

The ID of the partner to create a discount code for.

linkId

Yes

string

The ID of the partner's referral link to associate this discount code with. Each link can only have one discount code.

deleteDiscountCode

DELETE /discount-codes/{idOrCode}

Argument

Required

Type

Details

idOrCode

Yes

string

The unique ID (e.g. dcode_...) or alphanumeric code (e.g. ABC123) of the discount code to delete.

No native JSON request body.

createCommission

POST /commissions

Native JSON value; inspect the full schema for validation.

input oneOf branch 1

Argument

Required

Type

Details

type

Yes

string

Native field; use the reviewed provider reference. enum: ["custom"].

partnerId

Yes

string

The ID of the partner to create the commission for.

amount

Yes

number

The commission earnings amount in cents. Use a negative amount to create a clawback.

date

No; body/guard requirements still apply

['string', 'null']

If not provided, the current date will be used.

description

No; body/guard requirements still apply

['string', 'null']

The description of the commission. Required for clawbacks (negative amount). May be a known clawback reason (order_canceled, fraud, terms_violation, tracking_error, payment_failed, ineligible_partner, duplicate_commission) or an arbitrary string (max 190 characters). maxLength: 190.

input oneOf branch 2

Argument

Required

Type

Details

type

Yes

string

Native field; use the reviewed provider reference. enum: ["lead"].

partnerId

Yes

string

The ID of the partner to create the commission for.

customerId

No; body/guard requirements still apply

['string', 'null']

The customer ID to associate the commission with. Useful if the customer was already created in a prior operation and you want to associate the commission with it.

customer

No; body/guard requirements still apply

['object', 'null']

The full customer object to associate the commission with. Useful for creating the customer on demand.

linkId

No; body/guard requirements still apply

['string', 'null']

The partner link ID to associate the commission with. If not provided, default to the link with the most revenue.

date

No; body/guard requirements still apply

['string', 'null']

The date and time of the lead event. If not provided, defaults to the current date and time.

lead

No; body/guard requirements still apply

['object', 'null']

The lead event object to associate the commission with.

leadEventDate

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use date instead. The date and time of the lead event. If not provided, defaults to the current date and time. Deprecated native compatibility field.

leadEventName

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use lead.eventName instead. The name of the lead event. If not provided, defaults to 'Sign up'. default: "Sign up". Deprecated native compatibility field.

input.oneOf2.customer

Argument

Required

Type

Details

email

No; body/guard requirements still apply

['string', 'null']

The customer's email address. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". format: "email".

name

No; body/guard requirements still apply

['string', 'null']

The customer's name. If not provided, the email address will be used, and if email is not provided, a random name will be generated.

avatar

No; body/guard requirements still apply

['string', 'null']

The customer's avatar URL. If not provided, a random avatar will be generated. format: "uri".

externalId

Yes

string

The customer's unique identifier your database. This is useful for associating subsequent conversion events from Dub's API to your internal systems.

stripeCustomerId

No; body/guard requirements still apply

['string', 'null']

The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.

country

Yes

string

The customer's country in ISO 3166-1 alpha-2 format. Updating this field will only affect the customer's country in Dub's system (and has no effect on existing conversion events).

input.oneOf2.lead

Argument

Required

Type

Details

eventName

No; body/guard requirements still apply

['string', 'null']

The name of the lead event to track. If not provided, defaults to 'Sign up'. minLength: 1. maxLength: 255.

metadata

No; body/guard requirements still apply

['object', 'null']

Additional metadata to be stored with the lead event. Max 10,000 characters. default: null.

input oneOf branch 3

Argument

Required

Type

Details

type

Yes

string

Native field; use the reviewed provider reference. enum: ["sale"].

partnerId

Yes

string

The ID of the partner to create the commission for.

customerId

No; body/guard requirements still apply

['string', 'null']

The customer ID to associate the commission with. Useful if the customer was already created in a prior operation and you want to associate the commission with it.

customer

No; body/guard requirements still apply

['object', 'null']

The full customer object to associate the commission with. Useful for creating the customer on demand.

linkId

No; body/guard requirements still apply

['string', 'null']

The partner link ID to associate the commission with. If neither linkId nor discountCode is provided, default to the link with the most revenue.

discountCode

No; body/guard requirements still apply

['string', 'null']

The partner discount code to resolve the associated link. Use this when the link ID is unknown. Cannot be provided together with linkId. minLength: 1.

importStripeInvoices

No; body/guard requirements still apply

['boolean', 'null']

When true, import all unimported paid Stripe invoices for the customer and create a commission for each. When false, create a single manual sale event using sale.amount (or deprecated saleAmount). default: false.

date

No; body/guard requirements still apply

['string', 'null']

Only used when importStripeInvoices is false. The date of the manual sale event. Defaults to the current date and time if not provided.

sale

No; body/guard requirements still apply

['object', 'null']

The sale event object to associate the commission with.

saleEventDate

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use date instead. Deprecated native compatibility field.

saleAmount

No; body/guard requirements still apply

['number', 'null']

Deprecated: Use sale.amount instead. Deprecated native compatibility field.

invoiceId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use sale.invoiceId instead. Deprecated native compatibility field.

productId

No; body/guard requirements still apply

['string', 'null']

Deprecated: Use sale.metadata.productId instead. Deprecated native compatibility field.

input.oneOf3.customer

Argument

Required

Type

Details

email

No; body/guard requirements still apply

['string', 'null']

The customer's email address. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". format: "email".

name

No; body/guard requirements still apply

['string', 'null']

The customer's name. If not provided, the email address will be used, and if email is not provided, a random name will be generated.

avatar

No; body/guard requirements still apply

['string', 'null']

The customer's avatar URL. If not provided, a random avatar will be generated. format: "uri".

externalId

Yes

string

The customer's unique identifier your database. This is useful for associating subsequent conversion events from Dub's API to your internal systems.

stripeCustomerId

No; body/guard requirements still apply

['string', 'null']

The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.

country

Yes

string

The customer's country in ISO 3166-1 alpha-2 format. Updating this field will only affect the customer's country in Dub's system (and has no effect on existing conversion events).

input.oneOf3.sale

Argument

Required

Type

Details

amount

No; body/guard requirements still apply

['number', 'null']

The amount of the sale in cents (for all two-decimal currencies). If the sale is in a zero-decimal currency, pass the full integer value (e.g. 1580 JPY). Learn more: https://d.to/currency

currency

No; body/guard requirements still apply

string

The currency of the sale. Accepts ISO 4217 currency codes. Sales will be automatically converted and stored as USD at the latest exchange rates. Learn more: https://d.to/currency default: "usd".

eventName

No; body/guard requirements still apply

string

The name of the sale event. Recommended format: Invoice paid or Subscription created. maxLength: 255. default: "Purchase".

paymentProcessor

No; body/guard requirements still apply

string

The payment processor via which the sale was made. enum: ["stripe", "shopify", "polar", "paddle", "apple", "revenuecat", "lemonsqueezy", "dub", "custom"]. default: "custom".

invoiceId

No; body/guard requirements still apply

['string', 'null']

The invoice ID of the sale. Can be used as a idempotency key – only one sale event can be recorded for a given invoice ID. default: null.

metadata

No; body/guard requirements still apply

['object', 'null']

Additional metadata to be stored with the sale event. Max 10,000 characters when stringified. default: null.

listCommissions

GET /commissions

Argument

Required

Type

Details

type

No; body/guard requirements still apply

string

Filter the list of commissions by type. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: - "sale" - "sale,lead" - "-click" enum: ["click", "lead", "sale", "referral", "custom"].

customerId

No; body/guard requirements still apply

string

Filter the list of commissions by the associated customer.

payoutId

No; body/guard requirements still apply

string

Filter the list of commissions by the associated payout.

bountySubmissionId

No; body/guard requirements still apply

string

Filter the list of commissions by the associated bounty submission.

partnerId

No; body/guard requirements still apply

string

Filter the list of commissions by the associated partner. When specified, takes precedence over tenantId. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: - "partner_abc" - "partner_abc,partner_xyz" - "-partner_abc"

tenantId

No; body/guard requirements still apply

string

Filter the list of commissions by the associated partner's tenantId (their unique ID within your database).

groupId

No; body/guard requirements still apply

string

Filter the list of commissions by the associated partner group. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: - "group_abc" - "group_abc,group_xyz" - "-group_abc"

partnerTagId

No; body/guard requirements still apply

string

Filter the list of commissions by the associated partner tag. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: - "ptag_abc" - "ptag_abc,ptag_xyz" - "-ptag_abc"

invoiceId

No; body/guard requirements still apply

string

Filter the list of commissions by the associated invoice. Since invoiceId is unique on a per-program basis, this will only return one commission per invoice.

status

No; body/guard requirements still apply

string

Filter the list of commissions by their corresponding status. enum: ["pending", "processed", "paid", "refunded", "duplicate", "fraud", "canceled", "hold"].

sortBy

No; body/guard requirements still apply

string

The field to sort the list of commissions by. enum: ["createdAt", "amount"]. default: "createdAt".

sortOrder

No; body/guard requirements still apply

string

The sort order for the list of commissions. enum: ["asc", "desc"]. default: "desc".

interval

No; body/guard requirements still apply

string

The interval to retrieve commissions for. enum: ["24h", "7d", "30d", "90d", "1y", "mtd", "qtd", "ytd", "all"]. default: "all".

start

No; body/guard requirements still apply

string

The start date of the date range to filter the commissions by.

end

No; body/guard requirements still apply

string

The end date of the date range to filter the commissions by.

timezone

No; body/guard requirements still apply

string

Native field; use the reviewed provider reference.

query

No; body/guard requirements still apply

string

Filter by lead or sale event metadata. Top-level keys only. Compares string values only : numeric and boolean metadata values are not matched. Examples: - "metadata['key']='value'" - "metadata['key']!='value'" maxLength: 10000.

endingBefore

No; body/guard requirements still apply

string

If specified, the query only searches for results before this cursor. Mutually exclusive with startingAfter.

startingAfter

No; body/guard requirements still apply

string

If specified, the query only searches for results after this cursor. Mutually exclusive with endingBefore.

page

No; body/guard requirements still apply

integer

DEPRECATED. Use startingAfter instead. maximum: 9007199254740991. exclusiveMinimum: 0. Deprecated native compatibility field.

pageSize

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

No native JSON request body.

updateCommission

PATCH /commissions/{id}

Argument

Required

Type

Details

id

Yes

string

The commission's unique ID on Dub.

Argument

Required

Type

Details

earnings

No; body/guard requirements still apply

number

The new earnings amount for the commission. Paid commissions cannot be updated. If provided, will override the earnings calculated based on the sale amount and currency. minimum: 0.

saleAmount

No; body/guard requirements still apply

number

The new absolute amount for the sale. Paid commissions cannot be updated. minimum: 0.

modifySaleAmount

No; body/guard requirements still apply

number

Modify the current sale amount: use positive values to increase the amount, negative values to decrease it. Takes precedence over saleAmount. Paid commissions cannot be updated.

currency

No; body/guard requirements still apply

string

The currency of the sale amount to update. Accepts ISO 4217 currency codes. default: "usd".

status

No; body/guard requirements still apply

string

Useful for marking a commission as pending, refunded, duplicate, canceled, or fraudulent. Takes precedence over saleAmount and modifySaleAmount. When a commission is marked as pending, refunded, duplicate, canceled, or fraudulent, it will be omitted from the payout, and the payout amount will be recalculated accordingly. Paid commissions cannot be updated. enum: ["pending", "refunded", "duplicate", "canceled", "fraud"].

amount

No; body/guard requirements still apply

number

Deprecated. Use saleAmount instead. minimum: 0. Deprecated native compatibility field.

modifyAmount

No; body/guard requirements still apply

number

Deprecated. Use modifySaleAmount instead. Deprecated native compatibility field.

bulkUpdateCommissions

PATCH /commissions/bulk

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

commissionIds

Yes

array

Native field; use the reviewed provider reference. minItems: 1. maxItems: 100.

status

Yes

string

The status to apply to every commission in the batch. enum: ["pending", "refunded", "duplicate", "canceled", "fraud"].

input.commissionIds

input.commissionIds[]

Native JSON value; inspect the full schema for validation.

listPayouts

GET /payouts

Argument

Required

Type

Details

status

No; body/guard requirements still apply

string

Filter the list of payouts by their corresponding status. enum: ["pending", "processing", "processed", "sent", "completed", "failed", "canceled"].

partnerId

No; body/guard requirements still apply

string

Filter the list of payouts by the associated partner. When specified, takes precedence over tenantId.

tenantId

No; body/guard requirements still apply

string

Filter the list of payouts by the associated partner's tenantId (their unique ID within your database).

invoiceId

No; body/guard requirements still apply

string

Filter the list of payouts by invoice ID (the unique ID of the invoice you receive for each batch payout you process on Dub). Pending payouts will not have an invoice ID.

groupId

No; body/guard requirements still apply

string

Filter the list of payouts by the associated partner group. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: group_abc, group_abc,group_xyz, -group_abc.

sortBy

No; body/guard requirements still apply

string

The field to sort the list of payouts by. enum: ["amount", "initiatedAt", "paidAt"]. default: "amount".

sortOrder

No; body/guard requirements still apply

string

The sort order for the list of payouts. enum: ["asc", "desc"]. default: "desc".

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

pageSize

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

No native JSON request body.

createReferralsEmbedToken

POST /tokens/embed/referrals

Native JSON value; inspect the full schema for validation.

Argument

Required

Type

Details

partnerId

No; body/guard requirements still apply

string

Native field; use the reviewed provider reference.

tenantId

No; body/guard requirements still apply

string

Native field; use the reviewed provider reference.

partner

No; body/guard requirements still apply

object

Native field; use the reviewed provider reference.

input.partner

Argument

Required

Type

Details

name

No; body/guard requirements still apply

['string', 'null']

The partner's full name. If undefined, the partner's email will be used in lieu of their name (e.g. john@acme.com) maxLength: 100.

email

Yes

string

The partner's email address. Partners will be able to claim their profile by signing up at partners.dub.co with this email. maxLength: 190. pattern: "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$". format: "email".

username

No; body/guard requirements still apply

['string', 'null']

The partner's unique username in your system (max 100 characters). This will be used to create a short link for the partner using your program's default domain. If not provided, Dub will try to generate a username from the partner's name or email. maxLength: 100.

image

No; body/guard requirements still apply

['string', 'null']

The partner's avatar image. If not provided, a default avatar will be used.

tenantId

No; body/guard requirements still apply

string

The partner's unique ID in your system. Useful for retrieving the partner's links and stats later on. If not provided, the partner will be created as a standalone partner.

groupId

No; body/guard requirements still apply

string

The group ID to add the partner to. If not provided, the partner will be added to the default group.

country

No; body/guard requirements still apply

['string', 'null']

The partner's country of residence. Must be passed as a 2-letter ISO 3166-1 country code. See https://d.to/geo for more information.

description

No; body/guard requirements still apply

['string', 'null']

A brief description of the partner and their background. Max 5,000 characters. maxLength: 5000.

linkProps

No; body/guard requirements still apply

object

Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.

input.partner.linkProps

Argument

Required

Type

Details

externalId

No; body/guard requirements still apply

['string', 'null']

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace. Pass null or an empty string to remove it. maxLength: 255.

tenantId

No; body/guard requirements still apply

['string', 'null']

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant. Pass null or an empty string to remove it. maxLength: 255.

prefix

No; body/guard requirements still apply

string

Path prefix for each default referral link slug (e.g. /c/ → https://{domain}/c/{identity}). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. c/jane-a7f2).

archived

No; body/guard requirements still apply

boolean

Whether the short link is archived. Defaults to false if not provided.

tagIds

No; body/guard requirements still apply

JSON

The unique IDs of the tags assigned to the short link.

tagNames

No; body/guard requirements still apply

JSON

The unique name of the tags assigned to the short link (case insensitive).

comments

No; body/guard requirements still apply

['string', 'null']

The comments for the short link.

expiresAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the short link will expire at.

expiredUrl

No; body/guard requirements still apply

['string', 'null']

The URL to redirect to when the short link has expired. maxLength: 32000.

password

No; body/guard requirements still apply

['string', 'null']

The password required to access the destination URL of the short link.

proxy

No; body/guard requirements still apply

boolean

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

title

No; body/guard requirements still apply

['string', 'null']

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

No; body/guard requirements still apply

['string', 'null']

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

No; body/guard requirements still apply

['string', 'null']

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

No; body/guard requirements still apply

['string', 'null']

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewrite

No; body/guard requirements still apply

boolean

Whether the short link uses link cloaking. Defaults to false if not provided.

ios

No; body/guard requirements still apply

['string', 'null']

The iOS destination URL for the short link for iOS device targeting. maxLength: 32000.

android

No; body/guard requirements still apply

['string', 'null']

The Android destination URL for the short link for Android device targeting. maxLength: 32000.

doIndex

No; body/guard requirements still apply

boolean

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

testVariants

No; body/guard requirements still apply

['array', 'null']

An array of A/B test URLs and the percentage of traffic to send to each URL. minItems: 2. maxItems: 4.

testStartedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests started.

testCompletedAt

No; body/guard requirements still apply

['string', 'null']

The date and time when the tests were or will be completed.

input.partner.linkProps.tagIds

input.partner.linkProps.tagIds anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.partner.linkProps.tagIds anyOf branch 2

input.partner.linkProps.tagIds.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.partner.linkProps.tagNames

input.partner.linkProps.tagNames anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.partner.linkProps.tagNames anyOf branch 2

input.partner.linkProps.tagNames.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.partner.linkProps.testVariants

input.partner.linkProps.testVariants[]

Argument

Required

Type

Details

url

Yes

string

Native field; use the reviewed provider reference.

percentage

Yes

number

Native field; use the reviewed provider reference. minimum: 10. maximum: 90.

getQRCode

GET /qr

Argument

Required

Type

Details

url

Yes

string

The URL to generate a QR code for. maxLength: 32000.

logo

No; body/guard requirements still apply

string

The logo to include in the QR code. Can only be used with a paid plan on Dub.

size

No; body/guard requirements still apply

number

The size of the QR code in pixels. Defaults to 600 if not provided. default: 600.

level

No; body/guard requirements still apply

string

The level of error correction to use for the QR code. Defaults to L if not provided. enum: ["L", "M", "Q", "H"]. default: "L".

fgColor

No; body/guard requirements still apply

string

The foreground color of the QR code in hex format. Defaults to #000000 if not provided. default: "#000000".

bgColor

No; body/guard requirements still apply

string

The background color of the QR code in hex format. Defaults to #ffffff if not provided. default: "#FFFFFF".

hideLogo

No; body/guard requirements still apply

boolean

Whether to hide the logo in the QR code. Can only be used with a paid plan on Dub. default: false.

margin

No; body/guard requirements still apply

number

The size of the margin around the QR code. Defaults to 2 if not provided. default: 2.

includeMargin

No; body/guard requirements still apply

boolean

DEPRECATED: Margin is included by default. Use the margin prop to customize the margin size. default: true. Deprecated native compatibility field.

No native JSON request body.

listBountySubmissions

GET /bounties/{bountyId}/submissions

Argument

Required

Type

Details

bountyId

Yes

string

The unique ID of the bounty on Dub. Can be found in the URL of the bounty page, prefixed with bnty_.

status

No; body/guard requirements still apply

string

The status of the submissions to list. enum: ["draft", "submitted", "approved", "rejected"].

groupId

No; body/guard requirements still apply

string

The ID of the group to list submissions for.

partnerId

No; body/guard requirements still apply

string

The ID of the partner to list submissions for.

sortBy

No; body/guard requirements still apply

string

The field to sort the submissions by. enum: ["completedAt", "performanceCount", "socialMetricCount"]. default: "completedAt".

sortOrder

No; body/guard requirements still apply

string

The order to sort the submissions by. enum: ["asc", "desc"]. default: "asc".

page

No; body/guard requirements still apply

integer

The page number for pagination. The first page is 1. maximum: 9007199254740991. exclusiveMinimum: 0.

pageSize

No; body/guard requirements still apply

integer

The number of items per page. maximum: 100. exclusiveMinimum: 0. default: 100.

No native JSON request body.

approveBountySubmission

POST /bounties/{bountyId}/submissions/{submissionId}/approve

Argument

Required

Type

Details

bountyId

Yes

string

The ID of the bounty

submissionId

Yes

string

The ID of the bounty submission

Argument

Required

Type

Details

rewardAmount

No; body/guard requirements still apply

['number', 'null']

The reward amount for the performance-based bounty. Applicable if the bounty reward amount is not set.

rejectBountySubmission

POST /bounties/{bountyId}/submissions/{submissionId}/reject

Argument

Required

Type

Details

bountyId

Yes

string

The ID of the bounty

submissionId

Yes

string

The ID of the bounty submission

Argument

Required

Type

Details

rejectionReason

No; body/guard requirements still apply

string

The reason for rejecting the submission. enum: ["invalidProof", "duplicateSubmission", "outOfTimeWindow", "didNotMeetCriteria", "other"].

rejectionNote

No; body/guard requirements still apply

string

The note for rejecting the submission. maxLength: 5000.

Use list_links and get_link with a real link_id, external_id or domain plus key. API external-ID queries require the documented ext_ prefix. Existing get_link_stats now reaches the current analytics endpoint, with event/group/filter/date fields; it does not imply analytics is on the Free plan. Use schema/help to inspect native UTM, conversion tracking, expiration, tags/folders, A/B variants and platform redirect fields before submitting.

create_link/upsert_link require url; update_link must include an actual change. PATCH semantics follow the provider, not a recursive merge invented by this package. A/B/native nested constraints come from the pinned current schema. Native bulk create accepts an array, bulk update a data object, and bulk delete comma-separated linkIds. No bulk custom previews or webhook events are invented.

Partners, applications and financial work

Current list_program_applications/approve_program_application/reject_program_application use /program-applications. The older published SDK snapshot uses /partners/applications; do not assume aliases. Read the requested application/partner before approving or rejecting. Ban/delete actions can cancel commissions or remove links; confirmation must match the user's intended scope.

create_commission accepts the documented discriminated custom/lead/sale bodies and may return an asynchronous task receipt. bulk_update_commissions only accepts its native pending/refunded/duplicate/canceled/fraud statuses; do not fabricate an approved/paid status. list_payouts reads provider records; no payout transfer endpoint exists here. Events/conversions can affect business metrics and affiliate commissions, so they require the same explicit guard as other POSTs. No polling, financial completion, refunds or unrelated messages occur implicitly.

Requested private QR and embed output

dub-cli get-qr-code --url https://example.com/requested --output-file /absolute/private/requested.png --confirm --agent
dub-cli create-referrals-embed-token --payload '{"partnerId":"YOUR_PARTNER_ID"}' --output-file /absolute/private/referral-token.json --confirm --agent

Reserve a new exclusive private file before the provider request; existing files refuse without a request. QR requires the PNG signature/content type. Embed JSON contains publicToken and expires only in that file; a publicToken is still an access credential despite its name. No PNG base64/key appears in model output and no automatic upload/browser preview occurs. Keep its parent directory private and restrict Windows ACLs. Invalid/error responses remove only this newly reserved file; provider token creation can still have an unknown outcome.

10. Exact reviewed batches and pagination

Review an exact ordered batch

dub-cli preview-link-batch --tasks '{"tool":"create_link","arguments":{"payload":{"url":"https://example.com/a","key":"approved-a"}}}' --tasks '{"tool":"create_tag","arguments":{"name":"Approved campaign"}}' --account work --agent
dub-cli submit-link-batch --tasks '{"tool":"create_link","arguments":{"payload":{"url":"https://example.com/a","key":"approved-a"}}}' --tasks '{"tool":"create_tag","arguments":{"name":"Approved campaign"}}' --account work --review-sha256 YOUR_REVIEW_SHA256 --confirm --agent

Preview validates all one-to-twenty link/tag/folder operations locally without loading a key or contacting Dub. SHA-256 binds canonical native requests, ordered tasks, selected profile label and sanitized schema snapshot. Changed task/order/profile/schema refuses before the first mutation. Canonical key order does not change the hash. Nested account/confirm/file overrides are refused; batch bodies are inline, so mutable payload files cannot change after review.

The hash does not prove the key's owner, bind a key replaced behind the same label, lock changing provider state, reserve quota or certify human approval. No automatic reads or provider-state comparisons are added. Execution sends sequentially, stops on first HTTP/network/validation failure or native bulk-create per-link errors, and returns known receipts, failed index and unattempted indices. A native partial bulk receipt can include both successes and errors at the failed index. No rollback, replay, automatic continuation or implicit cleanup occurs. Native bulk remains up to 100 records per task.

Native pagination is explicit

list_links/list_customers/list_commissions use starting_after or ending_before with page_size; other list operations expose their own page/page_size or limit controls. Preserve original filters/date/sort and exact native cursor from the provider when deliberately continuing. Mutually exclusive cursors and cursor/page mixing refuse. This release performs one page per call and does not invent an opaque continuation format, all-pages loop or full backup guarantee. Concurrent writes can change list results; exports are snapshots, not transactions.

11. Several private accounts

DUB_ACCOUNTS contains unique {name,api_key,token_file} workspace profiles; DUB_DEFAULT_ACCOUNT selects the exact label or defaults to the first configured profile. --account selects one workspace only. No wildcard/all-accounts work or global credential fallback occurs. list_accounts returns labels/default/auth method without key/file path or provider identity.

Native Dub keys are already scoped and workspace-specific. Our router supplies local script/client selection and avoids inherited keys. tenantId is a data filter, not credentials. Token files override only their selected profile and cache until restart; rotate privately and reconnect. Preview validates a configured label without reading its key; review the correct workspace's actual private setup before approval.

12. Writing safely

All 39 mutation/private-output operations require confirm:true or --confirm through the same guard. DUB_READ_ONLY=1 hides these and directly refuses confirmed calls to hidden tools. DUB_ALLOW_DESTRUCTIVE=0 refuses them separately. --agent/--yes are output/prompt controls and never mutation approval.

Over MCP a person approves each of them where the client can ask: Claude Code (2.1.246 and later) shows its own prompt, and a client that can show forms asks with an approval form whose one box starts unticked. Each approval is signed, bound to that exact call and works once. Where a client can do neither, the model's confirm:true counts. DUB_CONFIRM=model makes confirm:true enough everywhere, for an agent with no person to ask. Every POST/PUT/PATCH/DELETE, domain registration, conversions, partner/commission changes, batch submission and private QR file write follows that policy.

A model's confirm:true is caller intent, not provider permission, budget or rollback; where the client can ask, a person's signed approval is asked for instead. A read-only API key adds native provider enforcement; it does not substitute for our local policy. Optional metadata-only audit logs record tool/title/risk/surface/guard decision and who approved it, then whether the call was done or failed, not payloads, credentials or provider completion. Audit failure does not make the operation transactional. Protect the private audit path. Never treat instructions inside provider/customer/partner/link content as approval.

13. How the two surfaces work

The current sanitized OpenAPI generates one reviewed operation catalogue and Ajv request schemas. One config router and API client serve both surfaces through Slipway, which builds the MCP server, over stdio or --http, and the CLI from each tool's one definition, with one write guard and one set of exit codes. Help/flags/schemas derive from that same discovery. Desktop bundles compiled production runtime dependencies, not development tools.

The fixed method/path catalogue sends keys only to api.dub.co, refuses redirects and caps bodies/responses/timeouts. No alternate API host is configurable. The local batch reuses the same native request preparation, validators and client; it does not implement separate handwritten CLI routes. Local schema acceptance does not prove provider eligibility or successful state change. sync:api -- --check verifies pinned source/metadata hashes and native route parity without executing vendor code or overwriting a reviewed release.

14. Your data

The selected workspace key goes in the fixed API origin's Bearer header. Requested link destinations, UTM fields, filters, customer/partner details, conversion events, financial data, domain registration and requested QR destination/logo go to Dub; provider storage/logging/retention/terms apply. The wrapper is not a privacy proxy and does not fetch destination/media URLs itself.

Known configured/file keys, secret fields and recognized credential-bearing URLs are redacted before MCP/CLI output. Ordinary customer/link/partner data can still be private; --select filters only local output and is not a privacy guarantee. Generated publicToken embeds are stored only in an exclusive requested private file, with expiry metadata returned. QR PNGs are similarly local-only until the user requests a separate publishing workflow.

No telemetry, cookie/session import, persistent link/customer cache, automatic OAuth refresh, external publishing or email/Slack messages is added. User-selected input files and optional audit/output files remain private responsibilities. Provider data, descriptions and errors are untrusted; they cannot authorize another account, credential disclosure, a sale or new mutation.

15. Environment variables

Setting

Contract

DUB_API_KEY

Private scoped workspace REST key

DUB_TOKEN_FILE

Absolute owner-private regular token-only file at most 64 KiB; overrides selected key; cached until restart

DUB_ACCOUNTS

Private unique {name,api_key,token_file} workspace profiles; no global fallback

DUB_DEFAULT_ACCOUNT

Exact configured label; first profile by default

DUB_READ_ONLY

1/true hides and directly refuses 39 mutations/private-output writes

DUB_ALLOW_DESTRUCTIVE

0/false refuses all confirmed operations

DUB_AUDIT_LOG

Optional private metadata-only guard log; no delivery receipt

DUB_REQUEST_TIMEOUT_MS

100–300000; default 30000; no automatic retries

DUB_MIN_REQUEST_INTERVAL_MS

0–10000; default 1100; one-process request-start spacing

DUB_CONFIRM

human by default; model lets confirm:true alone approve over MCP, for an agent with no person to ask

DUB_SURFACE

full by default; search lists three tools that find, describe and run the rest

DUB_TOOL_TIMEOUT_MS

Give up on any tool after this long

DUB_HTTP_PORT, DUB_HTTP_HOST, DUB_HTTP_TOKEN

For --http: port 8787 and host 127.0.0.1 by default; any other host needs the bearer token

DUB_HTTP_ALLOWED_ORIGINS

Comma-separated browser origins allowed to call --http; a page from any other site is refused

DUB_DEBUG

1 prints debug lines on stderr

No automatic .env or official OAuth/session/config loader. GUI/remote clients have their own environment/filesystem; quota is shared with other provider clients.

16. Updates and removal

npm install -g @thenavidm/dub-mcp-cli@latest
dub-cli --version
npm uninstall -g @thenavidm/dub-mcp-cli
codex mcp remove dub

npx @latest resolves when a process starts; reconnect/restart for updates. Global npm and versioned desktop bundles require explicit updates. Uninstalling does not revoke provider keys/OAuth, undo requested changes or remove saved private files. Revoke access through the actual provider workspace separately.

17. Troubleshooting

Symptom

Check / next action

No configured profile

Use private key/file settings; login explains setup

401/403

Verify selected workspace, key scopes, user role and plan

CLI works, GUI fails

Configure that GUI/remote process's own environment/filesystem

Read-only refusal

Do only the read requested, or configure the explicitly intended mutation access

Invalid body

Inspect current schema; complete body input and no mixing

Program applications fail

Use current /program-applications, not old SDK routes

Only one list page

Deliberately continue with that endpoint's current native pagination

HTTP200 bulk errors

Inspect each item; do not replay known successes

429

Respect per-key/analytics quotas; no automatic retry

Unknown mutation outcome

Inspect provider state/known receipts before repeating

Review mismatch

Re-review exact task/profile/order/schema

Existing output file

Choose a new private path; overwrite is never implicit

HTTP202 commission

Accepted task receipt is not a completed financial action

Desktop refused

Check runtime/custom-extension policy and correct version

18. API coverage and comparisons

Offering

Reviewed version/surface

Strengths and limits

Official Links MCP

Public listed 32 tools, checked 2026-10-03

Hosted OAuth or headless key access, links/bulk operations, analytics/events, QR, customers/conversions, domains/tags/folders. Count is listed documentation, not authenticated discovery.

Official Partners MCP

Public listed 25 tools, checked 2026-10-03

Hosted partner/application/bounty/commission workflows. Overlapping tools must not be summed as unique coverage. Client approval behavior was not authenticated here.

Official CLI

dub-cli 0.0.13, bin dub, source 53808cb1e89254fd0746bd3294b434866c9d34a6

OAuth login, private configuration, domain selection, shorten and link search. Actual released shorten command constructed one POST without a confirmation flag in an intercepted fixture. No provider request or account outcome was tested. No documented shared exact reviewed batch/mandatory read-only guard in this inspected command surface.

Official SDK

dub 0.73.5, source eff8e92e06dcd77c03155b03ea7575ccf409cc21

Broad typed application API, optional pagination/retry configuration and custom HTTP client. Default retries are none, not an owned improvement. Current provider schema has program-application routes newer than this SDK's partner-application snapshot. SDK is separate from official dub-cli.

Community MCP

Pinned source 08bc2649fdbc2d338dab81d3c8db829b9a95c8a6

Three inspected create/update/delete link tools using DUBCO_API_KEY. No task CLI bin, private profile routing or common direct-call guard found in this reviewed source. Source inspection is not a runtime benchmark.

This owned companion

Local stdio MCP, shared task CLI and versioned desktop bundle

61 tools, 22 reads/helpers and 39 confirmed operations. Current 57 native routes, isolated workspace profiles, exact reviewed link/tag/folder batches, exclusive private QR/embed-token files and shared direct-call policy. No hosted OAuth, official session import, browser dashboard or proven task-token winner.

Dub already has an official CLI, hosted action MCPs, native bulk actions, scoped/read-only workspace keys and useful provider logs. None are described as missing. The owned product qualifies through verified shared local confirmation/direct-call read-only rules and exact payload/profile/order batch review, plus private generated-credential delivery. The real official CLI baseline made one intercepted POST without a confirmation flag; our same create_link refuses before fetch until explicitly approved. This does not establish missing approvals in the hosted MCP.

Official SDK delete was separately exercised through its real export and injected HTTP, with one intentionally unsuccessful fixture request and no mandatory confirmation argument. Neither fixture proves a successful account task or universal superiority. A human/client can already coordinate official tools; our exact hash provides a repeatable local request review boundary, not a unique ability to do bulk work or cryptographic human approval.

The current API was fetched from the official SDK workflow's observed source https://api.dub.co. Its 57 operations rename list/approve/reject partner applications to /program-applications. Source/provenance records both snapshots and sanitized hashes. Native schemas are converted to Ajv JSON Schema; malformed positive exclusiveMinimum booleans without a numeric minimum are documented as explicit local positive pagination/event-quantity validation, not asserted SDK behavior.

19. Versions and migration

Component

Reviewed / locked version

Owned package

3.0.1

Current native API operations

57

Slipway

0.1.17

MCP TypeScript SDK, through Slipway

2.3.0

Ajv

8.20.0

Ajv formats

3.0.1

TypeScript

7.0.2

Vitest

5.0.3

Vite

8.3.2

MCPB

2.1.2

Official CLI

dub-cli 0.0.13

Official SDK

dub 0.73.5

2.0.0 is a breaking modernization of the private twelve-tool JavaScript MCP. Both owned binaries now live under @thenavidm/dub-mcp-cli; the old generic package name is not republished. Eleven legacy names remain with current schemas; unsupported get_workspace is removed. get_link now uses link_id/external_id/domain+key selectors, get_link_stats uses current analytics parameters and domain reads use current list fields. New folder/partner/program-application/commission/conversion/bounty/discount/embed/QR routes follow current primary contracts.

All mutations now need confirmation, private account files/profiles use the documented new config, PNG/embed outputs require a new output_file, and reviewed batches require an exact hash. Native body JSON retains camelCase; query/path wrapper flags use snake-derived dashes. There is no invented account-wide workspace identity read or legacy route alias. Preserve private legacy history; do not push old refs or private credential files. Record future provider changes in dated changelog/provenance, meaningful fixtures and complete repo/CMS/client docs before release.

20. FAQ

It offers the same 61 Dub tasks through a shared CLI, local MCP and desktop bundle, using current API schemas and private workspace profiles.

Yes. Official Links and Partners MCPs provide broad hosted OAuth/key workflows. Their listed 32/25 tools can overlap; these are not authenticated discovery counts.

Yes. Official dub-cli 0.0.13 installs dub and offers OAuth, config, domain selection, shortening and link search. Our binary is dub-cli and adds the proven shared policy/review workflow.

Verified shared confirmation/direct-call read-only controls, exact ordered request review and private generated-credential delivery serve local scripts and stdio clients. SEO and more names alone are insufficient.

The documented local stdio/CLI clients include Codex, Claude Desktop/Code, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Cline and Docker on macOS/Windows/Linux. Host GUI and actual account outcomes have separate verification status.

No. Codex can use local MCP or the task CLI. Claude Code is optional; section 7 has both clients' measured costs.

No. Keys/scopes/workspace roles and paid plan eligibility remain provider requirements; Free analytics/events access is listed as unavailable.

This package uses private REST Bearer workspace keys. Official MCP uses OAuth or Mcp-Dub-Token; official dub CLI uses its own OAuth session. No sessions are imported.

Yes, through private named profiles and exact --account selection. A missing profile key never inherits a global key. Native workspace-scoped keys already exist.

Canonical requests, task order, selected profile label and reviewed schema snapshot. It does not verify key ownership, lock provider state, reserve money/quota or certify human identity.

No. Batch tasks exclude private-output/financial/domain actions and reject nested account/confirm/payload_file overrides. Only approved link/tag/folder work is accepted.

Execution stops, reports known results, failed index and unattempted tasks. Native HTTP200 bulk-create errors include the full known partial receipt. There is no retry, rollback or implicit continuation.

Yes, up to 100 link creates/updates/deletes per native call. Bulk creation omits custom previews/webhook events; an owned twenty-task bound is not a twenty-record limit.

A confirmed request writes PNG bytes to a new exclusive private output file, with signature/content-type validation and metadata returned. No base64 dump or automatic upload occurs.

publicToken and expiry go only into the requested exclusive private JSON file. Despite its name, publicToken is a credential; keep it and the parent directory/ACLs private.

Yes. It hides all 39 mutation/file-write operations and refuses confirmed direct calls. Native read-only API keys supply additional provider enforcement.

The current provider API uses /program-applications; the published SDK snapshot still uses partner-application routes. The owned current methods follow the newer primary schema.

Not necessarily. create_commission may return HTTP202 accepted task metadata. No task polling, payout execution or financial completion is inferred.

It depends on the client and the task. In Claude Code the CLI costs nothing until it is used, plus about 4,400 tokens for SKILL.md once, where the server costs about 1,080 tokens a message with tool search and 74,200 with every tool loaded. In Codex, finding the command that creates a short link took a median of 110,559 input tokens over the CLI and 78,400 over MCP. Section 7 has how each was measured.

Reconnect npx @latest, update global npm or install the new desktop archive. Remove client entries and revoke provider keys/OAuth separately; prior mutations and local private output remain.

Questions

Open a sanitized issue. Use SECURITY.md for private reports.

Built by

Navid Moazzez

Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. He creates useful free tools, MCP servers and CLIs that creators and founders can use in their own workflows.

Dependencies

Runtime: Slipway, which brings the MCP TypeScript SDK, plus Ajv and ajv-formats. Development: TypeScript, Vitest, Vite and MCPB. Exact locked versions appear above. Packaging tools are excluded from desktop runtime.

License

Preserves AGPL-3.0 and existing private legacy history. Read THIRD_PARTY_NOTICES.md. Dub service terms and trademarks remain separate.


© 2026 Navid Media. Made with ❤️ by Navid Moazzez.

Available Tools

61 tools
approve_bounty_submissionApprove a bounty submissionC
Destructive

Approve a bounty submission. Optionally specify a custom reward amount.

Inputs: bounty_id (required), submission_id (required), account, confirm, +3 more.

approve_program_applicationApprove a partner applicationA
Destructive

Approve a pending partner application to your program. The partner will be enrolled in the specified group and notified of the approval.

Inputs: account, confirm, groupId, payload, +2 more.

ban_partnerBan a partnerA
Destructive

Ban a partner from your program. This will disable all links and mark all commissions as canceled.

Inputs: reason, account, confirm, payload, +3 more.

bulk_update_commissionsBulk update commissionsB
Destructive

Bulk update up to 100 commissions with the same status.

Inputs: status, account, confirm, payload, +2 more.

check_domain_statusCheck the availability of one or more domainsA
Read-onlyIdempotent

Check if a domain name is available for purchase. You can check multiple domains at once.

Inputs: domains (required), account.

create_commissionCreate commissionA
Destructive

Create one or more commissions (custom, lead or sale) for a partner. Custom commissions accept a negative amount to create a clawback. Commission creation is processed asynchronously – use the GET /commissions endpoint or webhooks to be notified when the commission is created.

Inputs: account, confirm, payload, payload_file.

create_discount_codeCreate a discount codeA
Destructive

Create a discount code for a partner. The partner's group must already have a discount assigned to it, and the discount code must be associated with a link that is not already linked with another discount code.

Inputs: code, linkId, account, confirm, +3 more.

create_domainCreate a domainC
Destructive

Create a domain for the authenticated workspace.

Inputs: logo, slug, account, confirm, +8 more.

create_folderCreate a folderB
Destructive

Create a folder for the authenticated workspace.

Inputs: name, account, confirm, payload, +3 more.

create_partnerCreate or update a partnerA
Destructive

Creates or updates a partner record (upsert behavior). If a partner with the same email already exists, their program enrollment will be updated with the provided tenantId. If no existing partner is found, a new partner will be created using the supplied information.

Inputs: name, email, image, account, +9 more.

create_referrals_embed_tokenCreate a referrals embed tokenA
Destructive

Create a referrals embed token for the given partner/tenant. The endpoint first attempts to locate an existing enrollment using the provided tenantId. If no enrollment is found, it resolves the partner by email and creates a new enrollment as needed. This results in an upsert-style flow that guarantees a valid enrollment and returns a usable embed token.

Inputs: output_file (required), account, confirm, partner, +4 more.

create_tagCreate a tagB
Destructive

Create a tag for the authenticated workspace.

Inputs: tag, name, color, account, +3 more.

deactivate_partnerDeactivate a partnerA
Destructive

This will deactivate the partner from your program and disable all their active links. Their commissions and payouts will remain intact. You can reactivate them later if needed.

Inputs: account, confirm, payload, tenantId, +2 more.

delete_customerDelete a customerB
Destructive

Delete a customer from a workspace.

Inputs: id (required), account, confirm.

delete_discount_codeDelete a discount codeA
Destructive

Delete a discount code for a partner by its unique ID or alphanumeric code. This will also disable the code in your connected discount provider (Stripe, Shopify, or custom via disccount.deleted webhook).

Inputs: id_or_code (required), account, confirm.

delete_domainDelete a domainA
Destructive

Delete a domain from a workspace. It cannot be undone. This will also delete all the links associated with the domain.

Inputs: slug (required), account, confirm.

delete_folderDelete a folderA
Destructive

Delete a folder from the workspace. All existing links will still work, but they will no longer be associated with this folder.

Inputs: id (required), account, confirm.

delete_tagDelete a tagA
Destructive

Delete a tag from the workspace. All existing links will still work, but they will no longer be associated with this tag.

Inputs: id (required), account, confirm.

get_customerRetrieve a customerA
Read-onlyIdempotent

Retrieve a customer by ID for the authenticated workspace. To retrieve a customer by external ID, prefix the ID with ext_.

Inputs: id (required), account, include_expanded_fields.

get_operation_schemaInspect a current native operationB
Read-onlyIdempotent

Local reviewed method/path/query/body schema and provenance for one native tool. No credentials or provider request.

Inputs: operation (required).

get_qr_codeRetrieve a QR codeC
Destructive

Retrieve a QR code for a link.

Inputs: url (required), output_file (required), logo, size, +8 more.

list_accountsList configured accountsB
Read-onlyIdempotent

Local profile labels/default/auth method only. No keys, token paths, provider identity or network request.

Inputs: no named parameters.

list_bounty_submissionsList bounty submissionsB
Read-onlyIdempotent

List all submissions for a specific bounty in your partner program.

Inputs: bounty_id (required), page, status, account, +5 more.

list_commissionsList all commissionsB
Read-onlyIdempotent

Retrieve a paginated list of commissions for your partner program.

Inputs: end, page, type, query, +18 more.

list_customersList all customersB
Read-onlyIdempotent

Retrieve a paginated list of customers for the authenticated workspace.

Inputs: page, email, search, account, +11 more.

list_discount_codesList discount codesA
Read-onlyIdempotent

Retrieve a paginated list of discount codes in a program or filtered by partner, discount, or code.

Inputs: code, page, account, page_size, +2 more.

list_domainsList all domainsB
Read-onlyIdempotent

Retrieve a paginated list of domains for the authenticated workspace.

Inputs: page, search, account, archived, +1 more.

list_eventsList all eventsC
Read-onlyIdempotent

Retrieve a paginated list of events for the authenticated workspace.

Inputs: os, qr, end, key, +41 more.

list_foldersList all foldersB
Read-onlyIdempotent

Retrieve a paginated list of folders for the authenticated workspace.

Inputs: page, search, account, page_size.

list_partnersList all partnersC
Read-onlyIdempotent

List all partners for a partner program.

Inputs: page, email, search, status, +7 more.

list_payoutsList all payoutsB
Read-onlyIdempotent

Retrieve a paginated list of payouts for your partner program.

Inputs: page, status, account, sort_by, +6 more.

list_program_applicationsList all program applicationsA
Read-onlyIdempotent

Retrieve a paginated list of applications for your partner program. Filter by status to list pending, approved, or rejected applications.

Inputs: page, search, status, account, +4 more.

list_tagsList all tagsB
Read-onlyIdempotent

Retrieve a paginated list of tags for the authenticated workspace.

Inputs: ids, page, search, account, +3 more.

register_domainRegister a domainA
Destructive

Register a domain for the authenticated workspace. Only available for Enterprise Plans.

Inputs: domain, account, confirm, payload, +1 more.

reject_bounty_submissionReject a bounty submissionC
Destructive

Reject a bounty submission with a specified reason and optional note.

Inputs: bounty_id (required), submission_id (required), account, confirm, +4 more.

reject_program_applicationReject a partner applicationA
Destructive

Reject a pending partner application to your program. The partner will be notified via email that their application was not approved.

Inputs: account, confirm, payload, partnerId, +6 more.

retrieve_partner_analyticsRetrieve analytics for a partnerB
Read-onlyIdempotent

Retrieve analytics for a partner within a program. The response type vary based on the groupBy query parameter.

Inputs: end, query, start, account, +5 more.

track_leadTrack a leadD
Destructive

Track a lead for a short link.

Inputs: mode, account, clickId, confirm, +9 more.

track_openTrack a deep link open eventC
Destructive

This endpoint is used to track when a user opens your app via a Dub-powered deep link (for both iOS and Android).

Inputs: account, confirm, payload, deepLink, +2 more.

track_saleTrack a saleC
Destructive

Track a sale for a short link.

Inputs: amount, account, clickId, confirm, +12 more.

update_commissionUpdate a commissionA
Destructive

Update an existing commission amount. This is useful for handling refunds (partial or full) or fraudulent sales.

Inputs: id (required), amount, status, account, +8 more.

update_customerUpdate a customerC
Destructive

Update a customer for the authenticated workspace.

Inputs: id (required), name, email, avatar, +9 more.

update_domainUpdate a domainC
Destructive

Update a domain for the authenticated workspace.

Inputs: slug (required), logo, account, confirm, +8 more.

update_folderUpdate a folderC
Destructive

Update a folder in the workspace.

Inputs: id (required), name, account, confirm, +4 more.

update_tagUpdate a tagC
Destructive

Update a tag in the workspace.

Inputs: id (required), tag, name, color, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 61 tools

    Disambiguation4/5

    Most tools target a distinct resource+action, and descriptions clarify boundaries well. Some pairs invite confusion—create_link vs upsert_link vs bulk_create_links, and preview_link_batch vs submit_link_batch vs bulk_create_links—but they are separable with careful reading.

    Naming Consistency4/5

    Predominantly consistent verb_noun snake_case (create_tag, list_folders, delete_domain, bulk_update_links). Minor deviations: mixing get_ vs retrieve_ (get_link vs retrieve_partner_links, retrieve_partner_analytics) and a few irregular forms like get_links_count.

    Tool Count2/5

    61 tools is very heavy for a single server, well into the too-many range. The domain (links, tags, folders, domains, partners, commissions, payouts, bounties, discount codes, customers, tracking, plus meta-tools) is genuinely broad, which softens but does not justify the volume.

    Completeness4/5

    Strong lifecycle coverage: full CRUD for links, tags, folders, and domains, plus partner/commission/bounty workflows. Minor gaps exist—payouts are list-only, discount codes lack an update, and there is no explicit create_customer (customers appear upserted via tracking).

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables users to shorten links, bulk-create URLs, generate QR codes, and retrieve click analytics through MCP clients such as Claude, ChatGPT, Cursor, and n8n.
      9
      47 npm
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      Enables AI agents and terminal clients to manage subscribers, draft campaigns, workflows, custom fields, webhooks, and private account profiles with shared read/write safeguards.
      32
      25 npm
      AGPL 3.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to run a QRTap workspace end to end: create and edit QR codes and short links, publish public pages, moderate guest reviews, manage booking requests, and configure conditional redirects, with anonymous scan analytics. It also supports bulk code issuance and print-ready PNG, SVG, and PDF artifacts.
      20
      68 npm
      MIT