How do I use Dub MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Dub MCP Server create a short link for https://example.com and show its click stats" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Dub MCP Server

by thenavidm

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Dub MCP Server & CLI

npm License YouTube 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. 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: filoo 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

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	Surface choice and pending usage evidence
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

Sign into the intended Dub workspace. Open Settings → API Keys / tokens. Verify the workspace before copying a key.
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.
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.
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.
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, no prompt/color; --yes does not approve writes
--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
2	Invalid input or refused 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

Fresh matched successful Codex task/token measurements are pending. Tool counts, schema characters, another client's results and --select are not an efficiency percentage. Measure actual client/model/package versions, loading mode, comparable successful task, API quota, input/output/cache usage and latency. Claude Code benchmarking remains deferred; it is optional for current Codex work.

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

create_link

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	Must be true for the requested mutation or exclusive private output file.
`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.

list_links

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.

get_links_count

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.

get_link

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.

update_link

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	Must be true for the requested mutation or exclusive private output file.
`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.

delete_link

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	Must be true for the requested mutation or exclusive private output file.

bulk_create_links

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	Must be true for the requested mutation or exclusive private output file.
`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.

bulk_update_links

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	Must be true for the requested mutation or exclusive private output file.
`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.

bulk_delete_links

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	Must be true for the requested mutation or exclusive private output file.

input.link_ids

input.link_ids[]

Native JSON value; inspect the full schema for validation.

upsert_link

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	Must be true for the requested mutation or exclusive private output file.
`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.

get_link_stats

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	Must be true for the requested mutation or exclusive private output file.
`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.

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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.

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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.

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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.

register_domain

dub-cli register-domain

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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.

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	Must be true for the requested mutation or exclusive private output file.
`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.

create_partner_link

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	Must be true for the requested mutation or exclusive private output file.
`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`.

retrieve_partner_links

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.

upsert_partner_link

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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.

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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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	Must be true for the requested mutation or exclusive private output file.
`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"].

preview_link_batch

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.

submit_link_batch

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	Explicit approval for this exact requested ordered batch.
`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.

createLink

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.

getLinks

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.

getLinksCount

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.

getLinkInfo

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.

updateLink

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.

deleteLink

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.

bulkCreateLinks

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.

bulkUpdateLinks

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.

bulkDeleteLinks

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.

upsertLink

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.

createPartnerLink

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`.

retrievePartnerLinks

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.

upsertPartnerLink

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`.

9. Link and partner workflows

Inspect and approve the intended link

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. Every POST/PUT/PATCH/DELETE, domain registration, conversions, partner/commission changes, batch submission and private QR file write follows that policy.

Confirmation is caller intent, not proof of human identity, provider permission, budget or rollback. 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, 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/API client/WriteGuard handles both surfaces. The copied house CLI uses the actual MCP server through SDK in-memory transport; local MCP uses stdio. 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

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	2.0.0
Current native API operations	57
MCP SDK	1.32.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, and its measurements are deferred.

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.

No fresh matched successful Codex task/token comparison exists. Tool counts, characters and local field filtering are not task-token savings.

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.

About the author

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. This Dub MCP server and CLI is one piece of that system.

Links

Personal website: navid.me
Link in bio: navid.bio
Navid Media: navid.media
YouTube: @thenavidm and @thenavidai
X: @thenavidm
Instagram: @thenavidm
LinkedIn: thenavidm

If this is useful, star the repo and come say hi on X.

Dependencies

Runtime: MCP TypeScript SDK, 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.

Available Tools

61 tools

approve_bounty_submissionApprove a bounty submissionC

Destructive

Approve a bounty submission. Optionally specify a custom reward amount.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`bounty_id`	Yes	The ID of the bounty
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.
`rewardAmount`	No	The reward amount for the performance-based bounty. Applicable if the bounty reward amount is not set.
`submission_id`	Yes	The ID of the bounty submission

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say the approval is irreversible, that confirm must be set, or what happens to the submission state, leaving the burden entirely on the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, action front-loaded, no filler. The second sentence is largely redundant with the schema's rewardAmount description, which slightly lowers the value density but keeps the definition tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with 7 parameters (including a nested payload object and mutually exclusive payload/payload_file inputs) and no output schema, two sentences are thin. It omits the confirm requirement, the reward-override precondition, and any note on what approval changes, leaving the agent to reconstruct behavior from annotations and schema alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across all 7 parameters, so the schema documents account, confirm, payload, payload_file and rewardAmount in detail. The description's only parameter remark ('custom reward amount') restates what the schema already says, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Approve a bounty submission') that an agent can match to the task, and the sibling names (reject_bounty_submission, list_bounty_submissions) make the intended operation unambiguous by contrast. However, the description never explicitly differentiates itself from reject_bounty_submission or states the outcome of approval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of the required 'confirm' flag, and no pointer to reject_bounty_submission as the alternative action. The only conditional hint is 'Optionally specify a custom reward amount,' which is a parameter note rather than usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`groupId`	No	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.
`payload`	No	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.
`partnerId`	No	The ID of the partner to approve.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the partner is enrolled into a specific group and notified of the approval, which tells the agent about side effects it would otherwise not know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences with the action front-loaded and the side effects second. No filler or redundancy; every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is a simple mutation whose safety profile is fully covered by annotations, its parameters by a 100%-covered schema, and there is no output schema to explain. The description covers the outcome, though it omits any prerequisite/permission context that an approval operation might warrant.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters (including the nested payload and confirm/payload_file alternatives) are already documented in the schema. The phrase 'specified group' loosely maps to groupId but adds no syntax or default detail beyond what the schema provides, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Approve a pending partner application') and adds the outcome scope (enrollment to a group, notification). It implicitly distinguishes itself from the sibling reject_program_application via the 'approve' verb, but never names that alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance is given. The word 'pending' implies it applies to open applications, but the description never points the agent to reject_program_application or list_program_applications as the routing alternatives, leaving selection to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ban_partnerBan a partnerA

Destructive

Ban a partner from your program. This will disable all links and mark all commissions as canceled.

ParametersJSON Schema

Name	Required	Description
`reason`	No	The reason for banning the partner.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`tenantId`	No	The ID of the partner in your system. If both `partnerId` and `tenantId` are not provided, an error will be thrown.
`partnerId`	No	The ID of the partner to create a link for. Will take precedence over `tenantId` if provided.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes beyond them by naming the actual side effects: all links are disabled and all commissions are marked canceled. That is genuine disclosure of destructive scope. It does not mention the confirm=true gate, so it falls short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two lean sentences, the purpose front-loaded and the consequence immediately after. Nothing redundant or padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with a nested payload, 100% schema coverage, and no output schema, the description covers purpose and effect well. The one meaningful omission is the confirm=true requirement for the mutation, which an agent only learns from the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents reason, account, confirm, payload, and the partnerId/tenantId precedence rules. The description adds no parameter-level meaning beyond that, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Ban a partner from your program') and adds the concrete effect (disables links, cancels commissions), which helps distinguish it from the sibling deactivate_partner. However, it never explicitly contrasts itself with deactivate_partner or the other partner tools, so an agent still has to infer the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of the close alternative deactivate_partner that sits right beside it in the tool list. The agent must guess whether banning or deactivating is the correct escalation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bulk_create_linksBulk create linksB

Destructive

Bulk create up to 100 links for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the risky mutation profile is covered. The description usefully adds the 100-link ceiling and workspace scoping, but says nothing about partial-batch failure behavior or the confirm flag's necessity beyond what the schema states.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence with the key constraint (up to 100) front-loaded and no filler. It stops earning its place only because it omits routing and failure information that the same sentence count could have carried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a bulk, non-idempotent, destructive mutation, an agent still needs to know how partial failures are reported and what the response contains, and there is no output schema to fall back on. Annotations cover the safety profile, but the batch-error semantics are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the parameter semantics baseline is 3. The description does contribute one genuinely non-schema detail — the 100-item cap, since payload has no maxItems — but adds nothing about account, confirm, or payload_file interplay.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (bulk create) and resource (links), plus the batch cap of 100 and the authenticated-workspace scope. It implicitly separates itself from create_link and bulk_update_links, but names no sibling explicitly, so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of alternatives (create_link for singles, preview_link_batch/submit_link_batch for the async path), and no stated prerequisites. The single sentence describes the operation, not the situation that selects it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bulk_delete_linksBulk delete linksB

Destructive

Bulk delete up to 100 links for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`link_ids`	Yes	Comma-separated list of link IDs to delete. Maximum of 100 IDs. Non-existing IDs will be ignored.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is largely covered. The description adds the useful 100-item cap and the workspace scoping, but says nothing about irreversibility, the confirm requirement, or that non-existent IDs are silently ignored (those live only in the schema).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no waste. It is appropriately sized, though it is so terse that it sacrifices some context in the name of brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with no output schema, the annotations carry the safety signal and the schema fully covers parameters, so the description is minimally sufficient. It still omits any note about irreversibility or the confirm guard, leaving the agent to read the schema for critical call behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so account, confirm, and link_ids are fully documented in the schema itself. The description only echoes the 100-ID limit already stated for link_ids, adding no new parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Bulk delete links') with scope ('up to 100', 'authenticated workspace'). This implicitly separates it from the single-item delete_link and from bulk_update_links, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to choose this over delete_link (single) or bulk_update_links, and no stated prerequisites beyond the implicit need for authentication. The 'up to 100' limit hints at batching, but the agent must infer when bulk is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bulk_update_commissionsBulk update commissionsB

Destructive

Bulk update up to 100 commissions with the same status.

ParametersJSON Schema

Name	Required	Description
`status`	No	The status to apply to every commission in the batch.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.
`commissionIds`	No

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description usefully adds the batch constraint that every commission receives the identical status, but it omits the confirm=true requirement, the account scoping, and the mutual exclusivity of payload vs payload_file — meaningful for a destructive batch mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One short sentence with the scope constraint front-loaded and no filler. It is efficiently sized, though its brevity comes at the cost of the details flagged in other dimensions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive bulk mutation with a nested payload, a confirm gate, an account parameter, and an alternate payload_file path — and no output schema — the description is too thin. An agent must get the exclusivity rules, the confirm requirement, and the account semantics entirely from the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 83%, so the schema already documents almost all parameters, including the payload/commissionIds constraints and the confirm flag. The description adds only the 'same status' and 'up to 100' framing, which largely restates the enum and maxItems already in the schema, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (bulk update), resource (commissions), and scope (up to 100, same status), which cleanly separates it from the singular update_commission and from bulk_update_links. It doesn't explicitly name the alternative sibling, but the batch/same-status framing makes the intent unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance or when-not guidance. 'With the same status' implicitly signals that per-record statuses require update_commission, but the agent must infer this rather than being told, and no prerequisites (confirm, account, payload exclusivity) are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bulk_update_linksBulk update linksB

Destructive

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

ParametersJSON Schema

Name	Required	Description
`data`	No
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`linkIds`	No	The IDs of the links to update. Takes precedence over `externalIds`.
`payload`	No	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.
`externalIds`	No	The external IDs of the links to update as stored in your database.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the meaningful trait that all targeted links receive identical data and the 100-link ceiling, but it omits the confirm-required gating, whether unspecified fields are overwritten or left intact, and partial-failure behavior. Given the annotations carry the safety burden, a 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler; the verb, limit, and scope arrive immediately. It is efficient, though one clause ('for the authenticated workspace') is near-redundant given the account parameter, keeping it just short of a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a destructive bulk mutation with 7 top-level parameters, nested data objects, three mutually exclusive body-delivery paths (payload, payload_file, inline flags), and a confirm requirement — yet the description is one sentence that never mentions any of this. With no output schema, the description should at least warn about the exclusivity rules and confirm gating; it does not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 86%, well above the 80% threshold, so the schema already documents the payload fields, linkIds/externalIds precedence, and confirm semantics in detail. The description adds no parameter-level meaning (no mention of linkIds vs externalIds, payload vs payload_file, or the confirm flag), so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb (bulk update), resource (links), and scope (up to 100 links, same data, authenticated workspace), which clearly separates it from the singular update_link and from bulk_create_links/bulk_delete_links. It stops short of explicitly naming a sibling or the alternative path an agent should consider, so it lands just below the top band.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'with the same data' implicitly signals the bulk-set semantics that distinguish this from per-link update tools, which is useful context. However, no explicit when-to-use/when-not guidance, no prerequisites, and no named alternative (e.g. upsert_link for mixed create/update) are given, so usage must be inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`domains`	Yes	The domains to search. We only support .link domains for now.

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the purchase-oriented framing but says nothing about rate limits, auth requirements, or how unregistered/invalid domains are reported.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core action and with zero filler. Nothing could be removed without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only lookup with no output schema, the description plus annotations and full schema coverage give an agent what it needs to invoke the tool. The only omission is a note about the .link-only limitation, which the schema already carries.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (account, domains) are already documented, including the .link-only restriction. The description's 'multiple domains at once' only restates the array support already expressed in the schema's anyOf, adding no new semantics. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Check') and resource ('domain name') with the qualifying outcome ('available for purchase'), which separates it from register_domain/create_domain siblings that act on domains. It stops short of naming those siblings, but the pre-purchase intent is clear enough to route correctly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'available for purchase' implies this is the lookup step before registration, but the description never states when to use this versus register_domain or list_domains, nor any exclusions. Usage is inferable rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_commissionCreate commissionA

Destructive

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the write/destructive/non-idempotent profile, so the bar is lower, yet the description adds a genuinely important behavioral trait: creation is asynchronous and requires polling or webhooks. It also flags the clawback behavior (negative amount). It does not mention the `confirm` mutation gate, which would have been useful context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: creation scope first, key edge case (clawback) second, asynchronous follow-up last. Every sentence earns its place with no padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-branch, nested payload schema with no output schema, the description adequately orients the agent (types, clawback rule, async result handling). It stops short of explaining what each branch requires or the confirm/account prerequisites, but the schema covers those, so the gap is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and nested branches are fully documented inline, so the schema carries parameter meaning. The description only echoes the negative-`amount`/clawback rule already in the schema and lists the three type values, adding no new syntax or format detail. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create ... commissions') and enumerates the three supported commission types (custom, lead, sale), which an agent can map to the oneOf branches. This clearly distinguishes it from the create-adjacent siblings list_commissions, update_commission, and bulk_update_commissions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides post-creation guidance (async processing; poll GET /commissions or use webhooks) but never states when to reach for this tool versus the semantically overlapping track_lead/track_sale or update_commission. Usage is implied by the verb/resource rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_discount_codeCreate a discount codeA

Destructive

ParametersJSON Schema

Name	Required	Description
`code`	No	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.
`linkId`	No	The ID of the partner's referral link to associate this discount code with. Each link can only have one discount code.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`partnerId`	No	The ID of the partner to create a discount code for.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context in the form of business-rule preconditions not present in the schema or annotations, though it does not restate the confirm/destructive requirement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with zero filler; the core action is front-loaded and the preconditions follow immediately. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with no output schema, the description supplies the key precondition rules an agent needs before calling. The main residual gap is that it does not surface the confirm-must-be-true requirement or the irreversibility implied by destructiveHint, but annotations carry that load.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents code, linkId, partnerId, account, confirm, payload, and payload_file in detail. The description adds no parameter syntax or format information beyond what is already structured, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Create) and resource (discount code) and adds scope ('for a partner'), which cleanly separates it from siblings like list_discount_codes and delete_discount_code. It stops short of explicitly naming an alternative tool, so it is clear but not maximally distinguishing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives two concrete preconditions for a successful call: the partner's group must already have a discount assigned, and the target link must not already carry another discount code. These are actionable when-to-use constraints, though no alternative tool is named for the failure cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_domainCreate a domainC

Destructive

Create a domain for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description
`logo`	No
`slug`	No	Name of the domain.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`archived`	No	Whether to archive this domain. `false` will unarchive a previously archived domain.
`assetLinks`	No	assetLinks.json configuration file (for deep link support on Android).
`expiredUrl`	No	Redirect users to a specific URL when any link under this domain has expired.
`notFoundUrl`	No	Redirect users to a specific URL when a link under this domain doesn't exist.
`placeholder`	No	Provide context to your teammates in the link creation modal by showing them an example of a link to be shortened.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.
`appleAppSiteAssociation`	No	apple-app-site-association configuration file (for deep link support on iOS).

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds nothing beyond that: it never mentions the required `confirm` flag, slug uniqueness, side effects such as archiving, or the payload/body-flag exclusivity rules.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler or redundancy. It is efficient, though its brevity borders on insufficiency for a 12-parameter destructive tool rather than being a fault of structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required, 12-parameter, nested-object, destructive mutation with no output schema, one sentence is inadequate. It omits the confirm requirement, the payload-vs-flags exclusivity constraint, and any notion of what a domain represents or what creating one affects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 92% across 12 parameters, so the schema already carries the parameter semantics (slug, logo, archived, redirect URLs, confirm, payload_file, etc.). The description adds no parameter meaning, which is the baseline 3 when schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a domain') plus a scope qualifier ('for the authenticated workspace'), so the intent is unambiguous. However, it offers no differentiation from the many sibling domain tools — register_domain, update_domain, delete_domain — which an agent must distinguish before calling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no prerequisites, no alternatives named. The mention of 'authenticated workspace' hints at auth scope but does not tell the agent when to pick create_domain over register_domain or how it relates to list_domains/update_domain.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_folderCreate a folderB

Destructive

Create a folder for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description	Default
`name`	No	The name of the folder.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`accessLevel`	No	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.	write
`description`	No	The description of the folder.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive=true, idempotent=false, readOnly=false and openWorld=true, so the safety profile is covered. The description's only added context is that the folder is scoped to the authenticated workspace; it says nothing about the confirm gate, permission requirements, or what happens on repeat calls. That small scoping detail earns a 3 rather than a 2.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler, restated name, or redundant phrasing. Nothing to trim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter tool with a nested payload object, three mutually exclusive body-passing modes (payload, flat flags, payload_file), a required confirm flag, and no output schema, one generic sentence leaves the agent guessing. Nothing explains the body-mode duality, the confirm requirement, or plan-gated accessLevel values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema itself documents name, accessLevel, description, account, confirm, payload and payload_file, including the enum on accessLevel. The description adds no parameter meaning beyond that, which is the expected baseline of 3 when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The sentence names a specific verb (Create) and resource (folder) plus a scope (the authenticated workspace), so the agent knows exactly what operation it is. It does not differentiate itself from siblings like update_folder/delete_folder or list_folders, but the name already carries that distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as upserting or updating an existing folder. The agent must infer usage entirely from the name and schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_linkCreate a linkC

Destructive

Create a link for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description
`geo`	No	Geo targeting information for the short link in JSON format `{[COUNTRY]: https://example.com }`. See https://d.to/geo for more information.
`ios`	No	The iOS destination URL for the short link for iOS device targeting.
`key`	No	The short link slug. If not provided, a random 7-character slug will be generated.
`ref`	No	The referral tag of the short link. If set, this will populate or override the `ref` query parameter in the destination URL.
`url`	No	The destination URL of the short link.
`image`	No	The custom link preview image (og:image). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
`proxy`	No	Whether the short link uses Custom Link Previews feature. Defaults to `false` if not provided.
`tagId`	No	Deprecated: Use `tagIds` instead. The unique ID of the tag assigned to the short link.
`title`	No	The custom link preview title (og:title). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
`video`	No	The custom link preview video (og:video). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
`domain`	No	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).
`prefix`	No	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.
`tagIds`	No	The unique IDs of the tags assigned to the short link.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`android`	No	The Android destination URL for the short link for Android device targeting.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`doIndex`	No	Allow search engines to index your short link. Defaults to `false` if not provided. Learn more: https://d.to/noindex
`payload`	No	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.
`rewrite`	No	Whether the short link uses link cloaking. Defaults to `false` if not provided.
`archived`	No	Whether the short link is archived. Defaults to `false` if not provided.
`comments`	No	The comments for the short link.
`folderId`	No	The unique ID existing folder to assign the short link to.
`password`	No	The password required to access the destination URL of the short link.
`tagNames`	No	The unique name of the tags assigned to the short link (case insensitive).
`tenantId`	No	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.
`utm_term`	No	The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL.
`expiresAt`	No	The date and time when the short link will expire at.
`keyLength`	No	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`.
`partnerId`	No	The ID of the partner the short link is associated with.
`programId`	No	The ID of the program the short link is associated with.
`expiredUrl`	No	The URL to redirect to when the short link has expired.
`externalId`	No	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.
`utm_medium`	No	The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL.
`utm_source`	No	The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL.
`webhookIds`	No	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.
`description`	No	The custom link preview description (og:description). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
`publicStats`	No	Deprecated: Use `dashboard` instead. Whether the short link's stats are publicly accessible. Defaults to `false` if not provided.
`utm_content`	No	The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.
`testVariants`	No	An array of A/B test URLs and the percentage of traffic to send to each URL.
`utm_campaign`	No	The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL.
`testStartedAt`	No	The date and time when the tests started.
`testCompletedAt`	No	The date and time when the tests were or will be completed.
`trackConversion`	No	Whether to track conversions for the short link. Defaults to `false` if not provided.

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered by structured data. The description adds only the workspace scope and omits behaviorally important details the schema hints at, such as the `confirm` requirement for the mutation and the payload vs. body-flag exclusivity rules.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with no filler, and the resource is front-loaded. It is efficient, though its brevity edges toward under-specification rather than true conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a high-complexity mutation tool with 44 parameters, nested objects, mutually exclusive body forms, and no output schema, yet the description conveys only that a link is created. An agent is left to infer the confirm requirement, payload exclusivity, and the difference from upsert_link entirely from the schema and annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every one of the 44 parameters is already documented in the schema, and the baseline for this case is 3. The description contributes nothing about parameters (e.g., that `url` is the core destination or how `payload`/`payload_file` interact), so it neither helps nor hurts.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a clear verb+resource ('Create a link') and scopes it to 'the authenticated workspace', so an agent knows what operation it performs. However, it does nothing to distinguish this from siblings like upsert_link, bulk_create_links, or create_partner_link, which all sound like link creation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance at all. With upsert_link and bulk_create_links in the sibling set, the agent gets no signal about when a single create is preferable, nor any note about prerequisites such as the `confirm` flag or workspace context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_partnerCreate or update a partnerA

Destructive

ParametersJSON Schema

Name	Required	Description
`name`	No	The partner's full name. If undefined, the partner's email will be used in lieu of their name (e.g. `john@acme.com`)
`email`	No	The partner's email address. Partners will be able to claim their profile by signing up at `partners.dub.co` with this email.
`image`	No	The partner's avatar image. If not provided, a default avatar will be used.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`country`	No	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.
`groupId`	No	The group ID to add the partner to. If not provided, the partner will be added to the default group.
`payload`	No	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.
`tenantId`	No	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.
`username`	No	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.
`linkProps`	No	Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.
`description`	No	A brief description of the partner and their background. Max 5,000 characters.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds genuine behavioral context the annotations cannot convey: the email-keyed deduplication and that an existing partner's program enrollment is updated rather than a duplicate being created. It omits auth/permission needs and the role of the confirm flag.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the upsert nature, with zero filler. Minor redundancy in restating the create-vs-update outcome after the opening sentence, but every sentence contributes concrete detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter tool with nested objects and no output schema, the description covers the core conceptual model (email-keyed upsert) that an agent most needs. It leaves the flat-params-versus-payload duality and the confirm requirement to the schema, which documents them, so the gap is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: email is the identity key driving the upsert, and tenantId is what gets written to an existing enrollment. Other params (linkProps, payload, account) rely entirely on schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Creates or updates a partner record') and immediately characterizes the operation as upsert, which is more precise than the title alone. It does not explicitly distinguish itself from siblings like list_partners or ban_partner, but the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the branch condition (same email exists → update enrollment; otherwise → create), which implies when each behavior fires. However, it gives no guidance on when an agent should call this versus other partner tools, nor any preconditions or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_partner_linkCreate a link for a partnerC

Destructive

Create a link for a partner that is enrolled in your program.

ParametersJSON Schema

Name	Required	Description
`key`	No	The short link slug. If not provided, a random 7-character slug will be generated.
`url`	No	The URL to shorten (if not provided, the program's default URL will be used).
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`comments`	No	The comments for the short link.
`tenantId`	No	The ID of the partner in your system. If both `partnerId` and `tenantId` are not provided, an error will be thrown.
`linkProps`	No	Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.
`partnerId`	No	The ID of the partner to create a link for. Will take precedence over `tenantId` if provided.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond the title - no note that the partner must pre-exist, what happens on duplicate slugs, or that the request requires confirmation. It merely restates the purpose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence that is front-loaded with the verb. It is efficiently sized, though it is arguably so terse that it borderlines on under-specification rather than genuine conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter mutation tool with nested objects, no output schema, and many overlapping sibling tools, this description is far too thin. It omits prerequisites, the relationship to upsert_partner_link/create_link, and any behavior of key parameters like confirm or partnerId/tenantId exclusivity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 10 parameters (key, url, account, confirm, payload, linkProps, partnerId, tenantId, etc.) are fully documented in the schema, making the baseline 3 appropriate. The description contributes no additional parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb+resource ('Create a link for a partner') and adds the scoping qualifier 'enrolled in your program', which distinguishes it somewhat from the generic create_link sibling. However, it never names or contrasts with the closely related upsert_partner_link or create_link, so differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus the many link-creation siblings (create_link, upsert_partner_link, bulk_create_links). The only hint is the 'enrolled in your program' precondition, which is not framed as a decision rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_referrals_embed_tokenCreate a referrals embed tokenA

Destructive

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`partner`	No
`payload`	No	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.
`tenantId`	No
`partnerId`	No
`output_file`	Yes	Required absolute new private file. Exclusive 0600 creation; never overwrites or echoes PNG/embed credentials.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive/non-idempotent/open-world behavior, but the description adds a genuinely useful side-effect disclosure: this is an upsert that may silently create a new enrollment when none exists. It omits auth/permission requirements and the confirm gating, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the action, then the resolution logic, then the outcome. No filler, though the final 'guarantees a valid enrollment and returns a usable embed token' is slightly redundant with the earlier upsert description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-param tool with nested objects and no output schema, the description covers the core flow but leaves out the required output_file's exclusive-file semantics, the confirm gating, and how the token is delivered. Adequate but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 63% and the description adds real meaning for tenantId (used to locate an existing enrollment) and the partner email (used to resolve the partner). However, key params like account, confirm, output_file, payload, and payload_file receive no explanation beyond the schema, so it only partially compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Create a referrals embed token') and then details the exact resolution flow (enrollment lookup by tenantId, fallback to partner email, upsert). No sibling tool does anything comparable, so the agent can place it immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the internal two-path logic (existing enrollment vs create-new), which implies the input conditions, but it never says when to prefer this tool, what prerequisites it has, or what it replaces. Usage is inferable rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_tagCreate a tagB

Destructive

Create a tag for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description
`tag`	No	The name of the tag to create.
`name`	No	The name of the tag to create.
`color`	No	The color of the tag. If not provided, a random color will be used from the list: red, yellow, green, blue, purple, brown, gray.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the 'authenticated workspace' scoping detail, and says nothing about duplicate-name handling, reversibility, or that confirm must be set.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler or redundancy. It is efficiently written, though its brevity is also its weakness given the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation tool with nested payload objects, a deprecated alias, and no output schema, one sentence is inadequate. The description does not explain the payload vs body-flag choice, the confirm requirement, or what a successful creation returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all seven parameters (including the deprecated 'tag', the payload/payload_file alternatives, and the confirm gate) are self-documented. The description adds nothing beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a tag') and scopes it to the authenticated workspace. It is clearly distinguishable from update_tag/delete_tag/list_tags by the verb, though it never explicitly names them as alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no guidance on when to use this tool versus update_tag or upsert-style siblings, and no prerequisites. The presence of 'confirm', 'account', and payload-vs-flags options implies important preconditions that the description never surfaces.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`tenantId`	No	The ID of the partner in your system. If both `partnerId` and `tenantId` are not provided, an error will be thrown.
`partnerId`	No	The ID of the partner to create a link for. Will take precedence over `tenantId` if provided.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, but the description adds real value beyond them: it names the precise blast radius (all active links disabled) and explicitly states what is NOT destroyed (commissions and payouts remain intact), plus reversibility. It stops short of 5 by saying nothing about the confirm requirement or authorization needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, zero filler, with the action and its primary effect front-loaded and the non-destructive guarantees following. Every sentence carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter destructive mutation with no output schema, the description covers the outcome, the collateral effect, and reversibility well. It omits how the operation is confirmed (the confirm flag) and how errors are reported when neither partnerId nor tenantId is supplied, leaving those to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-level detail at all, and notably does not correct the schema's misleading partnerId text ('the ID of the partner to create a link for'), which is a copy-paste artifact from a sibling tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('deactivate the partner from your program') plus the concrete side effect of disabling active links, so the agent knows exactly what happens. It does not differentiate from the sibling ban_partner, which is the closest alternative, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'You can reactivate them later if needed' implies this is the reversible/softer option, which is useful context for choosing it. However, there is no explicit when-to-use guidance and no comparison to ban_partner or delete_partner-style siblings, leaving the agent to infer the boundary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_customerDelete a customerB

Destructive

Delete a customer from a workspace.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	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	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds workspace scoping but does not disclose irreversibility, required confirmation, or side effects beyond what the annotations imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no wasted words. It is appropriately concise for a simple delete operation, though its brevity borders on under-specification.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description identifies the action and workspace scope, while annotations cover the destructive and non-idempotent nature of the call. It does not mention the required confirm flag or deletion consequences, but the schema and annotations supply enough for an agent to proceed correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the id, account, and confirm parameters in detail. The description adds no additional parameter meaning beyond the workspace scope hint.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Delete) and resource (customer) with workspace scope, so an agent knows exactly what action it performs. It does not distinguish this tool from other delete siblings such as delete_domain or delete_link beyond the resource name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this tool versus alternatives like update_customer, deactivate_partner, or list_customers. The usage is only implied by the tool name and one-line action statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_discount_codeDelete a discount codeA

Destructive

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`id_or_code`	Yes	The unique ID (e.g. `dcode_...`) or alphanumeric code (e.g. `ABC123`) of the discount code to delete.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: the deletion propagates to the connected discount provider (Stripe, Shopify, or a custom `disccount.deleted` webhook), which an agent could not infer from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action, then the propagation side effect. No filler or redundant restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with no output schema, the description plus annotations cover the essentials, including the cross-provider effect. It is slightly thin on irreversibility and on what the required `confirm` flag implies operationally, but nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the ID/code format and the `account`/`confirm` semantics are already documented in the schema. The description restates the id_or_code duality but adds nothing about `account` or the `confirm` gate, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Delete) and resource (discount code), and further scopes it to 'a partner by its unique ID or alphanumeric code'. Easily distinguished from create_discount_code, list_discount_codes, and the other delete_* siblings that target different resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description never says when to delete versus alternative actions (e.g., leaving a code active or updating it), nor mentions prerequisites like the required `confirm=true`. Usage must be inferred entirely from the verb.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description
`slug`	Yes	The domain name.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral facts beyond the annotations: the action is irreversible and it cascades to delete every link on the domain. It stops short of noting permission requirements or what the response returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short clauses, front-loaded with the action, then irreversibility, then blast radius. Every sentence carries information and nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with no output schema and only a full-coverage schema for parameters, the description supplies the two things an agent most needs: permanence and cascade scope. It would be complete if it also flagged the required confirmation parameter and any permission constraints.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so slug, account and confirm are already documented in the schema, making 3 the baseline. The description adds no syntax, format, or confirmation requirements of its own — notably it never mentions that a 'confirm' flag must be set for the mutation to proceed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Delete a domain from a workspace') so an agent immediately knows the operation and target, and the cascade note sharpens what the resource means. It does not explicitly contrast itself with the other delete_* siblings, but the unique resource name makes misselection unlikely.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'It cannot be undone' implicitly tells the agent this is only for permanent removal, which is real usage context. However, it never names an alternative or a circumstance in which to prefer something else (e.g., update_domain, or removing links individually), so guidance is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	The ID of the folder to delete.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered elsewhere. The description still adds real value by disclosing the non-obvious side effect: links survive deletion but lose their folder association, which is not derivable from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the purpose is front-loaded and the side-effect caveat follows immediately. No filler, no redundancy with the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-param destructive tool with no output schema, the description covers the essential irreversible side effect and annotations carry the safety profile. It stops short of noting the confirm gate or whether deletion is recoverable, but the core is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents id, account, and confirm (including the 'must be true' constraint). The description adds nothing about parameters, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Delete a folder from the workspace'), which clearly separates it from delete_link, delete_tag, and delete_domain. However, it doesn't explicitly route the agent against sibling folder operations like update_folder or the broader delete family.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus alternatives, no prerequisites, and no mention that the 'confirm' parameter must be set true before the mutation will succeed. The agent gets no usage context beyond the verb.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_linkDelete a linkC

Destructive

Delete a link for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`link_id`	Yes	The id of the link to delete. You may use either `linkId` (obtained via `/links/info` endpoint) or `externalId` prefixed with `ext_`.

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds only the workspace scoping clause and says nothing about irreversibility, the required confirm=true gate, or what a successful deletion returns – very little value beyond structured data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short, front-loaded sentence with no filler. It is economical, though its brevity is as much under-specification as conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter delete with full annotation and schema coverage and no output schema, the definition is minimally adequate. It omits the confirm gate and any consequence of deletion, which matter for a destructive operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including the linkId vs ext_-prefixed externalId distinction and the confirm requirement, so the schema carries the parameter burden. The description adds no parameter meaning whatsoever, which is the correct baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (delete) and resource (link), and scopes it to the authenticated workspace. It does not, however, distinguish itself from the sibling bulk_delete_links, which is the most plausible confusion for an agent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance and no mention of alternatives. The sibling list contains bulk_delete_links, and nothing here tells the agent to pick the single-item tool over the bulk one when removing one link.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	The ID of the tag to delete.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (destructiveHint=true, idempotentHint=false, readOnlyHint=false), so the bar is lower, and the description clears it by disclosing the real-world side effect: links survive but lose their tag association. It stops short of stating whether the deletion is permanent/reversible or that the `confirm` flag must be true, which would have made it a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the core action front-loaded and the consequence following. Every sentence earns its place and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with no output schema, the description tells the agent what happens to dependent links, which is the key unknown. It does not address reversibility, error cases, or the confirm requirement, but annotations plus the 100%-covered schema fill most of the remaining gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and all three parameters (id, account, confirm) are documented in the schema, so the baseline is 3. The description adds no additional meaning about which ID is expected or how the workspace profile and confirm flag interact with the deletion.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Delete a tag from the workspace"), which is clearly distinct from the other delete_* siblings (delete_link, delete_domain, delete_folder) by resource name. The description itself does not explicitly call out that distinction, so it lands just shy of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No indication of when to use this tool versus update_tag, delete_folder, or removing tags from individual links. It also omits any prerequisite or workflow context (e.g., confirming before destructive removal), leaving the agent to infer usage entirely.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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_.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	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	Exact configured private workspace profile label; not a tenant or provider account ID.
`include_expanded_fields`	No	Whether to include expanded fields on the customer (`link`, `partner`, `discount`).

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the workspace-scoping constraint, but says nothing about rate limits, auth prerequisites, or behavior when the ID does not exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the core action front-loaded and no filler. The second sentence largely duplicates the schema's own `id` description, a minor redundancy rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only lookup, the description plus annotations and a fully documented schema give an agent everything needed to invoke it. The absence of an output schema means the response shape is unspecified, though that is a minor gap for a get-by-ID tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters (id, account, include_expanded_fields) are already documented in the schema. The description's `ext_` prefix note restates what the `id` schema description already says, adding no new meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Retrieve a customer') plus a scope constraint ('for the authenticated workspace'). It is clearly distinguishable from sibling list_customers, update_customer, and delete_customer without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: fetch a single customer when you have an identifier, versus list_customers to enumerate. The only explicit guidance is the `ext_` prefix for external IDs. No alternatives or preconditions are named, so it stays at the minimum-viable level.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_linkRetrieve a linkC

Read-onlyIdempotent

Retrieve the info for a link.

ParametersJSON Schema

Name	Required	Description
`key`	No	The key of the link to retrieve. E.g. for `d.to/github`, the key is `github`.
`domain`	No	The domain of the link to retrieve. E.g. for `d.to/github`, the domain is `d.to`.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`link_id`	No	The unique ID of the short link.
`external_id`	No	This is the ID of the link in the your database.

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond those annotations – no note on lookup behavior when multiple identifiers are given, no indication of what happens on a miss, and no contradiction either.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler or redundancy. It is efficient, though the brevity edges into under-specification rather than crispness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Five optional parameters, no output schema, and the description says nothing about how the lookup identifiers relate, what a successful response contains, or what happens when nothing matches. For a retrieval tool with entirely optional parameters, this leaves real ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema itself gives worked examples (d.to/github -> key 'github', domain 'd.to'). With the schema doing the heavy lifting, the description earns the baseline 3 but adds no extra meaning about parameter interaction or precedence.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a verb (retrieve) and resource (link), but 'the info' is vague about what is returned, and nothing distinguishes it from siblings like list_links or get_link_stats. An agent can guess the general purpose but gets no precision about scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this instead of list_links, get_link_stats, or update_link, and crucially no explanation of which of the five optional lookup identifiers (key/domain, link_id, external_id) to supply or in what combination. This is pure 'no guidance' territory.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_links_countRetrieve links countB

Read-onlyIdempotent

Retrieve the number of links for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description
`domain`	No	The domain to filter the links by. E.g. `ac.me`. If not provided, all links for the workspace will be returned.
`search`	No	The search term to filter the links by. The search term will be matched against the short link slug and the destination url.
`tag_id`	No	Deprecated: Use `tagIds` instead. The tag ID to filter the links by.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`tag_ids`	No	The tag IDs to filter the links by.
`user_id`	No	The user ID to filter the links by.
`group_by`	No	The field to group the links by.
`folder_id`	No	The folder ID to filter the links by.
`tag_names`	No	The unique name of the tags assigned to the short link (case insensitive).
`tenant_id`	No	The ID of the tenant that created the link inside your system. If set, will only return links for the specified tenant.
`with_tags`	No	DEPRECATED. Filter for links that have at least one tag assigned to them.
`show_archived`	No	Whether to include archived links in the response. Defaults to `false` if not provided.

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the workspace scoping constraint, but says nothing about whether the 12 filter parameters change the returned count or what the response shape looks like. Adequate but thin given the annotation baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero waste. It is efficient, though its brevity comes at the cost of the guidance and filter context an agent would benefit from on a 12-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 12 optional filter parameters, grouping options, and no output schema, the description is substantially under-specified. It fails to convey that the count is shaped by the many filters, which is the key functional behavior an agent must know.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every filter (domain, search, tag_ids, group_by, show_archived, etc.), making 3 the correct baseline. The description adds no parameter meaning beyond the schema and never signals that these filters scope the count.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource ('Retrieve the number of links') and scopes it to the authenticated workspace, so an agent understands it returns a count rather than a list. It does not explicitly distinguish itself from list_links or get_link_stats, which would be the main sources of confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of sibling alternatives. An agent wanting a count vs. actually listing links (list_links) or pulling statistics (get_link_stats) gets no routing help at all.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_link_statsRetrieve analytics for a link, a domain, or the authenticated workspace.B

Read-onlyIdempotent

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

ParametersJSON Schema

Name	Required	Description	Default
`os`	No	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`.
`qr`	No	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.
`end`	No	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`.
`key`	No	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.
`url`	No	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`.
`city`	No	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`.
`root`	No	Filter for root domains. If true, filter for domains only. If false, filter for links only. If undefined, return both.
`event`	No	The type of event to retrieve analytics for. Defaults to `clicks`.	clicks
`query`	No	Search the events by a custom metadata value. Only available for lead and sale events. Examples: `metadata['key']:'value'`
`start`	No	The start date and time when to retrieve analytics from. If set, takes precedence over `interval`.
`device`	No	The device to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `Desktop`, `Mobile,Tablet`, `-Mobile`.
`domain`	No	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`.
`region`	No	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`.
`tag_id`	No	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`.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`browser`	No	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`.
`country`	No	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`.
`link_id`	No	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`.
`referer`	No	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`.
`tag_ids`	No	Deprecated: Use `tagId` instead. The tag IDs to retrieve analytics for.
`trigger`	No	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.
`group_by`	No	The parameter to group the analytics data points by. Defaults to `count` if undefined.	count
`group_id`	No	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`.
`interval`	No	The interval to retrieve analytics for. If undefined, defaults to 24h.
`timezone`	No	The IANA time zone code for aligning timeseries granularity (e.g. America/New_York). Defaults to UTC.	UTC
`utm_term`	No	The UTM term to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`).
`continent`	No	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`.
`folder_id`	No	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.
`sale_type`	No	Filter sales by type: 'new' for first-time purchases, 'recurring' for repeat purchases. If undefined, returns both.
`tenant_id`	No	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`.
`event_name`	No	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`.
`partner_id`	No	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`.
`program_id`	No	Deprecated: This is automatically inferred from your workspace's defaultProgramId. The ID of the program to retrieve analytics for.
`utm_medium`	No	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_source`	No	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`.
`customer_id`	No	The ID of the customer to retrieve analytics for.
`external_id`	No	The ID of the link in the your database. Must be prefixed with 'ext_' when passed as a query parameter.
`referer_url`	No	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`.
`utm_content`	No	The UTM content to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`).
`utm_campaign`	No	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`.
`partner_tag_id`	No	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`.

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds that the response type varies with `event` and `type` parameters, which is mildly useful, but it doesn't explain what the response shapes actually are or mention the nonexistent `type` param's role.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no padding, and the scope is front-loaded. The second sentence, however, cites a parameter that isn't in the schema, slightly undermining its value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 41-parameter analytics tool with no output schema, the description is far too thin: it doesn't explain how group_by shapes results, how the filtering modes combine, or when to prefer a sibling. Annotations cover safety, but the functional complexity is left largely unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across 41 parameters, so the schema carries the semantics and baseline is 3. The description adds nothing beyond naming `event` (already defaulted and enum-documented) and a `type` parameter that does not exist, so no extra value is provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb (Retrieve) and resource (analytics) and scopes it to a link, a domain, or the authenticated workspace. However, it offers no differentiation from siblings like retrieve_partner_analytics, and its reference to a `type` query parameter is inaccurate since no such parameter exists in the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. Given ~50 sibling tools including retrieve_partner_analytics and list_events, the absence of any routing guidance is a clear gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`operation`	Yes	Exact native tool name, e.g. create_link or approve_program_application.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, lowering the bar, yet the description adds genuinely non-obvious behavior: "No credentials or provider request" tells the agent this is a purely local lookup with no auth gate and no side-effecting provider call. "Provenance" and "reviewed" also hint that the returned schema is vetted rather than live-fetched.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with zero filler, and the payload of what is returned is front-loaded. It is slightly over-compressed, forcing the reader to parse telegraphic phrasing, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-param introspection tool with annotations covering the safety profile, the description says what is returned and that the call is local. With no output schema, it still leaves the shape of the response and the meaning of "provenance" unexplained, so it is adequate rather than complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single enum parameter is self-documenting with example values (create_link, approve_program_application). The description adds no further meaning about the operation argument beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource — "method/path/query/body schema and provenance for one native tool" — and the title verb "Inspect" frames it as introspection, which cleanly separates it from the sibling native tools it describes (create_link, approve_program_application). However, the compressed, jargon-heavy phrasing ("Local reviewed") takes a moment to decode and does not explicitly name how it relates to those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance and no condition that selects this tool over simply calling the native operation directly. The agent must infer that this is a pre-flight lookup for a named native tool, which is never stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_qr_codeRetrieve a QR codeC

Destructive

Retrieve a QR code for a link.

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes	The URL to generate a QR code for.
`logo`	No	The logo to include in the QR code. Can only be used with a paid plan on Dub.
`size`	No	The size of the QR code in pixels. Defaults to `600` if not provided.
`level`	No	The level of error correction to use for the QR code. Defaults to `L` if not provided.	L
`margin`	No	The size of the margin around the QR code. Defaults to 2 if not provided.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`bg_color`	No	The background color of the QR code in hex format. Defaults to `#ffffff` if not provided.	#FFFFFF
`fg_color`	No	The foreground color of the QR code in hex format. Defaults to `#000000` if not provided.	#000000
`hide_logo`	No	Whether to hide the logo in the QR code. Can only be used with a paid plan on Dub.
`output_file`	Yes	Required absolute new private file. Exclusive 0600 creation; never overwrites or echoes PNG/embed credentials.
`include_margin`	No	DEPRECATED: Margin is included by default. Use the `margin` prop to customize the margin size.

TDQS

C2.6/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false and destructiveHint=true, but the description's only verb, 'Retrieve,' frames the call as a harmless read. The description never discloses that the tool creates an exclusive 0600 file on disk, that confirm must be true, or that logo/hide_logo require a paid plan. The read framing actively contradicts the declared write/destructive profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single sentence is front-loaded and free of filler, but it is drastically undersized for a 12-parameter file-writing tool. It is concise only in the sense of being minimal, not in the sense of being efficiently complete.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 12 parameters, no output schema, two required args, and a destructive file write, the description omits every operational detail an agent needs. It conveys the high-level resource but leaves the file/confirm/paid-plan mechanics entirely to the schema and annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 12 parameters in detail. The description adds nothing about output_file, confirm, logo, size, level, or the deprecated include_margin, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb (retrieve), resource (QR code), and scope (for a link), so the agent can tell what the tool produces. It does not distinguish itself from any sibling, but there is no competing QR tool in the list, so a 4 is fair rather than a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use, when-not-to-use, or prerequisite guidance. Nothing tells the agent that output_file and confirm are mandatory, or that this should be preferred over any alternative. Usage is only implied by the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_accountsList configured accountsB

Read-onlyIdempotent

Local profile labels/default/auth method only. No keys, token paths, provider identity or network request.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine context beyond that: output is limited to local profile labels/defaults/auth method and deliberately excludes keys, token paths, and provider identity, telling the agent the result is safe to surface.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is very short (two fragments) and wastes no words, but it is telegraphic and front-loads a qualifier rather than the core action. The terseness borders on under-specification rather than disciplined conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only listing tool with no output schema and strong annotations, the description covers the essential safety and scope facts. However, it never plainly states what the tool does or what the returned list contains beyond field-level exclusions, leaving the purpose inferable only from the title.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is no parameter semantics for the description to carry. Baseline of 4 applies; nothing is missing on this dimension.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description never states a verb or resource — it only describes the scope of what is returned ("Local profile labels/default/auth method only"). The title supplies the actual purpose, so the agent can infer this lists local accounts, but the description itself is vague about the action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance and no named alternative among the numerous list_* siblings (list_customers, list_partners, list_domains, etc.). The agent must infer that this tool is for enumerating locally configured account profiles rather than any remote data.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_bounty_submissionsList bounty submissionsB

Read-onlyIdempotent

List all submissions for a specific bounty in your partner program.

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	The page number for pagination. The first page is `1`.
`status`	No	The status of the submissions to list.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`sort_by`	No	The field to sort the submissions by.	completedAt
`group_id`	No	The ID of the group to list submissions for.
`bounty_id`	Yes	The unique ID of the bounty on Dub. Can be found in the URL of the bounty page, prefixed with `bnty_`.
`page_size`	No	The number of items per page.
`partner_id`	No	The ID of the partner to list submissions for.
`sort_order`	No	The order to sort the submissions by.	asc

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the scoping constraint ('for a specific bounty in your partner program') and says nothing about pagination defaults, filtering behavior, or result ordering.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with zero filler and the scope stated up front. It is appropriately sized, though it errs toward being too sparse to be maximally helpful for a nine-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations covering the safety profile and a fully documented schema, the description has cover for its thinness. Still, for a tool with nine filter/sort/pagination parameters it omits any mention of the filtering capabilities or relationship to the approve/reject siblings, leaving gaps in workflow context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every one of the nine parameters is already documented (page, status, account, sort_by, group_id, partner_id, etc.). The description adds no parameter meaning beyond the schema, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (list) and resource (bounty submissions) scoped to a specific bounty in the partner program, so the agent knows exactly what it returns. It does not, however, explicitly distinguish itself from related siblings like approve_bounty_submission, reject_bounty_submission, or list_program_applications.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use or when-not-to-use guidance. The description never mentions the reviewer siblings (approve_bounty_submission, reject_bounty_submission) or when listing is preferable, leaving the agent to infer the workflow entirely.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_commissionsList all commissionsB

Read-onlyIdempotent

Retrieve a paginated list of commissions for your partner program.

ParametersJSON Schema

Name	Required	Description	Default
`end`	No	The end date of the date range to filter the commissions by.
`page`	No	DEPRECATED. Use `startingAfter` instead.
`type`	No	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"
`query`	No	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'"
`start`	No	The start date of the date range to filter the commissions by.
`status`	No	Filter the list of commissions by their corresponding status.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`sort_by`	No	The field to sort the list of commissions by.	createdAt
`group_id`	No	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"
`interval`	No	The interval to retrieve commissions for.	all
`timezone`	No
`page_size`	No	The number of items per page.
`payout_id`	No	Filter the list of commissions by the associated payout.
`tenant_id`	No	Filter the list of commissions by the associated partner's `tenantId` (their unique ID within your database).
`invoice_id`	No	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.
`partner_id`	No	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"
`sort_order`	No	The sort order for the list of commissions.	desc
`customer_id`	No	Filter the list of commissions by the associated customer.
`ending_before`	No	If specified, the query only searches for results before this cursor. Mutually exclusive with `startingAfter`.
`partner_tag_id`	No	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"
`starting_after`	No	If specified, the query only searches for results after this cursor. Mutually exclusive with `endingBefore`.
`bounty_submission_id`	No	Filter the list of commissions by the associated bounty submission.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered by structured data. The description's one addition beyond that is the paginated nature of the result set, which is useful but thin given the 22-parameter surface and cursor-based pagination the schema exposes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler or repetition. It is efficient, though the terseness is arguably under-specification for a tool with 22 parameters, which is better penalized under completeness than conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 22-parameter read tool with no output schema, the description covers the essence (paginated list of commissions) and lets the rich schema handle filters. It omits any pointer about cursor pagination (startingAfter/endingBefore) and the deprecated page parameter, which are the two areas most likely to trip up an agent, so it is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 95% across the 22 properties, so the schema already carries nearly all parameter meaning, including enum values and advanced-filter syntax. The description adds no parameter detail at all, so the baseline of 3 applies rather than a higher score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description pairs a specific verb ('Retrieve') with a specific resource ('a paginated list of commissions') and scopes it to 'your partner program'. It does not, however, distinguish this tool from sibling list tools such as list_payouts, list_partners, or list_bounty_submissions, leaving the agent to infer the difference from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus alternatives, no mention of the create_commission/update_commission/bulk_update_commissions siblings, and no guidance on scenarios or prerequisites. The only implicit hint is that results are paginated, which the agent must act on without instruction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_customersList all customersB

Read-onlyIdempotent

Retrieve a paginated list of customers for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	DEPRECATED. Use `startingAfter` instead.
`email`	No	A case-sensitive filter on the list based on the customer's `email` field. The value must be a string. Takes precedence over `externalId`.
`search`	No	A search query to filter customers by email, name, or customer ID (`cus_...`). If `email` or `externalId` is provided, this will be ignored.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`country`	No	A filter on the list based on the customer's `country` field.
`link_id`	No	A filter on the list based on the customer's `linkId` field (the referral link ID).
`sort_by`	No	The field to sort the customers by. The default is `createdAt`.	createdAt
`page_size`	No	The number of items per page.
`partner_id`	No	Partner ID to filter by.
`program_id`	No	Program ID to filter by.
`sort_order`	No	The sort order. The default is `desc`.	desc
`external_id`	No	A case-sensitive filter on the list based on the customer's `externalId` field. The value must be a string. Takes precedence over `search`.
`ending_before`	No	If specified, the query only searches for results before this cursor. Mutually exclusive with `startingAfter`.
`starting_after`	No	If specified, the query only searches for results after this cursor. Mutually exclusive with `endingBefore`.
`include_expanded_fields`	No	Whether to include expanded fields on the customer (`link`, `partner`, `discount`).

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered structurally. The description adds only the fact that results are paginated, without explaining cursor semantics, default ordering, or result limits — modest added value against an already-covered safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity means it also carries no structural guidance (ordering, pagination flow) that would earn a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter list tool with no output schema, the description is thin: it says results are paginated but not how to page through them or what the response contains. Annotations cover safety and the schema covers filters, so it is minimally adequate rather than complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 15 parameters — including precedence rules for email/search and the deprecation of page — are already documented in the schema. The description adds no filter, sorting, or pagination syntax beyond what the schema provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Retrieve a paginated list of customers') and scopes it to 'the authenticated workspace,' so the agent knows exactly what is returned. It does not, however, differentiate from sibling list tools (list_accounts, list_partners) or from the single-record get_customer, leaving that to the name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of alternatives such as get_customer for a single record, and no stated prerequisites or exclusions. The agent can only infer purpose from the name itself.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_discount_codesList discount codesA

Read-onlyIdempotent

Retrieve a paginated list of discount codes in a program or filtered by partner, discount, or code.

ParametersJSON Schema

Name	Required	Description
`code`	No	Filter discount codes by the alphanumeric code (e.g. `PARTNER10OFF`).
`page`	No	The page number for pagination. The first page is `1`.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`page_size`	No	The number of items per page.
`partner_id`	No	The ID of the partner to retrieve discount codes for. If omitted, returns discount codes for the whole program.
`discount_id`	No	Filter discount codes by discount ID.

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that results are paginated and can be scoped to a program or partner, which is modest added context but not rich behavioral detail beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficient sentence that front-loads the pagination and filtering behavior. No wasted words, though it is brief enough to leave some gaps unfilled.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with full annotation coverage and no output schema, the description covers the essential scope (paginated, filterable). It is adequate, with only minor room to describe ordering or default page-size behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all six parameters thoroughly. The description's mention of filtering by partner, discount, or code mirrors existing schema descriptions without adding format or default details, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Retrieve) and resource (discount codes) with the scope of filtering by partner, discount, or code. It is clearly a read/list operation distinguishable from create_discount_code and delete_discount_code, though it does not name those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (list codes, optionally filtered) but gives no explicit when-to-use guidance, no prerequisites, and does not point to alternative sibling tools. Guidance is inferred rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_domainsList all domainsB

Read-onlyIdempotent

Retrieve a paginated list of domains for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description
`page`	No	The page number for pagination. The first page is `1`.
`search`	No	The search term to filter the domains by.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`archived`	No	Whether to include archived domains in the response. Defaults to `false` if not provided.
`page_size`	No	The number of items per page.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered externally. The description adds that results are paginated and scoped to the authenticated workspace, but says nothing about default page size, archived-domain handling, or how filtering affects results. Useful but thin given annotations carry the safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficient sentence with the operation front-loaded and no filler. It is appropriately sized for a simple list tool, though it leaves little room for the scoping and pagination detail the other dimensions call for.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter list tool with full schema coverage and complete annotations, this is minimally adequate. However, it omits any note on pagination defaults, result ordering, or how the search/archived filters behave, which an agent would benefit from when composing calls.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters (page, search, account, archived, page_size) are already documented in the schema with defaults and bounds. The description's only param-relevant contribution is the word 'paginated', which adds no detail beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Retrieve a paginated list of domains') with scope ('authenticated workspace'), so the agent knows exactly what operation this performs. It does not differentiate itself from siblings like list_accounts or delete_domain, relying on the name alone for routing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives such as list_accounts or list_links, nor any mention of prerequisites or expected context. The only usable signal is 'authenticated workspace', which is a scope statement rather than usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_eventsList all eventsC

Read-onlyIdempotent

Retrieve a paginated list of events for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description	Default
`os`	No	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`.
`qr`	No	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.
`end`	No	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`.
`key`	No	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.
`url`	No	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`.
`city`	No	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`.
`page`	No	The page number for pagination. The first page is `1`.
`root`	No	Filter for root domains. If true, filter for domains only. If false, filter for links only. If undefined, return both.
`event`	No	The type of event to retrieve analytics for. Defaults to 'clicks'.	clicks
`limit`	No	The number of items per page.
`order`	No	DEPRECATED. Use `sortOrder` instead.	desc
`query`	No	Search the events by a custom metadata value. Only available for lead and sale events. Examples: `metadata['key']:'value'`
`start`	No	The start date and time when to retrieve analytics from. If set, takes precedence over `interval`.
`device`	No	The device to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `Desktop`, `Mobile,Tablet`, `-Mobile`.
`domain`	No	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`.
`region`	No	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`.
`tag_id`	No	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`.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`browser`	No	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`.
`country`	No	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`.
`link_id`	No	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`.
`referer`	No	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`.
`sort_by`	No	The field to sort the events by. The default is `timestamp`.	timestamp
`tag_ids`	No	Deprecated: Use `tagId` instead. The tag IDs to retrieve analytics for.
`trigger`	No	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.
`group_id`	No	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`.
`interval`	No	The interval to retrieve analytics for. If undefined, defaults to 24h.
`timezone`	No	The IANA time zone code for aligning timeseries granularity (e.g. America/New_York). Defaults to UTC.	UTC
`utm_term`	No	The UTM term to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`).
`continent`	No	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`.
`folder_id`	No	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.
`sale_type`	No	Filter sales by type: 'new' for first-time purchases, 'recurring' for repeat purchases. If undefined, returns both.
`tenant_id`	No	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`.
`event_name`	No	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`.
`partner_id`	No	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`.
`program_id`	No	Deprecated: This is automatically inferred from your workspace's defaultProgramId. The ID of the program to retrieve analytics for.
`sort_order`	No	The sort order. The default is `desc`.	desc
`utm_medium`	No	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_source`	No	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`.
`customer_id`	No	The ID of the customer to retrieve analytics for.
`external_id`	No	The ID of the link in the your database. Must be prefixed with 'ext_' when passed as a query parameter.
`referer_url`	No	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`.
`utm_content`	No	The UTM content to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`).
`utm_campaign`	No	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`.
`partner_tag_id`	No	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`.

TDQS

C2.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description only adds that results are paginated and workspace-scoped, both of which are marginal additions over the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single well-formed sentence with no filler, and the key noun 'events' is front-loaded. But for a tool with 45 filtering parameters, one generic sentence is arguably under-specified rather than optimally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (45 optional filters spanning geo, device, UTM, event type, and time-range dimensions) and the absence of an output schema, the description should at least sketch the filterable dimensions and the event types. It omits all of that, leaving the agent to reconstruct the tool's purpose entirely from the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 45 parameters are already documented in the schema. The description adds no parameter-level meaning beyond that baseline, so 3 is the appropriate ceiling.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Retrieve a paginated list of events'), which is clearer than a tautology. However, it is generic: it never mentions the analytics nature of these events (clicks/leads/sales) or how it differs from sibling read tools like get_link_stats or retrieve_partner_analytics, so an agent must infer the distinction from the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use or when-not-to-use guidance and no mention of alternatives. 'For the authenticated workspace' implies a scope but gives no decision criteria for choosing this tool over other list/analytics siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_foldersList all foldersB

Read-onlyIdempotent

Retrieve a paginated list of folders for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description
`page`	No	The page number for pagination. The first page is `1`.
`search`	No	The search term to filter the folders by.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`page_size`	No	The number of items per page.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the paginated-result and workspace-scoping details, with no mention of result shape, default ordering, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. It is appropriately sized, though it is arguably under-specified rather than maximally efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool with full schema coverage and an annotations-declared safety profile, the definition covers what the tool returns at a high level. Nothing critical is missing, though the search-filtering behavior could have been acknowledged.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so page, page_size, search, and account are fully documented in the schema. The description adds nothing per-parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Retrieve ... folders') with scope ('for the authenticated workspace') and the pagination nature of the result. It does not explicitly differentiate itself from siblings like create_folder/update_folder, but the list verb makes that obvious.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance, and no alternatives are named. The read-only listing intent is inferable from the verb, but the definition leaves all routing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_linksList all linksB

Read-onlyIdempotent

Retrieve a paginated list of links for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description
`page`	No	DEPRECATED. Use `startingAfter` instead.
`domain`	No	The domain to filter the links by. E.g. `ac.me`. If not provided, all links for the workspace will be returned.
`search`	No	The search term to filter the links by. The search term will be matched against the short link slug and the destination url.
`tag_id`	No	Deprecated: Use `tagIds` instead. The tag ID to filter the links by.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`tag_ids`	No	The tag IDs to filter the links by.
`user_id`	No	The user ID to filter the links by.
`folder_id`	No	The folder ID to filter the links by.
`page_size`	No	The number of items per page.
`tag_names`	No	The unique name of the tags assigned to the short link (case insensitive).
`tenant_id`	No	The ID of the tenant that created the link inside your system. If set, will only return links for the specified tenant.
`with_tags`	No	DEPRECATED. Filter for links that have at least one tag assigned to them.
`ending_before`	No	If specified, the query only searches for results before this cursor. Mutually exclusive with `startingAfter`.
`show_archived`	No	Whether to include archived links in the response. Defaults to `false` if not provided.
`starting_after`	No	If specified, the query only searches for results after this cursor. Mutually exclusive with `endingBefore`.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly=true, idempotent=true, openWorld=true, destructive=false, so the safety profile is fully covered. The description adds that results are paginated and scoped to the authenticated workspace, but says nothing about default filtering behavior (archived links excluded, default page size) or pagination mechanics, which is thin for a 15-parameter read.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler, stating the resource and scope immediately. It is efficient, though arguably under-sized for a tool with this many filtering and pagination options.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Annotations cover safety and the schema covers all parameters, but with no output schema the description could have described the returned list shape, and it omits notable behaviors such as archived-link exclusion and the deprecated-vs-preferred pagination parameters. Adequate but with clear gaps for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every one of the 15 parameters (including deprecated page, tag_id, with_tags and the cursor pair starting_after/ending_before) is already documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb (Retrieve) plus resource (links) plus scope (paginated, authenticated workspace), which is enough for an agent to understand the operation. It does not explicitly differentiate from close siblings like get_link (singular) or get_links_count, but the plural 'list' framing makes the distinction reasonably inferable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no mention of alternatives (e.g., get_link for a single link, get_links_count for totals), and no stated preconditions or exclusions. The agent must infer all routing decisions from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_partnersList all partnersC

Read-onlyIdempotent

List all partners for a partner program.

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	The page number for pagination. The first page is `1`.
`email`	No	Filter the partner list based on the partner's `email`. The value must be a string. Takes precedence over `search`.
`search`	No	A search query to filter partners by ID, name, email, company name, description, social platforms, or referral links. Partial matches are supported.
`status`	No	A filter on the list based on the partner's `status` field.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`country`	No	A filter on the list based on the partner's `country` field.
`sort_by`	No	The field to sort the partners by. The default is `totalSaleAmount`.	totalSaleAmount
`group_id`	No	A filter on the list based on the partner's `groupId` field.
`page_size`	No	The number of items per page.
`tenant_id`	No	Filter the partner list based on the partner's `tenantId`. The value must be a string. Combines with the other filters.
`sort_order`	No	The sort order. The default is `desc`.	desc

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds nothing beyond that: it does not mention pagination defaults (page_size 100/max 100), the email-over-search precedence rule, or the default sort. With annotations carrying the safety profile, a 2 reflects a description that contributes no extra behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with no waste and the resource front-loaded. It is efficient, though its brevity is under-specification rather than disciplined conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter list tool with no output schema, the description should at least indicate what is returned (partner objects), pagination behavior, or that filters combine. None of that is present, leaving the agent to rely entirely on the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across all 11 parameters, so the schema already documents pagination, filters, precedence, and defaults. The description contributes no parameter meaning beyond what the schema provides, which is the baseline 3 case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a clear verb and resource ("List all partners"), but it essentially restates the title "List all partners" and adds only the vague qualifier "for a partner program." It does nothing to distinguish this tool from siblings like list_program_applications, list_accounts, or list_customers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of alternatives among the many sibling list tools, and no note of prerequisites. The agent is left to infer everything from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_payoutsList all payoutsB

Read-onlyIdempotent

Retrieve a paginated list of payouts for your partner program.

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	The page number for pagination. The first page is `1`.
`status`	No	Filter the list of payouts by their corresponding status.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`sort_by`	No	The field to sort the list of payouts by.	amount
`group_id`	No	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`.
`page_size`	No	The number of items per page.
`tenant_id`	No	Filter the list of payouts by the associated partner's `tenantId` (their unique ID within your database).
`invoice_id`	No	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.
`partner_id`	No	Filter the list of payouts by the associated partner. When specified, takes precedence over `tenantId`.
`sort_order`	No	The sort order for the list of payouts.	desc

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds only that results are paginated, which is genuinely useful context but thin. No mention of rate limits, ordering defaults, or empty-result behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no padding or repetition; it is efficient. It is arguably undersized relative to a ten-parameter filtering tool, but conciseness itself is not violated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With ten optional filter parameters, no output schema, and no annotation-level detail about the response, the description leaves the return shape and filtering capability to inference. The rich schema and annotations cover most needs, but a sentence about filtering and pagination limits would round it out.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter is already documented in the schema, including the advanced filter syntax on group_id and the tenant_id precedence rule. The description adds nothing beyond the schema, making the baseline 3 correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (retrieve) plus resource (payouts) and scopes it ('for your partner program'), so an agent immediately knows this is a read/list operation over payouts. It does not differentiate from any sibling, but no other payout-listing sibling exists, so the gap is minor. Clear but generic.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of the filtering/pagination use cases the ten parameters enable, and no named alternative or exclusion condition. The agent must infer usage entirely from the schema. Only the bare operation is described.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`page`	No	The page number for pagination. The first page is `1`.
`search`	No	Filter applications by name, email, or company name. Partial matches are supported. An exact partner ID is also matched.
`status`	No	Filter applications by status. One of `pending`, `approved`, or `rejected`. Defaults to `pending`.	pending
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`country`	No	A filter on the list based on the partner's `country` field.
`group_id`	No	A filter on the list based on the partner's `groupId` field.
`page_size`	No	The number of items per page.
`sort_order`	No	The sort order. The default is `desc`.	desc

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered. The description only adds that the result is paginated, which is also visible from the page/page_size parameters, so it contributes little beyond structured data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the core action and scope. The second sentence partially duplicates the enum and default already in the schema, which is mild redundancy rather than bloating.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, no-required-parameter list endpoint whose 8 parameters are fully described in the schema and whose safety profile is covered by annotations, the description is adequate. It omits return shape and default pagination behavior, but with no output schema and rich annotations those gaps are minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: page, search, status, account, country, group_id, page_size and sort_order are all documented, including the pending default. The description restates the status enum and pagination without adding any semantics the schema lacks, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Retrieve/list) and resource (applications for your partner program), with pagination noted. It is reasonably distinct from sibling list tools like list_partners or list_bounty_submissions, though it never explicitly contrasts itself with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence implies usage by pointing at the status filter and its three values, but there is no explicit when-to-use guidance, no prerequisites, and no discrimination against the many other list_* siblings. Usage is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tagsList all tagsB

Read-onlyIdempotent

Retrieve a paginated list of tags for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description	Default
`ids`	No	IDs of tags to filter by.
`page`	No	The page number for pagination. The first page is `1`.
`search`	No	The search term to filter the tags by.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`sort_by`	No	The field to sort the tags by.	name
`page_size`	No	The number of items per page.
`sort_order`	No	The order to sort the tags by.	asc

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true), so the description only needs to add context beyond that. It adds that results are paginated and scoped to the authenticated workspace, but says nothing about rate limits, default result size, or how filtering interacts with pagination.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler; the scope qualifier follows immediately after the core action. Nothing is wasted and nothing needs to be re-read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description is the sole place to learn what comes back, and it conveys only 'paginated list of tags' — no indication of result envelope, total counts, or ordering behavior. For a seven-parameter list endpoint, this is adequate but leaves clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across all seven parameters, so the schema already documents filtering, sorting, and pagination semantics. The description only echoes 'paginated' and 'tags' without adding meaning beyond the structured fields, matching the baseline for a fully documented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (retrieve/list) and resource (tags) with the scope narrowed to 'the authenticated workspace', so an agent can distinguish it from create_tag, update_tag, and delete_tag without opening schemas. It does not, however, explicitly name or contrast itself with any sibling tool, which keeps it just short of 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives such as the filter-oriented siblings, nor any stated prerequisites or exclusions. The optional ids/search parameters hint that the tool doubles as a lookup mechanism, but the description never says so; usage must be inferred entirely from the schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

preview_link_batchReview exact ordered link tasksA

Read-onlyIdempotent

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.

ParametersJSON Schema

Name	Required	Description	Default
`tasks`	Yes	One to twenty ordered link/tag/folder operations. CLI repeats --tasks with individual JSON objects; native bulk work still counts all affected records.
`account`	No	Exact selected private workspace profile; binds label, not key ownership.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds real context beyond them: it explicitly disclaims provider reads, key loading, identity checks, pricing, and any rollback guarantee. This is meaningful disclosure of the tool's limits, though the practical meaning of the SHA-256 step for the caller remains unexplained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with no filler, and the core capability (local validation + hash) is front-loaded. The negation clause is dense and telegraphic, but every element carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should clarify what the preview returns (validation report, digest, per-task errors), and it does not. Safety and non-actions are well covered, but the caller cannot predict the shape or content of the preview result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the required tasks array, its nested tool enum, and the account label are already documented in the schema. The description's phrases ('exact ordered link/tag/folder work', 'selected profile label') only loosely echo those parameters and add no new syntax or constraint detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names specific operations (local validation and SHA-256 hashing) over a specific resource set (ordered link/tag/folder tasks with a profile label and schema), so an agent can tell this is a dry-run preview rather than an execution. It stops short of naming its obvious counterpart submit_link_batch, so the sibling distinction must be inferred from the name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: 'No provider reads, key load, identity check...' communicates that this is a safe pre-flight step before a real submission, but the description never states when to call it versus submit_link_batch. There is no explicit conditional routing or exclusion, so the agent must infer the workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

register_domainRegister a domainA

Destructive

ParametersJSON Schema

Name	Required	Description
`domain`	No	The domain to claim. We only support .link domains for now.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive=true, idempotent=false, openWorld=true, and readOnly=false, so the agent knows the mutation profile. The description adds the Enterprise-plan gating, which is real context, but says nothing about irreversibility, what confirm does, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero waste, with the core action front-loaded and the plan constraint following. Appropriately sized for the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter mutation with a nested payload object, no output schema, and a near-duplicate sibling (create_domain), the description is thin. The schema carries most of the load, but the lack of sibling differentiation leaves a real gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents domain, account, confirm, payload, and payload_file. The description adds no parameter-level meaning beyond what the schema provides, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a clear verb+resource ('Register a domain') and scopes it to the authenticated workspace. However, it never distinguishes this from the sibling create_domain, so an agent cannot tell which one to pick without opening both schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states an eligibility constraint ('Only available for Enterprise Plans'), which is useful context, but gives no when-to-use guidance or alternative (e.g. create_domain, update_domain). Usage must be inferred from the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reject_bounty_submissionReject a bounty submissionC

Destructive

Reject a bounty submission with a specified reason and optional note.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`bounty_id`	Yes	The ID of the bounty
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.
`rejectionNote`	No	The note for rejecting the submission.
`submission_id`	Yes	The ID of the bounty submission
`rejectionReason`	No	The reason for rejecting the submission.

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds nothing beyond that — it does not state that rejection is irreversible, whether a confirmation is mandatory, or any downstream effects, so the added behavioral value is minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficient sentence with the core action and its inputs front-loaded; no wasted words, though it is arguably under-specified rather than optimally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with 8 parameters, nested objects, and no output schema, the description is thin: it omits the mandatory confirm flag and the payload vs. payload_file distinction. The schema and annotations carry most of the load, leaving this adequate but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so every parameter including the rejectionReason enum and rejectionNote is already documented in the schema. The description merely echoes 'specified reason and optional note' without adding format, allowed values, or interaction constraints, matching the baseline when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (reject) and resource (bounty submission), and the mention of 'reason' and 'optional note' signals what the rejection is configured with. It reads clearly against siblings like approve_bounty_submission and reject_program_application, though the differentiation comes largely from the name rather than explicit routing language.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to reject versus approve, no prerequisites, and no mention of the required confirm flag or the payload/payload_file choice. Usage is left entirely to inference from the tool name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`partnerId`	No	The ID of the partner to reject.
`flagForFraud`	No	Whether to flag the partner for fraud review by the Dub team. Cannot be combined with `reapplicationTimeframe: instant`.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.
`rejectionNote`	No	Additional details about the rejection. This will be shared with the partner via email.
`rejectionReason`	No	The reason for rejecting the partner application. This will be shared with the partner via email.
`flagForFraudReason`	No	The reason for flagging the partner for fraud. Required when flagForFraud is true.
`reapplicationTimeframe`	No	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.	standard

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false and non-idempotency, so the safety profile is covered. The description adds genuine behavioral context beyond that: the partner is notified by email that the application was not approved, making the side effect externally visible and irreversible. It still omits the confirm requirement and the permanence implications of reapplicationTimeframe.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero waste, with the action front-loaded and the notification consequence immediately after. Nothing is repeated from the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter destructive mutation with a nested payload and no output schema, the description covers the action and its external side effect adequately, and annotations carry the safety profile. It would be stronger if it noted the confirm gate or that 'never' reapplication is permanent, but nothing essential to calling it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents partnerId, rejectionReason, rejectionNote, flagForFraud, and reapplicationTimeframe in detail. The description adds no parameter-level syntax or constraints of its own, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Reject a pending partner application') and implicitly contrasts with the sibling approve_program_application and list_program_applications via the 'pending' qualifier. It does not explicitly name an alternative, but the purpose is unambiguous without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The word 'pending' implies the application must be in a pending state, which is a mild usage condition. However, no alternatives are named, no prerequisites (such as the required confirm=true or the account label) are given, and no when-not-to-use guidance appears.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`end`	No	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`.
`query`	No	Search the events by a custom metadata value. Only available for lead and sale events. Examples: `metadata['key']:'value'`
`start`	No	The start date and time when to retrieve analytics from. If set, takes precedence over `interval`.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`group_by`	No	The parameter to group the analytics data points by. Defaults to `count` if undefined.	count
`interval`	No	The interval to retrieve analytics for. If undefined, defaults to 24h.
`timezone`	No	The IANA time zone code for aligning timeseries granularity (e.g. America/New_York). Defaults to UTC.	UTC
`tenant_id`	No	The ID of the partner in your system. If both `partnerId` and `tenantId` are not provided, an error will be thrown.
`partner_id`	No	The ID of the partner to create a link for. Will take precedence over `tenantId` if provided.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description only needs to add operational context. It does add one real behavioral fact — that the response shape varies with groupBy — but says nothing about what that variation looks like, pagination, aggregation behavior, or the error thrown when neither partner_id nor tenant_id is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with the core purpose front-loaded and no filler. Minor deduction for the ungrammatical "The response type vary" and for spending the second sentence on a point that is not developed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 9 parameters, no output schema, and an explicitly variable response shape, the description is thinner than the tool's complexity warrants — it never explains what top_links, timeseries, or count actually return, and omits the partner_id/tenant_id requirement. The schema covers the inputs well, so this is adequate but with a clear gap on output expectations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains every parameter including defaults, enums, precedence rules, and the tenant_id/partner_id error condition. The description's only parameter-adjacent remark (response varies by groupBy) restates what the schema's enum implies. Baseline 3 for a fully documented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Retrieve analytics for a partner within a program") and hints at the groupBy-driven output variation. It is clearly distinct from link/customer/commission siblings, though it never explicitly routes the agent away from the similarly named get_link_stats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of prerequisites (tenant_id or partner_id must be supplied), and no comparison to alternatives such as get_link_stats or list_events. The agent must infer context entirely from the schema and sibling names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

retrieve_partner_linksRetrieve a partner's links.C

Read-onlyIdempotent

Retrieve a partner's links by their partner ID or tenant ID.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`tenant_id`	No	The ID of the partner in your system. If both `partnerId` and `tenantId` are not provided, an error will be thrown.
`partner_id`	No	The ID of the partner to create a link for. Will take precedence over `tenantId` if provided.

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds no behavioral context of its own — no mention of the error thrown when neither ID is supplied, no pagination, ordering, or return-shape notes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the lookup keys are stated immediately. It is efficient, though arguably thin given the tool's optional-parameter and error-handling nuance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should ideally cover the return shape and the failure mode when neither identifier is provided; the schema covers the latter but the description is silent on results. For a read-only lookup with full annotation and schema coverage, this is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters including partnerId precedence over tenantId and the error condition. The description's 'partner ID or tenant ID' phrasing adds no syntax or format detail beyond that, and it omits the 'account' parameter entirely, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Retrieve') and resource ('a partner's links'), so the operation is unambiguous. It does not, however, distinguish this from sibling tools like list_links, create_partner_link, or upsert_partner_link, which an agent must infer on its own.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'by their partner ID or tenant ID' hints at the required inputs, but there is no statement of when to use this tool versus list_links, list_partners, or retrieve_partner_analytics, and no prerequisites or exclusions are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

submit_link_batchExecute reviewed link tasksA

Destructive

ParametersJSON Schema

Name	Required	Description
`tasks`	Yes	One to twenty ordered link/tag/folder operations. CLI repeats --tasks with individual JSON objects; native bulk work still counts all affected records.
`account`	No	Exact selected private workspace profile; binds label, not key ownership.
`confirm`	No	Explicit approval for this exact requested ordered batch.
`review_sha256`	Yes	Exact preview_link_batch hash for identical requests, profile label, schema and order.

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive/non-idempotent/open-world, but the description adds substantive behavior beyond them: prevalidation of all tasks, hash verification before the first request, stop-on-first-failure with known results/failed index/unattempted indices, and explicit absence of retries, rollback or implicit continuation. That partial-execution contract is exactly what an agent needs for a destructive batch.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the batch scope and immediately followed by the precondition and failure contract. No filler or restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive batch tool with no output schema, the description covers scope, preconditions, and the failure return shape (known results/failed index/unattempted indices), which is the critical information. The success return shape is not described, but the failure path is the higher-risk gap and it is handled.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema itself already says 'one to twenty ordered link/tag/folder operations' and documents the hash fields, so the description largely repeats structured data. The ordering emphasis is the only semantic reinforcement, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (submit/execute) and resource (ordered link/tag/folder tasks), plus the 1-20 bound, so an agent knows exactly what the tool does. It does not name the obvious sibling preview_link_batch, leaving the pairing to be inferred from 'Confirmed' and the hash requirement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Confirmed' plus 'verify exact hash before first request' makes the precondition clear: this runs only after a preview was reviewed and confirmed. It gives clear context but never explicitly names preview_link_batch as the alternative or states when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

track_leadTrack a leadD

Destructive

Track a lead for a short link.

ParametersJSON Schema

Name	Required	Description	Default
`mode`	No	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.	async
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`clickId`	No	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.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`metadata`	No	Additional metadata to be stored with the lead event. Max 10,000 characters.
`eventName`	No	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`).
`customerName`	No	The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”).
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.
`customerEmail`	No	The email address of the customer.
`eventQuantity`	No	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.
`customerAvatar`	No	The avatar URL of the customer.
`customerExternalId`	No	The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer.

TDQS

D1.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is partly covered. The description adds nothing beyond them: it does not mention that this creates a persistent conversion event, that repeated calls are not idempotent, or any auth/rate-limit context. It does not contradict the annotations, but it contributes no behavioral context of its own.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One short sentence is certainly terse, but the problem is under-specification rather than conciseness. A single sentence that merely echoes the title leaves the definition effectively empty for a 13-parameter, nested-payload mutation tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool that writes conversion events with a nested payload requiring clickId, eventName, and customerExternalId, and that supports async/wait/deferred modes and deferred lead tracking semantics, the description omits every operational detail. No output schema exists to compensate, and the agent is left to reverse-engineer intent from the schema alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and each field (mode, clickId, eventName, customerExternalId, payload, etc.) is well documented in the schema itself. Per the baseline rule for high coverage, 3 is appropriate; the description adds no parameter meaning beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description is essentially a restatement of the tool name and title ('Track a lead for a short link'), adding only a thin scope hint about short links. It does not distinguish this from siblings like track_sale or track_open, which are equally about conversion event tracking, so an agent cannot tell them apart from the text alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no when-not-to-use guidance, and no named alternative. Nothing tells the agent why it would pick track_lead over track_sale, track_open, or list_events, nor what preconditions (e.g. a valid clickId attribution) must hold.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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).

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`deepLink`	No	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
`dubDomain`	No	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
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this is a non-read-only, non-idempotent, destructive, open-world operation, but the description adds nothing to explain those traits. It does not mention the required `confirm` flag, the private `account` scoping, or why a 'tracking' call is flagged destructive, which is exactly the kind of context annotations cannot convey. The only extra fact is platform coverage (iOS and Android).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler. It is appropriately sized, though the brevity is partly responsible for the behavioral and usage gaps rather than being a virtue of precision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 100% schema coverage and annotations carrying the safety profile, the minimum needed to invoke the tool is present. However, for a destructive-flagged mutation requiring a `confirm` flag and private account scoping, the description leaves an agent without operational context on confirmation or the probabilistic-tracking fallback.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the deepLink/dubDomain fallback logic and the payload/payload_file exclusivity are already fully documented in the schema. The description contributes no additional parameter meaning, which is the expected baseline when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('track') and resource ('when a user opens your app via a Dub-powered deep link'), which is far clearer than the bare name. It implicitly distinguishes itself from sibling trackers like track_lead and track_sale by scoping to deep-link open events, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this versus the other tracking endpoints (track_lead, track_sale) or when the deepLink vs dubDomain fallback path should be chosen. The 'when' is only inferable from the resource being tracked.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

track_saleTrack a saleC

Destructive

Track a sale for a short link.

ParametersJSON Schema

Name	Required	Description	Default
`amount`	No	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
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`clickId`	No	[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.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`currency`	No	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	usd
`metadata`	No	Additional metadata to be stored with the sale event. Max 10,000 characters when stringified.
`eventName`	No	The name of the sale event. Recommended format: `Invoice paid` or `Subscription created`.	Purchase
`invoiceId`	No	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.
`customerName`	No	[For direct sale tracking]: The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”).
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.
`customerEmail`	No	[For direct sale tracking]: The email address of the customer.
`leadEventName`	No	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.
`customerAvatar`	No	[For direct sale tracking]: The avatar URL of the customer.
`paymentProcessor`	No	The payment processor via which the sale was made.	custom
`customerExternalId`	No	The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer.

TDQS

C2.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, openWorldHint=true and readOnlyHint=false, and the description adds nothing beyond them. It omits the required confirm flag behavior, the invoiceId idempotency key, and what side effects a tracked sale produces - all meaningful context for a mutating tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no wasted words, so structurally clean. But for a 16-parameter tool with nested objects and overloaded naming (payload vs. flat fields), one sentence is under-specified rather than appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex mutation with nested objects, a confirm gate, invoice-based idempotency, and multiple tracking modes, the description covers none of it. With no output schema, the agent gets no signal about results, attribution requirements, or the significance of the destructive annotation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and every one of the 16 parameters (including the nested payload) is documented in the schema itself, so the baseline of 3 applies. The description contributes no additional parameter meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource ('Track a sale') and the event type distinguishes it from siblings like track_lead and track_open. However, 'for a short link' is imprecise: no linkId exists in the schema and attribution is actually via clickId/customerExternalId, so the scope claim is slightly misleading rather than fully precise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool, when not to, or how it relates to track_lead/track_open. Nothing explains whether a lead must precede the sale or which of the two tracking modes (direct vs. invoice-based) to pick.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_commissionUpdate a commissionA

Destructive

Update an existing commission amount. This is useful for handling refunds (partial or full) or fraudulent sales.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	The commission's unique ID on Dub.
`amount`	No	Deprecated. Use `saleAmount` instead.
`status`	No	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.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`currency`	No	The currency of the sale amount to update. Accepts ISO 4217 currency codes.	usd
`earnings`	No	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.
`saleAmount`	No	The new absolute amount for the sale. Paid commissions cannot be updated.
`modifyAmount`	No	Deprecated. Use `modifySaleAmount` instead.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.
`modifySaleAmount`	No	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.

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the mutation and safety profile is covered. The description adds useful behavioral context about refund and fraud use cases, but it does not disclose critical constraints such as paid commissions being unmodifiable, status precedence over saleAmount, or the confirm requirement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The core operation is front-loaded, followed immediately by a concrete use case, so every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter mutation tool with nested payload options and no output schema, the description is thin. However, the schema is fully documented and annotations cover the destructive read/write profile, so the definition is minimally adequate for an agent that reads the schema, though it omits important routing and constraint context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so nearly all parameter meaning is already in the schema. The description mentions only 'amount' and adds no syntax or precedence guidance beyond what the parameter descriptions already provide, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Update an existing commission amount.' It does not explicitly distinguish this single-record update from the sibling bulk_update_commissions tool, and it narrows the purpose to amount while the schema also supports status and earnings updates. Still, the core operation is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides implied usage context by naming refunds (partial or full) and fraudulent sales as reasons to call it. It does not say when to use this instead of create_commission, list_commissions, or bulk_update_commissions, and it gives no exclusions beyond the schema's paid-commission constraint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_customerUpdate a customerC

Destructive

Update a customer for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	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`).
`name`	No	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.
`email`	No	The customer's email address.
`avatar`	No	The customer's avatar URL. If not provided, a random avatar will be generated.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`country`	No	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).
`payload`	No	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.
`externalId`	No	The customer's unique identifier your database. This is useful for associating subsequent conversion events from Dub's API to your internal systems.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.
`stripeCustomerId`	No	The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.
`subscriptionCanceledAt`	No	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).
`include_expanded_fields`	No	Whether to include expanded fields on the customer (`link`, `partner`, `discount`).

TDQS

C2.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context of its own: it does not say whether the update is a partial merge or full replacement, what happens to omitted fields, or that repeated calls are not idempotent. With annotations present the bar is lower, but this adds essentially nothing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single short sentence with no padding, so nothing is wasted, but the sentence is nearly redundant with the title and carries almost no substance, leaving it under-specified rather than genuinely concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter destructive mutation with a nested payload object, multiple input modes (payload/payload_file/body flags), and no output schema, a one-line description is far too thin. It omits the update semantics, the confirm requirement, and any caveat surrounding the destructive change.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 13 parameters, including the confirm flag and the payload/payload_file mutual exclusion. The description adds no parameter meaning beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The phrase "Update a customer" gives a clear verb+resource, but it largely restates the title and name. The only added information is the workspace scoping ("for the authenticated workspace"), and there is no differentiation from siblings such as get_customer, list_customers, or delete_customer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no when-to-use guidance, no prerequisites, and no alternatives. It does not mention that the mutation requires confirm=true, nor how it relates to get_customer/delete_customer/upsert-style siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_domainUpdate a domainC

Destructive

Update a domain for the authenticated workspace.

ParametersJSON Schema

Name	Required	Description
`logo`	No
`slug`	Yes	Name of the domain.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`archived`	No	Whether to archive this domain. `false` will unarchive a previously archived domain.
`assetLinks`	No	assetLinks.json configuration file (for deep link support on Android).
`expiredUrl`	No	Redirect users to a specific URL when any link under this domain has expired.
`notFoundUrl`	No	Redirect users to a specific URL when a link under this domain doesn't exist.
`placeholder`	No	Provide context to your teammates in the link creation modal by showing them an example of a link to be shortened.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.
`appleAppSiteAssociation`	No	apple-app-site-association configuration file (for deep link support on iOS).

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the 'authenticated workspace' scope and says nothing about what fields get overwritten, reversibility, or the confirm requirement for this mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no padding or redundancy. Efficient, though its brevity edges toward under-specification rather than tightness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter destructive mutation with a nested payload object, a payload_file alternative, and a confirm requirement, one bare sentence is inadequate. The agent must reverse-engineer mutation behavior and payload strategy entirely from the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 92%, so the schema documents the 12 parameters (payload, payload_file, confirm, account, etc.) thoroughly. The description adds no param meaning beyond that, which is the baseline expectation when coverage is this high.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource ('Update a domain') and adds scope ('for the authenticated workspace'). However, it does nothing to distinguish this from siblings like create_domain, delete_domain, or register_domain beyond the verb.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No indication of when to use this versus create_domain/delete_domain/register_domain, no prerequisites, and no mention that a confirm flag or payload strategy is required. The agent gets no routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_folderUpdate a folderC

Destructive

Update a folder in the workspace.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	The ID of the folder to update.
`name`	No	The name of the folder.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`accessLevel`	No	The access level of the folder within the workspace.
`description`	No	The description of the folder.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing on top of that: it does not mention that a mutation requires confirm=true, what happens to unspecified fields, or that changes are non-idempotent, which is exactly the extra context this bar rewards.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler, which is structurally clean. It is under-specified rather than bloated, and under-specification is penalized elsewhere.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a destructive mutation with a nested payload, a confirm flag, and two mutually exclusive body channels (payload vs payload_file), yet the description never acknowledges any of that. With no output schema and a complex argument surface, one generic sentence is not enough to call the tool correctly with confidence.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the eight parameters (including the nested payload, payload_file, and the confirm flag) are already documented in structured form. The description adds no parameter meaning whatsoever, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a verb and resource ("Update a folder") and scopes it to the workspace, but it does little more than restate the tool title. It never distinguishes this from siblings like create_folder, delete_folder, or update_link, nor does it say what aspect of the folder is updatable, leaving the agent to open the schema to find out.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as create_folder or delete_folder. The agent must infer everything about applicability from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_linkUpdate a linkB

Destructive

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

ParametersJSON Schema

Name	Required	Description
`geo`	No
`ios`	No	The iOS destination URL for the short link for iOS device targeting.
`key`	No	The short link slug. If not provided, a random 7-character slug will be generated.
`ref`	No	The referral tag of the short link. If set, this will populate or override the `ref` query parameter in the destination URL.
`url`	No	The destination URL of the short link.
`image`	No
`proxy`	No	Whether the short link uses Custom Link Previews feature. Defaults to `false` if not provided.
`tagId`	No	Deprecated: Use `tagIds` instead. The unique ID of the tag assigned to the short link.
`title`	No	The custom link preview title (og:title). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
`video`	No	The custom link preview video (og:video). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
`domain`	No	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).
`tagIds`	No	The unique IDs of the tags assigned to the short link.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`android`	No	The Android destination URL for the short link for Android device targeting.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`doIndex`	No	Allow search engines to index your short link. Defaults to `false` if not provided. Learn more: https://d.to/noindex
`link_id`	Yes	The id of the link to update. You may use either `linkId` (obtained via `/links/info` endpoint) or `externalId` prefixed with `ext_`.
`payload`	No	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.
`rewrite`	No	Whether the short link uses link cloaking. Defaults to `false` if not provided.
`archived`	No	Whether the short link is archived. Defaults to `false` if not provided.
`comments`	No	The comments for the short link.
`folderId`	No	The unique ID existing folder to assign the short link to.
`password`	No	The password required to access the destination URL of the short link.
`tagNames`	No	The unique name of the tags assigned to the short link (case insensitive).
`tenantId`	No	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.
`utm_term`	No	The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL.
`expiresAt`	No	The date and time when the short link will expire at.
`partnerId`	No	The ID of the partner the short link is associated with.
`programId`	No	The ID of the program the short link is associated with.
`expiredUrl`	No	The URL to redirect to when the short link has expired.
`externalId`	No	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.
`utm_medium`	No	The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL.
`utm_source`	No	The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL.
`webhookIds`	No	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.
`description`	No	The custom link preview description (og:description). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
`publicStats`	No	Deprecated: Use `dashboard` instead. Whether the short link's stats are publicly accessible. Defaults to `false` if not provided.
`utm_content`	No	The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.
`testVariants`	No	An array of A/B test URLs and the percentage of traffic to send to each URL.
`utm_campaign`	No	The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL.
`testStartedAt`	No	The date and time when the tests started.
`testCompletedAt`	No	The date and time when the tests were or will be completed.
`trackConversion`	No	Whether to track conversions for the short link. Defaults to `false` if not provided.

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds useful context — workspace scoping and the no-op contract ('if there's no change, returns it as it is') — but says nothing about permissions, which fields are replaced vs merged, or side effects of destructive changes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core action and followed by the notable no-op behavior. Zero filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 43-parameter destructive mutation with rich schema coverage and annotations, the description covers the core action and no-op semantics but omits routing guidance against upsert_link/bulk_update_links and any note on partial vs full updates. Adequate but with clear gaps given the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 95%, so the schema already documents nearly all 43 parameters in detail, including nested payload objects. The description adds no parameter-level meaning beyond what the schema provides, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (update) and resource (a link) scoped to the authenticated workspace, which is clear and unambiguous. However, it does not distinguish itself from close siblings like upsert_link or bulk_update_links, so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no when-to-use guidance or conditions for choosing this tool over upsert_link or bulk_update_links. The only extra sentence concerns no-op behavior, not usage selection, leaving alternatives entirely unaddressed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_tagUpdate a tagC

Destructive

Update a tag in the workspace.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	The ID of the tag to update.
`tag`	No	The name of the tag to create.
`name`	No	The name of the tag to create.
`color`	No	The color of the tag. If not provided, a random color will be used from the list: red, yellow, green, blue, purple, brown, gray.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

C2.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the agent knows this mutates state. The description adds nothing on top: it does not mention that a mutation requires confirm=true (per the schema's own flag), what gets overwritten, or how the deprecated 'tag' field interacts with 'name'. With annotations carrying the safety profile, this earns a low score for adding no context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One short sentence is certainly concise and front-loaded, but it is under-specified rather than efficiently informative. It wastes no words yet conveys almost nothing beyond the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter destructive mutation with a nested payload object, deprecated fields, and mutually exclusive body-passing options, a single sentence is inadequate. Even accounting for the rich schema and the existence of annotations, the description leaves an agent without the mutation context (confirm requirement, field semantics) that a definition of this complexity should supply.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 8 parameters (including the deprecated 'tag', the payload/payload_file exclusivity rules, and the confirm flag) are documented in the schema itself. The description contributes no additional parameter meaning, making the baseline of 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description is essentially a restatement of the title ('Update a tag') with 'in the workspace' appended; it names a verb and resource but provides no scope, no affected fields, and no differentiation from sibling tools like update_folder, update_link, or update_domain. This is close to a tautology rather than a specification of purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use update_tag versus create_tag, delete_tag, or list_tags, nor any mention of prerequisites such as the confirm flag. Nothing tells the agent which conditions select this tool over its siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

upsert_linkUpsert a linkB

Destructive

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.

ParametersJSON Schema

Name	Required	Description
`geo`	No	Geo targeting information for the short link in JSON format `{[COUNTRY]: https://example.com }`. See https://d.to/geo for more information.
`ios`	No	The iOS destination URL for the short link for iOS device targeting.
`key`	No	The short link slug. If not provided, a random 7-character slug will be generated.
`ref`	No	The referral tag of the short link. If set, this will populate or override the `ref` query parameter in the destination URL.
`url`	No	The destination URL of the short link.
`image`	No	The custom link preview image (og:image). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
`proxy`	No	Whether the short link uses Custom Link Previews feature. Defaults to `false` if not provided.
`tagId`	No	Deprecated: Use `tagIds` instead. The unique ID of the tag assigned to the short link.
`title`	No	The custom link preview title (og:title). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
`video`	No	The custom link preview video (og:video). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
`domain`	No	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).
`prefix`	No	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.
`tagIds`	No	The unique IDs of the tags assigned to the short link.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`android`	No	The Android destination URL for the short link for Android device targeting.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`doIndex`	No	Allow search engines to index your short link. Defaults to `false` if not provided. Learn more: https://d.to/noindex
`payload`	No	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.
`rewrite`	No	Whether the short link uses link cloaking. Defaults to `false` if not provided.
`archived`	No	Whether the short link is archived. Defaults to `false` if not provided.
`comments`	No	The comments for the short link.
`folderId`	No	The unique ID existing folder to assign the short link to.
`password`	No	The password required to access the destination URL of the short link.
`tagNames`	No	The unique name of the tags assigned to the short link (case insensitive).
`tenantId`	No	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.
`utm_term`	No	The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL.
`expiresAt`	No	The date and time when the short link will expire at.
`keyLength`	No	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`.
`partnerId`	No	The ID of the partner the short link is associated with.
`programId`	No	The ID of the program the short link is associated with.
`expiredUrl`	No	The URL to redirect to when the short link has expired.
`externalId`	No	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.
`utm_medium`	No	The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL.
`utm_source`	No	The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL.
`webhookIds`	No	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.
`description`	No	The custom link preview description (og:description). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og
`publicStats`	No	Deprecated: Use `dashboard` instead. Whether the short link's stats are publicly accessible. Defaults to `false` if not provided.
`utm_content`	No	The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.
`testVariants`	No	An array of A/B test URLs and the percentage of traffic to send to each URL.
`utm_campaign`	No	The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL.
`testStartedAt`	No	The date and time when the tests started.
`testCompletedAt`	No	The date and time when the tests were or will be completed.
`trackConversion`	No	Whether to track conversions for the short link. Defaults to `false` if not provided.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is carried for free. The description adds real behavioral context — matching by URL, returning an existing link, or creating a new one — but omits the destructive nuances (which fields an update overwrites) and the confirm=true requirement for the mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, front-loaded sentences that each carry content with no filler. For a 44-parameter destructive tool it is arguably terse, but every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The core create-or-update contract is covered and the annotations plus 100% schema coverage carry the rest. However, for a high-complexity mutation tool the description leaves the confirm requirement and the destructive/overwrite consequences unstated, so it is adequate but has clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 44 parameters; the baseline is 3. The description clarifies only that URL is the upsert matching key (the schema just calls it the 'destination URL'), which is a marginal addition rather than compensation for any gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Upsert a link') scoped to the authenticated workspace and keyed by URL. The upsert semantics implicitly separate it from create_link/update_link, but it never names those siblings, so differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what happens when the URL exists vs does not, but gives no explicit when-to-use guidance, no prerequisites, and no routing away from create_link or update_link. There is no 'use this when...' or 'prefer X instead' clause.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

upsert_partner_linkUpsert a link for a partnerA

Destructive

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.

ParametersJSON Schema

Name	Required	Description
`key`	No	The short link slug. If not provided, a random 7-character slug will be generated.
`url`	No	The URL to upsert for.
`account`	No	Exact configured private workspace profile label; not a tenant or provider account ID.
`confirm`	No	Must be true for the requested mutation or exclusive private output file.
`payload`	No	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.
`comments`	No	The comments for the short link.
`tenantId`	No	The ID of the partner in your system. If both `partnerId` and `tenantId` are not provided, an error will be thrown.
`linkProps`	No	Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.
`partnerId`	No	The ID of the partner to create a link for. Will take precedence over `tenantId` if provided.
`payload_file`	No	Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags.

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (destructive=true, openWorld=true, readOnly=false), and the description usefully adds the URL-keyed match/update semantics. It does not say what happens to existing link properties that are omitted (overwritten vs preserved), and the 'return it if unchanged' wording sits in mild tension with idempotentHint=false without resolving it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero filler, front-loading the operation and then the branch behavior. Every clause carries information; nothing is restated from the title or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, nested-payload mutation the description omits important framing: that partnerId or tenantId must be supplied or an error is thrown, that confirm=true is required, and that body can be passed either as flat flags or as a native payload. It is adequate but leaves the agent to discover these from the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 10 properties (key, url, account, confirm, payload, partnerId, tenantId, linkProps, etc.) are already documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (upsert) and resource (a short link for a partner) plus a scoping condition (partner must be enrolled in your program). It does not, however, contrast itself with close siblings like create_partner_link or upsert_link, so the agent still has to infer the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the create-vs-update branch (existing URL is returned or updated, otherwise created), which implies when the tool is appropriate. It gives no explicit when-not guidance and never names an alternative, so routing between this and create_partner_link / upsert_link is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

61 tool updatesv2.0.0Oct 3, 2026
- First observedapprove_bounty_submission
- First observedapprove_program_application
- First observedban_partner
- First observedbulk_create_links
- First observedbulk_delete_links
- First observedbulk_update_commissions
- First observedbulk_update_links
- First observedcheck_domain_status
- First observedcreate_commission
- First observedcreate_discount_code
- First observedcreate_domain
- First observedcreate_folder
- First observedcreate_link
- First observedcreate_partner
- First observedcreate_partner_link
- First observedcreate_referrals_embed_token
- First observedcreate_tag
- First observeddeactivate_partner
- First observeddelete_customer
- First observeddelete_discount_code
- First observeddelete_domain
- First observeddelete_folder
- First observeddelete_link
- First observeddelete_tag
- First observedget_customer
- First observedget_link
- First observedget_link_stats
- First observedget_links_count
- First observedget_operation_schema
- First observedget_qr_code
- First observedlist_accounts
- First observedlist_bounty_submissions
- First observedlist_commissions
- First observedlist_customers
- First observedlist_discount_codes
- First observedlist_domains
- First observedlist_events
- First observedlist_folders
- First observedlist_links
- First observedlist_partners
- First observedlist_payouts
- First observedlist_program_applications
- First observedlist_tags
- First observedpreview_link_batch
- First observedregister_domain
- First observedreject_bounty_submission
- First observedreject_program_application
- First observedretrieve_partner_analytics
- First observedretrieve_partner_links
- First observedsubmit_link_batch
- First observedtrack_lead
- First observedtrack_open
- First observedtrack_sale
- First observedupdate_commission
- First observedupdate_customer
- First observedupdate_domain
- First observedupdate_folder
- First observedupdate_link
- First observedupdate_tag
- First observedupsert_link
- First observedupsert_partner_link

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.9/5.0

Scored 2026-10-03 05:45 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

ActivityNo data

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

linkly B
com.linklyhq
Create and manage short links, track clicks, and automate URL management
Marketing Developer Tools
2521
toui.io URL ShortenerOAuth
io.toui
Short-link service embedded in your AI workflow — shorten links, track campaigns, read stats.
Developer Tools
2
dub B
io.usefulapi
Short links with click, lead and sale analytics, customers, tags and the partner programme.
Marketing CRM
221
MiniURL A
io.github.addychang
OAuth 2.1 short-link tools for AI agents with scoped tokens, approvals, audit logs, and revocation.
Marketing Developer Tools
232

Related MCP Servers

DWZ Short URL MCP Server
Developer Tools App Automation
muleiwu
A
license
A
quality
D
maintenance
Enables AI assistants to create, manage, and analyze short URLs through complete URL shortening functionality. Supports batch operations, custom domains, click statistics, and comprehensive link management.
Updated 8 months ago (2026-01-28 08:26 UTC)
6
7 npm
1
MIT
filoo MCP server
Marketing Developer Tools
jrlprost
A
license
A
quality
D
maintenance
Enables AI agents to shorten URLs, manage links, and track click analytics through 8 first-class tools, designed for use with Claude Desktop, Cursor, and other MCP clients.
Updated 4 months ago (2026-05-20 21:49 UTC)
9
52 npm
MIT
genpark-creator-affiliate-gmvofficial
E-commerce & Retail Finance Autonomous Agents
alphaparkinc
F
license
Not graded
quality
B
maintenance
Enables autonomous creator affiliate GMV tracking and return-adjusted commission ledger calculations for influencer marketing and multi-agent campaign workflows.
Updated a month ago (2026-09-02 10:24 UTC)
8
-
linkbit-mcp
Marketing
elkinegor
A
license
A
quality
B
maintenance
Enables users to shorten links, bulk create URLs, generate QR codes, manage and disable links, and retrieve click analytics from MCP clients like Claude, ChatGPT, Cursor, and n8n.
Updated 4 days ago (2026-09-29 07:42 UTC)
9
MIT

Dub MCP Server & CLI

Two ways to use it

Command line

MCP server, for your AI app

Which one

Features

Contents

1. What you can ask it

2. Quick install

3. Set up Dub access

Private workspace access

Plans, quotas and provider effects

Rotation and revocation

4. Connect your client

5. Check it works

6. Output, flags and exit codes

7. MCP or CLI and token cost

8. Every tool and argument

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

list_accounts

get_operation_schema

preview_link_batch

submit_link_batch

Native request contracts