Links
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
| Method | Path | Scope |
|---|---|---|
POST | /api/v1/links | links:write |
GET | /api/v1/links | links: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}/enable | links:write |
POST | /api/v1/links/{public_id}/ab/winner | links: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
| Field | Type | Required | Notes |
|---|---|---|---|
url | string | yes | The 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. |
title | string | yes | The link’s title. |
description | string | no | A description. |
custom_code | string | no | Your own short code. See short codes. Starter and higher. |
short_domain | string | no | The short domain, such as go.example.com. Defaults to the workspace’s default domain. |
Placement and organization
| Field | Type | Required | Notes |
|---|---|---|---|
workspace_public_id | string | no | The workspace. Defaults to a workspace key’s workspace, or your personal workspace. |
team_public_ids | array of strings | no | Limit the link to these teams. team_public_id (one string) is the older form. |
tag_public_ids | array of strings | no | Tags to apply, by public ID. |
utm_template_id | string | no | A UTM template’s public ID; its values replace the utm_* fields. |
utm_source, utm_medium, utm_campaign, utm_term, utm_content, utm_id | string | no | UTM parameters, up to 100 characters each, without line breaks. |
Schedule
| Field | Type | Required | Notes |
|---|---|---|---|
starts_at | string | no | When the link goes live, RFC 3339 (2026-07-09T12:30:00Z). Until then the link is scheduled. Starter and higher. |
expires_at | string | no | When the link expires, RFC 3339. Starter and higher. |
expiration_action | string | with expires_at | suspended (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
| Field | Type | Required | Notes |
|---|---|---|---|
access_mode | string | no | password (Starter and higher) or jit, one-time email codes (Professional and higher). Sending password alone implies password. |
password | string | with password mode | At least 12 characters, at most 72 bytes, and not a common password. Not allowed with jit. |
access_duration_hours | integer | no | How long an unlock lasts: 1, 24, 168 (the default) or 720. |
jit_allowlist | array of strings | no | Who can ask for a code: addresses (ana@acme.com) or domains (@acme.com), up to 200. |
See link protection.
Targeting
| Field | Type | Required | Notes |
|---|---|---|---|
targeting_geo_overrides | array of objects | no | {"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_targets | object | no | Language code to URL, such as {"es": "...", "pt-BR": "..."}. Professional and higher. |
device_targets | object | no | desktop, mobile or tablet to URL. Professional and higher. |
os_targets | object | no | ios, android, windows, macos or linux to URL. Agency. |
browser_targets | object | no | chrome, safari, firefox, edge or opera to URL. Agency. |
mobile_target_ios, mobile_target_android | string | no | The same as the ios and android entries of os_targets. Agency. |
targeting_priority | array of strings | no | The order rule types are checked in. Default: regional, os, browser, device, language. |
See targeting.
A/B testing
| Field | Type | Required | Notes |
|---|---|---|---|
ab_variants | array of objects | no | 2 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_percent | string, integer | no | The older two-way form: one alternative destination, and the main destination’s share. |
See A/B testing.
Conversions
| Field | Type | Required | Notes |
|---|---|---|---|
conversion_enabled | boolean | no | Track conversions for the link. The workspace must have conversion tracking on. Professional and higher. |
conversion_attribution_model | string | no | inherit, first_touch or last_touch. |
conversion_attribution_window_days | integer | no | 1 to 90, or 0 for the workspace’s window. |
attribution | object | no | Who 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
| Field | Type | Required | Notes |
|---|---|---|---|
preview_title | string | no | Up to 120 characters. |
preview_description | string | no | Up to 240 characters. |
preview_image | string | no | An image URL. |
preview_custom | boolean | no | Use the custom preview. Setting any preview field turns it on. |
cloaking_enabled | boolean | no | Show 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_statusisactive,scheduled(with a futurestarts_at), orsecurity_locked.security_verdict,security_risk_scoreandsecurity_reason_codesreport the destination’s safety check. A destination that fails it creates asecurity_lockedlink, which doesn’t redirect until it’s reviewed.expires_atis included when the link expires.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | unsupported_fields | A field the endpoint doesn’t accept; details.fields lists them. |
400 | invalid_url | The destination isn’t a valid URL. |
400 | unsafe_destination | A destination is already a short link (on a public shortener, shtnl.ink, or a Shortn custom domain). |
400 | title_required | No title. |
400 | invalid_short_code_length, invalid_short_code_characters, reserved_short_code | The custom_code breaks the short code rules. |
400 | invalid_starts_at, invalid_expires_at, invalid_schedule, expiration_action_required, invalid_expiration_action | A schedule problem. |
400 | short_domain_not_found, team_not_found, tag_not_found, utm_template_not_found | A referenced item doesn’t exist or isn’t available. |
400 | password_required, password_too_short, password_too_long, password_too_common, password_with_jit, invalid_access_mode, invalid_access_duration, invalid_jit_allowlist | An access problem. |
400 | invalid_geo_overrides, invalid_language_targets, invalid_device_targets, invalid_os_targets, invalid_browser_targets, invalid_ab_test | A targeting or A/B problem. |
400 | team_workspace_mismatch, utm_template_workspace_mismatch, utm_template_team_mismatch, tag_team_mismatch | A team, UTM template or tag doesn’t fit the link’s workspace or teams. |
400 | utm_value_too_long, utm_value_invalid | A UTM value is too long or has line breaks. |
400 | preview_title_too_long, preview_description_too_long, invalid_preview_image | A share preview problem. |
400 | invalid_attribution, invalid_conversion_attribution_model, invalid_conversion_attribution_window | A conversion setting problem. |
400 | cloaking_incompatible | The destination can’t be cloaked. |
403 | plan_limit_exceeded | Your plan doesn’t include an option you used, or you’re at the active-link limit. See plan limits. |
403 | workspace_permission_denied | Your workspace role can’t create links. |
403 | api_key_workspace_mismatch | The workspace or team isn’t the key’s workspace. |
409 | custom_code_conflict | The custom_code is taken. |
409 | workspace_conversion_tracking_disabled, conversion_tracking_locked, conversion_attribution_model_locked, conversion_attribution_window_locked | The workspace’s conversion settings don’t allow the values. |
List links
GET /api/v1/links lists links, newest first.
| Field | Type | Required | Notes |
|---|---|---|---|
limit | integer | no | 1 to 100. Default 50. |
offset | integer | no | How 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
| Field | Description |
|---|---|
public_id | The link’s ID in the API. |
original_url | The destination. |
short_code, domain | The short code and short domain; together they make the short URL. |
title, description | The title and description. |
clicks | Total clicks. |
status | active, scheduled, suspended, archived or security_locked. |
active | Whether the link redirects. false for a blocked or quarantined link, whatever its status. |
security_status | clear, blocked or quarantined. |
workspace_public_id, workspace_name | The link’s workspace. workspace_name is in lists only. |
tags | The link’s tags: public_id, name, color. |
starts_at, expires_at | The schedule, when set (get a link only). |
created_at, updated_at | RFC 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.
| Field | Type | Required | Notes |
|---|---|---|---|
title | string | no | Can’t be empty. |
description | string | no | |
url | string | no | A new destination. Counts as a destination edit. |
short_code | string | no | A new short code. See short codes. |
domain | string | no | A new short domain, such as go.example.com, available to the link’s workspace. |
status | string | no | active, suspended, archived or scheduled. |
active | boolean | no | true for active, false for suspended. |
team_public_ids | array of strings | no | Replace 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.
| Status | Code | Meaning |
|---|---|---|
400 | unsupported_fields | A field the endpoint doesn’t change. |
400 | invalid_status, title_required, invalid_url | An invalid value. |
400 | invalid_short_code_length, invalid_short_code_characters, reserved_short_code | The new short code breaks the rules. |
403 | plan_limit_exceeded | A plan limit. |
409 | short_code_conflict | The short code is taken. |
409 | link_security_locked | The 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.
| Field | Type | Required | Notes |
|---|---|---|---|
variant | string | yes | The 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.
| Status | Code | Meaning |
|---|---|---|
400 | variant_required | No variant. |
400 | unknown_variant | The letter isn’t part of the test. |
409 | ab_test_not_running | The link has no running A/B test. |
409 | ab_test_changed | The test changed meanwhile; read the link and try again. |
422 | winner_destination_flagged | The 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,apiorhealth, 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.