Skip to content

Links

Availability: The links API is available on every plan, including Free. Keys need links:read to read links and links:write to change them. Advanced link options need the plans that include them.

Create, read, update, suspend and re-enable short links, and end A/B tests. Every request needs an API key — see authentication. Refer to a link by its public_id, which the API returns when you create or list links. For a link’s clicks, see analytics.

Endpoints

MethodPathScope
POST/api/v1/linkslinks:write
GET/api/v1/linkslinks:read
GET/api/v1/links/{public_id}links:read
PATCH/api/v1/links/{public_id}links:write
DELETE/api/v1/links/{public_id}links:write
POST/api/v1/links/{public_id}/enablelinks:write
POST/api/v1/links/{public_id}/ab/winnerlinks:write

Create a link

POST /api/v1/links creates a link. Only url and title are required; every other field is optional. A field the endpoint doesn’t know is refused with 400 unsupported_fields, listing the names in details.fields, rather than ignored.

Basics

FieldTypeRequiredNotes
urlstringyesThe destination, http or https; without a scheme, https:// is added. Up to 4,096 characters. A destination that is itself a short link is refused.
titlestringyesThe link’s title.
descriptionstringnoA description.
custom_codestringnoYour own short code. See short codes. Starter and higher.
short_domainstringnoThe short domain, such as go.example.com. Defaults to the workspace’s default domain.

Placement and organization

FieldTypeRequiredNotes
workspace_public_idstringnoThe workspace. Defaults to a workspace key’s workspace, or your personal workspace.
team_public_idsarray of stringsnoLimit the link to these teams. team_public_id (one string) is the older form.
tag_public_idsarray of stringsnoTags to apply, by public ID.
utm_template_idstringnoA UTM template’s public ID; its values replace the utm_* fields.
utm_source, utm_medium, utm_campaign, utm_term, utm_content, utm_idstringnoUTM parameters, up to 100 characters each, without line breaks.

Schedule

FieldTypeRequiredNotes
starts_atstringnoWhen the link goes live, RFC 3339 (2026-07-09T12:30:00Z). Until then the link is scheduled. Starter and higher.
expires_atstringnoWhen the link expires, RFC 3339. Starter and higher.
expiration_actionstringwith expires_atsuspended (the link stops working) or archive (it keeps redirecting, without analytics). There’s no default.

Both times must be at least 30 minutes from now, and the start must be before the expiry. See link expiration.

Access

FieldTypeRequiredNotes
access_modestringnopassword (Starter and higher) or jit, one-time email codes (Professional and higher). Sending password alone implies password.
passwordstringwith password modeAt least 12 characters, at most 72 bytes, and not a common password. Not allowed with jit.
access_duration_hoursintegernoHow long an unlock lasts: 1, 24, 168 (the default) or 720.
jit_allowlistarray of stringsnoWho can ask for a code: addresses (ana@acme.com) or domains (@acme.com), up to 200.

See link protection.

Targeting

FieldTypeRequiredNotes
targeting_geo_overridesarray of objectsno{"target": "country:de", "url": "..."} or {"target": "region:europe", "url": "..."}. Countries use ISO codes; regions are north-america, south-america, europe, asia, africa, oceania, middle-east. Countries on Professional, regions on Agency.
language_targetsobjectnoLanguage code to URL, such as {"es": "...", "pt-BR": "..."}. Professional and higher.
device_targetsobjectnodesktop, mobile or tablet to URL. Professional and higher.
os_targetsobjectnoios, android, windows, macos or linux to URL. Agency.
browser_targetsobjectnochrome, safari, firefox, edge or opera to URL. Agency.
mobile_target_ios, mobile_target_androidstringnoThe same as the ios and android entries of os_targets. Agency.
targeting_priorityarray of stringsnoThe order rule types are checked in. Default: regional, os, browser, device, language.

See targeting.

A/B testing

FieldTypeRequiredNotes
ab_variantsarray of objectsno2 to 4 destinations, each {"url": "...", "split_percent": 50}. Splits you leave out share what’s left of 100%. Professional and higher.
ab_destination, ab_split_percentstring, integernoThe older two-way form: one alternative destination, and the main destination’s share.

See A/B testing.

Conversions

FieldTypeRequiredNotes
conversion_enabledbooleannoTrack conversions for the link. The workspace must have conversion tracking on. Professional and higher.
conversion_attribution_modelstringnoinherit, first_touch or last_touch.
conversion_attribution_window_daysintegerno1 to 90, or 0 for the workspace’s window.
attributionobjectnoWho gets credit for the link’s conversions. type is workspace, workspace_member (with user_public_id), team (with team_public_id), external_partner (with partner_public_id), or campaign / custom (with external_id or label, up to 255 characters).

If the workspace requires tracking on every link, or enforces its attribution settings, values that contradict it return 409.

Share preview and cloaking

FieldTypeRequiredNotes
preview_titlestringnoUp to 120 characters.
preview_descriptionstringnoUp to 240 characters.
preview_imagestringnoAn image URL.
preview_custombooleannoUse the custom preview. Setting any preview field turns it on.
cloaking_enabledbooleannoShow the destination under the short URL. Refused with 400 cloaking_incompatible if the destination doesn’t allow framing or isn’t https.

A custom share preview needs Starter or higher. See create a link and cloaking.

Example

curl -X POST https://app.shortn.link/api/v1/links \
  -H "Authorization: Bearer $SHORTN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/spring",
    "title": "Spring campaign",
    "tag_public_ids": ["8c4f2a6e-1b3d-4e5f-9a7b-2c1d0e9f8a7b"],
    "utm_source": "newsletter",
    "utm_medium": "email"
  }'

Returns 201:

{
  "public_id": "3f6c1e2a-9b8d-4c7e-a1f0-5d2e3c4b6a71",
  "short_url": "https://shtnl.ink/abC12x9",
  "short_code": "abC12x9",
  "original_url": "https://example.com/spring",
  "title": "Spring campaign",
  "link_status": "active",
  "security_verdict": "clean"
}
  • link_status is active, scheduled (with a future starts_at), or security_locked.
  • security_verdict, security_risk_score and security_reason_codes report the destination’s safety check. A destination that fails it creates a security_locked link, which doesn’t redirect until it’s reviewed.
  • expires_at is included when the link expires.

Errors

StatusCodeMeaning
400unsupported_fieldsA field the endpoint doesn’t accept; details.fields lists them.
400invalid_urlThe destination isn’t a valid URL.
400unsafe_destinationA destination is already a short link (on a public shortener, shtnl.ink, or a Shortn custom domain).
400title_requiredNo title.
400invalid_short_code_length, invalid_short_code_characters, reserved_short_codeThe custom_code breaks the short code rules.
400invalid_starts_at, invalid_expires_at, invalid_schedule, expiration_action_required, invalid_expiration_actionA schedule problem.
400short_domain_not_found, team_not_found, tag_not_found, utm_template_not_foundA referenced item doesn’t exist or isn’t available.
400password_required, password_too_short, password_too_long, password_too_common, password_with_jit, invalid_access_mode, invalid_access_duration, invalid_jit_allowlistAn access problem.
400invalid_geo_overrides, invalid_language_targets, invalid_device_targets, invalid_os_targets, invalid_browser_targets, invalid_ab_testA targeting or A/B problem.
400team_workspace_mismatch, utm_template_workspace_mismatch, utm_template_team_mismatch, tag_team_mismatchA team, UTM template or tag doesn’t fit the link’s workspace or teams.
400utm_value_too_long, utm_value_invalidA UTM value is too long or has line breaks.
400preview_title_too_long, preview_description_too_long, invalid_preview_imageA share preview problem.
400invalid_attribution, invalid_conversion_attribution_model, invalid_conversion_attribution_windowA conversion setting problem.
400cloaking_incompatibleThe destination can’t be cloaked.
403plan_limit_exceededYour plan doesn’t include an option you used, or you’re at the active-link limit. See plan limits.
403workspace_permission_deniedYour workspace role can’t create links.
403api_key_workspace_mismatchThe workspace or team isn’t the key’s workspace.
409custom_code_conflictThe custom_code is taken.
409workspace_conversion_tracking_disabled, conversion_tracking_locked, conversion_attribution_model_locked, conversion_attribution_window_lockedThe workspace’s conversion settings don’t allow the values.

List links

GET /api/v1/links lists links, newest first.

FieldTypeRequiredNotes
limitintegerno1 to 100. Default 50.
offsetintegernoHow many links to skip. Default 0.

An account-wide key lists the links you created, in the workspaces you still belong to. A workspace key lists every link in its workspace you can see.

curl "https://app.shortn.link/api/v1/links?limit=50&offset=0" \
  -H "Authorization: Bearer $SHORTN_API_KEY"
{
  "data": [
    {
      "public_id": "3f6c1e2a-9b8d-4c7e-a1f0-5d2e3c4b6a71",
      "original_url": "https://example.com/spring",
      "short_code": "abC12x9",
      "domain": "shtnl.ink",
      "title": "Spring campaign",
      "description": "",
      "clicks": 42,
      "active": true,
      "status": "active",
      "security_status": "clear",
      "workspace_public_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "workspace_name": "Marketing",
      "created_at": "2026-10-01T09:30:00Z",
      "updated_at": "2026-10-02T11:00:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 1,
    "has_more": false,
    "next_offset": null
  }
}

When has_more is true, request again with offset set to next_offset. With an account-wide key, links that have tags also list them under tags.

Link fields

FieldDescription
public_idThe link’s ID in the API.
original_urlThe destination.
short_code, domainThe short code and short domain; together they make the short URL.
title, descriptionThe title and description.
clicksTotal clicks.
statusactive, scheduled, suspended, archived or security_locked.
activeWhether the link redirects. false for a blocked or quarantined link, whatever its status.
security_statusclear, blocked or quarantined.
workspace_public_id, workspace_nameThe link’s workspace. workspace_name is in lists only.
tagsThe link’s tags: public_id, name, color.
starts_at, expires_atThe schedule, when set (get a link only).
created_at, updated_atRFC 3339 times.

Get a link

GET /api/v1/links/{public_id} returns one link under data, with its tags and, when set, its starts_at and expires_at.

curl https://app.shortn.link/api/v1/links/3f6c1e2a-9b8d-4c7e-a1f0-5d2e3c4b6a71 \
  -H "Authorization: Bearer $SHORTN_API_KEY"
{
  "data": {
    "public_id": "3f6c1e2a-9b8d-4c7e-a1f0-5d2e3c4b6a71",
    "original_url": "https://example.com/spring",
    "short_code": "abC12x9",
    "domain": "shtnl.ink",
    "title": "Spring campaign",
    "description": "",
    "clicks": 42,
    "active": true,
    "status": "active",
    "security_status": "clear",
    "workspace_public_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "tags": [{ "public_id": "8c4f2a6e-1b3d-4e5f-9a7b-2c1d0e9f8a7b", "name": "Spring", "color": "#14b8a6" }],
    "expires_at": "2026-12-31T23:00:00Z",
    "created_at": "2026-10-01T09:30:00Z",
    "updated_at": "2026-10-02T11:00:00Z"
  }
}

A link that doesn’t exist, or that the key can’t see, returns 404 link_not_found.

Update a link

PATCH /api/v1/links/{public_id} changes the fields you send.

FieldTypeRequiredNotes
titlestringnoCan’t be empty.
descriptionstringno
urlstringnoA new destination. Counts as a destination edit.
short_codestringnoA new short code. See short codes.
domainstringnoA new short domain, such as go.example.com, available to the link’s workspace.
statusstringnoactive, suspended, archived or scheduled.
activebooleannotrue for active, false for suspended.
team_public_idsarray of stringsnoReplace the teams the link is limited to; [] makes it workspace-wide. Send it in a request of its own. team_public_id is the older single-team form.

Scheduling, targeting, UTM, tags, access and conversion settings can’t be changed here; any other field is refused with 400 unsupported_fields. Change those in the dashboard.

curl -X PATCH https://app.shortn.link/api/v1/links/3f6c1e2a-9b8d-4c7e-a1f0-5d2e3c4b6a71 \
  -H "Authorization: Bearer $SHORTN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Spring sale", "url": "https://example.com/spring-sale"}'
{ "message": "URL updated successfully" }

A team_public_ids change also returns the result: workspace_wide, team_public_ids, team_names and teams.

Changing url counts toward your plan’s monthly destination edits (403 plan_limit_exceeded) and a limit of 20 edits per link in 24 hours (429). Moving a link to active or scheduled needs room under your active-link limit.

StatusCodeMeaning
400unsupported_fieldsA field the endpoint doesn’t change.
400invalid_status, title_required, invalid_urlAn invalid value.
400invalid_short_code_length, invalid_short_code_characters, reserved_short_codeThe new short code breaks the rules.
403plan_limit_exceededA plan limit.
409short_code_conflictThe short code is taken.
409link_security_lockedThe link’s destination failed its safety check, so it can’t be made active.

Suspend and re-enable a link

DELETE /api/v1/links/{public_id} suspends a link: it stops redirecting, and its analytics and history are kept. POST /api/v1/links/{public_id}/enable makes it active again.

curl -X DELETE https://app.shortn.link/api/v1/links/3f6c1e2a-9b8d-4c7e-a1f0-5d2e3c4b6a71 \
  -H "Authorization: Bearer $SHORTN_API_KEY"

curl -X POST https://app.shortn.link/api/v1/links/3f6c1e2a-9b8d-4c7e-a1f0-5d2e3c4b6a71/enable \
  -H "Authorization: Bearer $SHORTN_API_KEY"
{ "message": "URL disabled successfully" }

Re-enabling answers {"message": "URL enabled successfully"}, or 403 plan_limit_exceeded when you’re at your active-link limit, or 409 link_security_locked when the destination failed its safety check. To delete a link for good, use the dashboard.

End an A/B test

POST /api/v1/links/{public_id}/ab/winner ends the link’s A/B test: the winning variant’s URL becomes the destination for every visitor.

FieldTypeRequiredNotes
variantstringyesThe winner’s letter, such as B.
curl -X POST https://app.shortn.link/api/v1/links/3f6c1e2a-9b8d-4c7e-a1f0-5d2e3c4b6a71/ab/winner \
  -H "Authorization: Bearer $SHORTN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variant": "B"}'
{ "winner": "B", "test": 1, "destination": "https://example.com/spring-b" }

test is the number of the link’s test. Making the winner the destination counts as a destination edit.

StatusCodeMeaning
400variant_requiredNo variant.
400unknown_variantThe letter isn’t part of the test.
409ab_test_not_runningThe link has no running A/B test.
409ab_test_changedThe test changed meanwhile; read the link and try again.
422winner_destination_flaggedThe winner’s destination failed its safety check.

Short codes

A short code you choose (custom_code when creating, short_code when updating):

  • has 3 to 20 letters, digits, - or _;
  • isn’t a reserved word, such as login, api or health, or another path the app uses;
  • is unique across all short domains.

A code that breaks a rule returns 400 with invalid_short_code_length, invalid_short_code_characters or reserved_short_code; one that’s taken returns 409. Without a custom code, Shortn generates one.

Last updated on