POST
/
links
curl --request POST \
  --url https://api.dub.co/links \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://google/com",
  "domain": "<string>",
  "key": "<string>",
  "externalId": "123456",
  "prefix": "<string>",
  "archived": true,
  "publicStats": true,
  "tagId": "<string>",
  "tagIds": [
    "clux0rgak00011..."
  ],
  "tagNames": "<string>",
  "comments": "<string>",
  "expiresAt": "<string>",
  "expiredUrl": "<string>",
  "password": "<string>",
  "proxy": true,
  "title": "<string>",
  "description": "<string>",
  "image": "<string>",
  "rewrite": true,
  "ios": "<string>",
  "android": "<string>",
  "geo": {
    "AF": "<string>",
    "AL": "<string>",
    "DZ": "<string>",
    "AS": "<string>",
    "AD": "<string>",
    "AO": "<string>",
    "AI": "<string>",
    "AQ": "<string>",
    "AG": "<string>",
    "AR": "<string>",
    "AM": "<string>",
    "AW": "<string>",
    "AU": "<string>",
    "AT": "<string>",
    "AZ": "<string>",
    "BS": "<string>",
    "BH": "<string>",
    "BD": "<string>",
    "BB": "<string>",
    "BY": "<string>",
    "BE": "<string>",
    "BZ": "<string>",
    "BJ": "<string>",
    "BM": "<string>",
    "BT": "<string>",
    "BO": "<string>",
    "BA": "<string>",
    "BW": "<string>",
    "BV": "<string>",
    "BR": "<string>",
    "IO": "<string>",
    "BN": "<string>",
    "BG": "<string>",
    "BF": "<string>",
    "BI": "<string>",
    "KH": "<string>",
    "CM": "<string>",
    "CA": "<string>",
    "CV": "<string>",
    "KY": "<string>",
    "CF": "<string>",
    "TD": "<string>",
    "CL": "<string>",
    "CN": "<string>",
    "CX": "<string>",
    "CC": "<string>",
    "CO": "<string>",
    "KM": "<string>",
    "CG": "<string>",
    "CD": "<string>",
    "CK": "<string>",
    "CR": "<string>",
    "CI": "<string>",
    "HR": "<string>",
    "CU": "<string>",
    "CY": "<string>",
    "CZ": "<string>",
    "DK": "<string>",
    "DJ": "<string>",
    "DM": "<string>",
    "DO": "<string>",
    "EC": "<string>",
    "EG": "<string>",
    "SV": "<string>",
    "GQ": "<string>",
    "ER": "<string>",
    "EE": "<string>",
    "ET": "<string>",
    "FK": "<string>",
    "FO": "<string>",
    "FJ": "<string>",
    "FI": "<string>",
    "FR": "<string>",
    "GF": "<string>",
    "PF": "<string>",
    "TF": "<string>",
    "GA": "<string>",
    "GM": "<string>",
    "GE": "<string>",
    "DE": "<string>",
    "GH": "<string>",
    "GI": "<string>",
    "GR": "<string>",
    "GL": "<string>",
    "GD": "<string>",
    "GP": "<string>",
    "GU": "<string>",
    "GT": "<string>",
    "GN": "<string>",
    "GW": "<string>",
    "GY": "<string>",
    "HT": "<string>",
    "HM": "<string>",
    "VA": "<string>",
    "HN": "<string>",
    "HK": "<string>",
    "HU": "<string>",
    "IS": "<string>",
    "IN": "<string>",
    "ID": "<string>",
    "IR": "<string>",
    "IQ": "<string>",
    "IE": "<string>",
    "IL": "<string>",
    "IT": "<string>",
    "JM": "<string>",
    "JP": "<string>",
    "JO": "<string>",
    "KZ": "<string>",
    "KE": "<string>",
    "KI": "<string>",
    "KP": "<string>",
    "KR": "<string>",
    "KW": "<string>",
    "KG": "<string>",
    "LA": "<string>",
    "LV": "<string>",
    "LB": "<string>",
    "LS": "<string>",
    "LR": "<string>",
    "LY": "<string>",
    "LI": "<string>",
    "LT": "<string>",
    "LU": "<string>",
    "MO": "<string>",
    "MG": "<string>",
    "MW": "<string>",
    "MY": "<string>",
    "MV": "<string>",
    "ML": "<string>",
    "MT": "<string>",
    "MH": "<string>",
    "MQ": "<string>",
    "MR": "<string>",
    "MU": "<string>",
    "YT": "<string>",
    "MX": "<string>",
    "FM": "<string>",
    "MD": "<string>",
    "MC": "<string>",
    "MN": "<string>",
    "MS": "<string>",
    "MA": "<string>",
    "MZ": "<string>",
    "MM": "<string>",
    "NA": "<string>",
    "NR": "<string>",
    "NP": "<string>",
    "NL": "<string>",
    "NC": "<string>",
    "NZ": "<string>",
    "NI": "<string>",
    "NE": "<string>",
    "NG": "<string>",
    "NU": "<string>",
    "NF": "<string>",
    "MK": "<string>",
    "MP": "<string>",
    "NO": "<string>",
    "OM": "<string>",
    "PK": "<string>",
    "PW": "<string>",
    "PS": "<string>",
    "PA": "<string>",
    "PG": "<string>",
    "PY": "<string>",
    "PE": "<string>",
    "PH": "<string>",
    "PN": "<string>",
    "PL": "<string>",
    "PT": "<string>",
    "PR": "<string>",
    "QA": "<string>",
    "RE": "<string>",
    "RO": "<string>",
    "RU": "<string>",
    "RW": "<string>",
    "SH": "<string>",
    "KN": "<string>",
    "LC": "<string>",
    "PM": "<string>",
    "VC": "<string>",
    "WS": "<string>",
    "SM": "<string>",
    "ST": "<string>",
    "SA": "<string>",
    "SN": "<string>",
    "SC": "<string>",
    "SL": "<string>",
    "SG": "<string>",
    "SK": "<string>",
    "SI": "<string>",
    "SB": "<string>",
    "SO": "<string>",
    "ZA": "<string>",
    "GS": "<string>",
    "ES": "<string>",
    "LK": "<string>",
    "SD": "<string>",
    "SR": "<string>",
    "SJ": "<string>",
    "SZ": "<string>",
    "SE": "<string>",
    "CH": "<string>",
    "SY": "<string>",
    "TW": "<string>",
    "TJ": "<string>",
    "TZ": "<string>",
    "TH": "<string>",
    "TL": "<string>",
    "TG": "<string>",
    "TK": "<string>",
    "TO": "<string>",
    "TT": "<string>",
    "TN": "<string>",
    "TR": "<string>",
    "TM": "<string>",
    "TC": "<string>",
    "TV": "<string>",
    "UG": "<string>",
    "UA": "<string>",
    "AE": "<string>",
    "GB": "<string>",
    "US": "<string>",
    "UM": "<string>",
    "UY": "<string>",
    "UZ": "<string>",
    "VU": "<string>",
    "VE": "<string>",
    "VN": "<string>",
    "VG": "<string>",
    "VI": "<string>",
    "WF": "<string>",
    "EH": "<string>",
    "YE": "<string>",
    "ZM": "<string>",
    "ZW": "<string>",
    "AX": "<string>",
    "BQ": "<string>",
    "CW": "<string>",
    "GG": "<string>",
    "IM": "<string>",
    "JE": "<string>",
    "ME": "<string>",
    "BL": "<string>",
    "MF": "<string>",
    "RS": "<string>",
    "SX": "<string>",
    "SS": "<string>",
    "XK": "<string>"
  }
}'
{
  "id": "<string>",
  "domain": "<string>",
  "key": "<string>",
  "externalId": "<string>",
  "url": "<string>",
  "archived": true,
  "expiresAt": "<string>",
  "expiredUrl": "<string>",
  "password": "<string>",
  "proxy": true,
  "title": "<string>",
  "description": "<string>",
  "image": "<string>",
  "rewrite": true,
  "ios": "<string>",
  "android": "<string>",
  "geo": {
    "AF": "<string>",
    "AL": "<string>",
    "DZ": "<string>",
    "AS": "<string>",
    "AD": "<string>",
    "AO": "<string>",
    "AI": "<string>",
    "AQ": "<string>",
    "AG": "<string>",
    "AR": "<string>",
    "AM": "<string>",
    "AW": "<string>",
    "AU": "<string>",
    "AT": "<string>",
    "AZ": "<string>",
    "BS": "<string>",
    "BH": "<string>",
    "BD": "<string>",
    "BB": "<string>",
    "BY": "<string>",
    "BE": "<string>",
    "BZ": "<string>",
    "BJ": "<string>",
    "BM": "<string>",
    "BT": "<string>",
    "BO": "<string>",
    "BA": "<string>",
    "BW": "<string>",
    "BV": "<string>",
    "BR": "<string>",
    "IO": "<string>",
    "BN": "<string>",
    "BG": "<string>",
    "BF": "<string>",
    "BI": "<string>",
    "KH": "<string>",
    "CM": "<string>",
    "CA": "<string>",
    "CV": "<string>",
    "KY": "<string>",
    "CF": "<string>",
    "TD": "<string>",
    "CL": "<string>",
    "CN": "<string>",
    "CX": "<string>",
    "CC": "<string>",
    "CO": "<string>",
    "KM": "<string>",
    "CG": "<string>",
    "CD": "<string>",
    "CK": "<string>",
    "CR": "<string>",
    "CI": "<string>",
    "HR": "<string>",
    "CU": "<string>",
    "CY": "<string>",
    "CZ": "<string>",
    "DK": "<string>",
    "DJ": "<string>",
    "DM": "<string>",
    "DO": "<string>",
    "EC": "<string>",
    "EG": "<string>",
    "SV": "<string>",
    "GQ": "<string>",
    "ER": "<string>",
    "EE": "<string>",
    "ET": "<string>",
    "FK": "<string>",
    "FO": "<string>",
    "FJ": "<string>",
    "FI": "<string>",
    "FR": "<string>",
    "GF": "<string>",
    "PF": "<string>",
    "TF": "<string>",
    "GA": "<string>",
    "GM": "<string>",
    "GE": "<string>",
    "DE": "<string>",
    "GH": "<string>",
    "GI": "<string>",
    "GR": "<string>",
    "GL": "<string>",
    "GD": "<string>",
    "GP": "<string>",
    "GU": "<string>",
    "GT": "<string>",
    "GN": "<string>",
    "GW": "<string>",
    "GY": "<string>",
    "HT": "<string>",
    "HM": "<string>",
    "VA": "<string>",
    "HN": "<string>",
    "HK": "<string>",
    "HU": "<string>",
    "IS": "<string>",
    "IN": "<string>",
    "ID": "<string>",
    "IR": "<string>",
    "IQ": "<string>",
    "IE": "<string>",
    "IL": "<string>",
    "IT": "<string>",
    "JM": "<string>",
    "JP": "<string>",
    "JO": "<string>",
    "KZ": "<string>",
    "KE": "<string>",
    "KI": "<string>",
    "KP": "<string>",
    "KR": "<string>",
    "KW": "<string>",
    "KG": "<string>",
    "LA": "<string>",
    "LV": "<string>",
    "LB": "<string>",
    "LS": "<string>",
    "LR": "<string>",
    "LY": "<string>",
    "LI": "<string>",
    "LT": "<string>",
    "LU": "<string>",
    "MO": "<string>",
    "MG": "<string>",
    "MW": "<string>",
    "MY": "<string>",
    "MV": "<string>",
    "ML": "<string>",
    "MT": "<string>",
    "MH": "<string>",
    "MQ": "<string>",
    "MR": "<string>",
    "MU": "<string>",
    "YT": "<string>",
    "MX": "<string>",
    "FM": "<string>",
    "MD": "<string>",
    "MC": "<string>",
    "MN": "<string>",
    "MS": "<string>",
    "MA": "<string>",
    "MZ": "<string>",
    "MM": "<string>",
    "NA": "<string>",
    "NR": "<string>",
    "NP": "<string>",
    "NL": "<string>",
    "NC": "<string>",
    "NZ": "<string>",
    "NI": "<string>",
    "NE": "<string>",
    "NG": "<string>",
    "NU": "<string>",
    "NF": "<string>",
    "MK": "<string>",
    "MP": "<string>",
    "NO": "<string>",
    "OM": "<string>",
    "PK": "<string>",
    "PW": "<string>",
    "PS": "<string>",
    "PA": "<string>",
    "PG": "<string>",
    "PY": "<string>",
    "PE": "<string>",
    "PH": "<string>",
    "PN": "<string>",
    "PL": "<string>",
    "PT": "<string>",
    "PR": "<string>",
    "QA": "<string>",
    "RE": "<string>",
    "RO": "<string>",
    "RU": "<string>",
    "RW": "<string>",
    "SH": "<string>",
    "KN": "<string>",
    "LC": "<string>",
    "PM": "<string>",
    "VC": "<string>",
    "WS": "<string>",
    "SM": "<string>",
    "ST": "<string>",
    "SA": "<string>",
    "SN": "<string>",
    "SC": "<string>",
    "SL": "<string>",
    "SG": "<string>",
    "SK": "<string>",
    "SI": "<string>",
    "SB": "<string>",
    "SO": "<string>",
    "ZA": "<string>",
    "GS": "<string>",
    "ES": "<string>",
    "LK": "<string>",
    "SD": "<string>",
    "SR": "<string>",
    "SJ": "<string>",
    "SZ": "<string>",
    "SE": "<string>",
    "CH": "<string>",
    "SY": "<string>",
    "TW": "<string>",
    "TJ": "<string>",
    "TZ": "<string>",
    "TH": "<string>",
    "TL": "<string>",
    "TG": "<string>",
    "TK": "<string>",
    "TO": "<string>",
    "TT": "<string>",
    "TN": "<string>",
    "TR": "<string>",
    "TM": "<string>",
    "TC": "<string>",
    "TV": "<string>",
    "UG": "<string>",
    "UA": "<string>",
    "AE": "<string>",
    "GB": "<string>",
    "US": "<string>",
    "UM": "<string>",
    "UY": "<string>",
    "UZ": "<string>",
    "VU": "<string>",
    "VE": "<string>",
    "VN": "<string>",
    "VG": "<string>",
    "VI": "<string>",
    "WF": "<string>",
    "EH": "<string>",
    "YE": "<string>",
    "ZM": "<string>",
    "ZW": "<string>",
    "AX": "<string>",
    "BQ": "<string>",
    "CW": "<string>",
    "GG": "<string>",
    "IM": "<string>",
    "JE": "<string>",
    "ME": "<string>",
    "BL": "<string>",
    "MF": "<string>",
    "RS": "<string>",
    "SX": "<string>",
    "SS": "<string>",
    "XK": "<string>"
  },
  "publicStats": true,
  "tagId": "<string>",
  "tags": [
    {
      "id": "<string>",
      "name": "<string>",
      "color": "red"
    }
  ],
  "comments": "<string>",
  "shortLink": "<string>",
  "qrCode": "<string>",
  "utm_source": "<string>",
  "utm_medium": "<string>",
  "utm_campaign": "<string>",
  "utm_term": "<string>",
  "utm_content": "<string>",
  "userId": "<string>",
  "workspaceId": "<string>",
  "clicks": 123,
  "lastClicked": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "projectId": "<string>"
}

Authorizations

Authorization
string
headerrequired

Default authentication mechanism

Query Parameters

workspaceId
string
required

The ID of the workspace.

projectSlug
string
deprecated

The slug of the project. This field is deprecated – use workspaceId instead.

Body

application/json
url
string
required

The destination URL of the short link.

domain
string

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

key
string

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

externalId
string | null

This is the ID of the link in your database. If set, it can be used to identify the link in the future. Must be prefixed with ext_ when passed as a query parameter.

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

archived
boolean
default: false

Whether the short link is archived.

publicStats
boolean
default: false

Whether the short link's stats are publicly accessible.

tagId
string | null
deprecated

The unique ID of the tag assigned to the short link. This field is deprecated – use tagIds instead.

tagIds

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

tagNames

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

comments
string | null

The comments for the short link.

expiresAt
string | null

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

expiredUrl
string | null

The URL to redirect to when the short link has expired.

password
string | null

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

proxy
boolean
default: false

Whether the short link uses Custom Social Media Cards feature.

title
string | null

The title of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

description
string | null

The description of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

image
string | null

The image of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

rewrite
boolean
default: false

Whether the short link uses link cloaking.

ios
string | null

The iOS destination URL for the short link for iOS device targeting.

android
string | null

The Android destination URL for the short link for Android device targeting.

geo
object | null

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

Response

200 - application/json
id
string
required

The unique ID of the short link.

domain
string
required

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

key
string
required

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

externalId
string | null
required

This is the ID of the link in your database. If set, it can be used to identify the link in the future. Must be prefixed with 'ext_' when passed as a query parameter.

url
string
required

The destination URL of the short link.

archived
boolean
default: falserequired

Whether the short link is archived.

expiresAt
string | null
required

The date and time when the short link will expire in ISO-8601 format.

expiredUrl
string | null
required

The URL to redirect to when the short link has expired.

password
string | null
required

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

proxy
boolean
default: falserequired

Whether the short link uses Custom Social Media Cards feature.

title
string | null
required

The title of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

description
string | null
required

The description of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

image
string | null
required

The image of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

rewrite
boolean
default: falserequired

Whether the short link uses link cloaking.

ios
string | null
required

The iOS destination URL for the short link for iOS device targeting.

android
string | null
required

The Android destination URL for the short link for Android device targeting.

geo
object | null
required

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

publicStats
boolean
default: falserequired

Whether the short link's stats are publicly accessible.

tagId
string | null
requireddeprecated

The unique ID of the tag assigned to the short link. This field is deprecated – use tags instead.

tags
object[] | null
required

The tags assigned to the short link.

comments
string | null
required

The comments for the short link.

shortLink
string
required

The full URL of the short link, including the https protocol (e.g. https://dub.sh/try).

qrCode
string
required

The full URL of the QR code for the short link (e.g. https://api.dub.co/qr?url=https://dub.sh/try).

utm_source
string | null
required

The UTM source of the short link.

utm_medium
string | null
required

The UTM medium of the short link.

utm_campaign
string | null
required

The UTM campaign of the short link.

utm_term
string | null
required

The UTM term of the short link.

utm_content
string | null
required

The UTM content of the short link.

userId
string
required

The user ID of the creator of the short link.

workspaceId
string
required

The workspace ID of the short link.

clicks
number
default: 0required

The number of clicks on the short link.

lastClicked
string | null
required

The date and time when the short link was last clicked.

createdAt
string
required

The date and time when the short link was created.

updatedAt
string
required

The date and time when the short link was last updated.

projectId
string
requireddeprecated

The project ID of the short link. This field is deprecated – use workspaceId instead.

Was this page helpful?

ErrorsRetrieve a link