canonical: https://jentic.com/apis/dub.co/dub

# Dub API

Jentic publishes the only available OpenAPI specification for Dub API, keeping it validated and agent-ready. Dub is link management infrastructure for marketing teams who need branded short links, conversion tracking, and partner programs. The API exposes 16 endpoints to create and manage short links, custom domains, tags, folders, analytics, events, partners, and workspaces. Authentication uses an OAuth-style bearer token, and the analytics surface returns aggregated click and conversion data sliced by attributes such as country, device, and referrer.

## For AI agents

Create branded short links, read click and conversion analytics, and manage marketing campaigns and partner programs through Dub.

## Scope

Does not handle email sending, ad buying, or CRM contact records - use for short link management, click analytics, and conversion attribution only.

## Capabilities

- Create short links with custom slugs and UTMs via POST /links
- Read aggregated click, lead, and sale analytics via GET /analytics
- Track lead and sale conversion events via POST `/track/lead` and POST `/track/sale`
- Register and verify custom domains via POST /domains
- Organise links with tags and folders via /tags and /folders
- Provision partners for referral programs via POST /partners
- Inspect workspace settings via GET `/workspaces/{workspaceId}`

## Use cases

### Branded Short Links for Marketing Campaigns

Generate branded short links with UTMs for paid, social, and email campaigns. The agent calls POST /links with the destination, slug, and tags, then reads GET /analytics to roll up clicks by source. Branded short links reduce trust friction in social posts and let marketing teams retire links without breaking outbound creative.

Example prompt: POST /links with url='https://example.com/landing', domain='go.brand.com', and tags=['summer-2026'], then GET /analytics?linkId={id}&interval=7d for the click totals

### Conversion Attribution for Referral Programs

Attribute leads and sales back to the referral link or partner that drove them. The agent fires POST `/track/lead` when a visitor signs up and POST `/track/sale` when they pay, passing the customer or external_id, so Dub joins the event chain back to the original click. This unlocks partner payouts and channel ROI reporting without building attribution from scratch.

Example prompt: On signup, POST `/track/lead` with clickId and external_id; on first paid invoice, POST `/track/sale` with the same external_id, amount, and currency

### Partner Program Provisioning

Spin up partners for a referral program and issue them tracked links automatically. The agent calls POST /partners to add a partner record, then POST /links to mint a referral link tagged to that partner. Combined with the conversion tracking above, this drives a self-serve affiliate flow where each partner sees their attributed leads and sales.

Example prompt: POST /partners with the partner email and name, then POST /links with the destination URL and the partner's tenantId so referrals are attributed correctly

### Agent-Driven Campaign Tooling via Jentic

Wire Dub into agent workflows that draft, publish, and measure campaigns. Through Jentic the agent searches by intent, loads the schema for /links or /analytics, and executes - the bearer token stays in your Jentic One instance, not the agent's prompt context.

Example prompt: Search Jentic for 'create a branded short link', load the Dub /links schema, and execute with a destination URL and tags supplied by the parent campaign agent

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/links` | Create a short link |
| GET | `/links` | List links |
| GET | `/analytics` | Retrieve click and conversion analytics |
| POST | `/track/lead` | Track a lead conversion event |
| POST | `/track/sale` | Track a sale conversion event |
| POST | `/domains` | Register a custom domain |
| POST | `/partners` | Create a referral partner |

## Key resources

- **Links** — Create, read, update, and delete short links under /links
- **Analytics** — Aggregated click and conversion analytics under /analytics and event records under /events
- **Track** — Record lead and sale conversion events under `/track/lead` and `/track/sale`
- **Domains** — Register and manage custom branded domains under /domains
- **Partners** — Manage referral partners under /partners

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 69 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 87 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 51 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 100 / 100
- **View full report:** https://jentic.com/apis/dub.co/dub/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Dub API by hand means handling its bearer auth and building the link, analytics, and conversion-tracking calls yourself. Through Jentic you install once, import Dub from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Dub identifies links and events through the request body and query, so you limit the agent to the operations it needs, such as creating a link or reading click analytics. You choose which operations are allowed, so tracking sales or creating domains is not included unless you add it.
- **Credential handling:** Your Dub bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a branded short link' or 'read click analytics', and Jentic returns the matching Dub operation with its input schema so the agent calls the right endpoint without browsing the docs.

## Related APIs

- **Rebrandly API** — Branded short links with deep custom domain support but a thinner conversion-tracking surface than Dub
- **Short.io API** — Short link platform with click analytics and webhook-driven workflows
- **TinyURL API** — Lightweight URL shortener without the analytics or partner surface

## FAQ

### Why is there no official OpenAPI spec for Dub API?

Dub does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Dub API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Dub API use?

Dub uses an OAuth-style bearer token in the Authorization header. Through Jentic the token is stored in the encrypted vault and injected at execution, so the raw bearer never enters the agent's prompt.

### Can I create branded short links with the Dub API?

Yes. POST /links accepts the destination URL plus optional domain, slug, and tags, and returns a short link record. Register the branded domain first via POST /domains.

### How do I track conversions with the Dub API?

Fire POST `/track/lead` when a click becomes a signup, then POST `/track/sale` on the first paid event with the same external_id. Dub joins those calls to the originating click for attribution.

### What are the rate limits for the Dub API?

The OpenAPI spec does not declare rate limits. Dub publishes per-plan limits in its dashboard; have your agent retry HTTP 429 with exponential backoff.

### How do I read campaign analytics through Jentic?

Search Jentic for 'retrieve link analytics', load the schema for GET /analytics, and execute with a linkId and interval (for example 7d). Install with pip install jentic.

### Does the Dub API support a referral partner program?

Yes. POST /partners creates a partner record and POST /links can mint a referral link attributed to that partner, which combines with `/track/lead` and `/track/sale` for end-to-end attribution.

### Can I limit what my agent is allowed to do with the Dub API?

Yes. Because Jentic One is self-hosted, your own rules decide which Dub operations and credentials the agent may use. You can allow only the endpoints a given workflow needs, such as POST /links to create a branded short link or GET /analytics to read click data, while leaving out operations like POST `/track/sale` or POST /domains unless you explicitly add them. Dub identifies links and events through the request body and query, so scoping happens at the operation level you control.