/api/v6/urlshortener/linksCreate a short link
Publish a short link on one of your domains, with a generated code or your own alias.
Scope and limits
API key with the urlshortener service enabled
35 requests per second
Supports Idempotency-Key
- The destination URL allows up to 2048 characters.
- Destinations pointing to private or reserved hosts are rejected.
Creates a short link on one of your domains. The code is generated automatically (base36, 7 characters) unless you pass your own alias. Codes are unique per domain: the same alias can exist on two different domains.
Headers
Idempotency-KeyA-Za-z0-9_-). Repeating the same operation with the same key returns the original response without running it again. See the idempotency guide.Request body
application/jsonurlhttp or https, max 2048 characters. Private or reserved hosts are rejected.domainGET /api/v6/urlshortener/domains). Defaults to your default domain.alias- and _). Must be free on the domain and not a reserved word.expiresAt410.{
"url": "https://example.com/landing?utm_source=sms",
"domain": "go.acme.co",
"alias": "spring-sale"
}Responses
Link created. In the extreme case where the immediate re-read fails, data carries only code and domain.
{
"success": true,
"data": {
"id": 1024,
"code": "a1b2c3d",
"domain": "go.acme.co",
"shortUrl": "https://go.acme.co/a1b2c3d",
"longUrl": "https://example.com/landing?utm_source=sms",
"alias": false,
"active": true,
"expiresAt": null,
"createdAt": "2026-06-01T15:04:05Z",
"clicks": 0,
"uniqueClicks": 0,
"lastClickAt": null
},
"meta": {
"requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6",
"timestamp": "2026-06-01T15:04:05+00:00",
"responseTimeMs": 7.2
}
}Invalid input (destination URL, alias, expiry or domain), or a malformed idempotency key.
Invalid or missing credentials.
The organization is read-only, or cannot create the link.
The alias is already taken on this domain, or a request with the same idempotency key is still in progress.
The idempotency key was reused with a different body.
Request limit exceeded.
Possible errors
Codes this endpoint can return in error.code. The full detail lives in the catalog.
AUTH_REQUIREDNo Bearer token was sent, and every call requires one.401AUTH_INVALID_KEYThe API key is not recognized: wrong format, revoked or expired.401AUTH_SERVICE_NOT_ALLOWEDThe key is not allowed to use the service behind this endpoint.403ACCOUNT_READ_ONLYRead-only mode: only GET, HEAD and OPTIONS pass.400URL_INVALIDThe destination URL is malformed.400URL_SCHEME_NOT_ALLOWEDOnly http/https destinations are allowed.400URL_TOO_LONGThe destination URL exceeds the maximum length.400URL_BLOCKED_HOSTThe destination host is private or reserved.400ALIAS_INVALIDThe custom alias doesn't match the allowed format.409ALIAS_TAKENThe alias is already used on this domain.409ALIAS_RESERVEDThe alias is a reserved word.400EXPIRES_AT_INVALIDexpiresAt must be a future ISO date-time.400DOMAIN_NOT_ALLOWEDThe chosen domain isn't available to your account.500CODE_GENERATION_FAILEDCould not allocate a unique code.400IDEMPOTENCY_KEY_INVALIDThe idempotency key does not match the format.409IDEMPOTENCY_IN_PROGRESSThe first request with that key is still in progress.422IDEMPOTENCY_KEY_REUSEDThe key already exists, but with a different body.429RATE_TPS_EXCEEDEDYou exceeded your organization quota for this endpoint.