Skip to main content
POST
Create a permanent link

Body

application/json
destination
string<uri>
required

Where the code resolves to. http/https only; localhost, private ranges and cloud metadata endpoints are refused. Stored normalised, so HTTPS://Example.COM and https://example.com/ are the same link.

Minimum string length: 1
Example:

"https://example.com/spring-menu"

slug
string

The path segment the code resolves on. Drawn from an unambiguous alphabet (no 0/O, no 1/l/I) because people type these off printed material. Omit on create and one is allocated for you.

Example:

"m4rq7bd"

domain_id
string

A verified custom domain to mint the code on. Requires a subscription.

Example:

"dom_2YgQk1p8fT3mN7wCxRvBdLsHjZa"

Response

The link was created. A key-authenticated call gets Link; a call that paid gets PaidLink, which adds the printable short URL and — on the first paid link of a new machine account — the API key to repoint it.

A permanent link. Once issued, it never stops resolving.

id
string
required
Example:

"lnk_2YgQk1p8fT3mN7wCxRvBdLsHjZa"

slug
string
required

The path segment the code resolves on. Drawn from an unambiguous alphabet (no 0/O, no 1/l/I) because people type these off printed material. Omit on create and one is allocated for you.

Example:

"m4rq7bd"

destination
string<uri>
required

Where the code resolves to. http/https only; localhost, private ranges and cloud metadata endpoints are refused. Stored normalised, so HTTPS://Example.COM and https://example.com/ are the same link.

Minimum string length: 1
Example:

"https://example.com/spring-menu"

host
string | null
required

The custom domain this link resolves on, or null for the default domain.

Example:

null

status
integer
required

0 = active, 1 = quarantine, 2 = abuse. Every link is created in quarantine, which forces a live safety check on each resolution until the link earns release: three clean checks once it is at least seven days old. Quarantine is a property of the link, never of the account — it is not a paywall and a quarantined link still resolves.

Example:

1