Authentication
The Shortn API uses API keys with scopes. Create and manage keys from Profile → API keys.
Base URL and headers
Every endpoint lives under:
https://app.shortn.link/api/v1Send your key in the Authorization header:
curl https://app.shortn.link/api/v1/links \
-H "Authorization: Bearer $SHORTN_API_KEY"X-API-Key: <key> works too; if you send both, X-API-Key is used. Keys begin with
sk_live_. Keep them on your server — don’t embed them in frontend code.
Data access
A key is either account-wide or limited to one workspace, chosen when you create it:
- An account-wide key works in every workspace you belong to.
- A workspace key works only in its workspace. Asking for a link, tag, team or other
resource in another workspace returns
403 api_key_workspace_mismatch. Adding, verifying and removing custom domains needs an account-wide key (403 account_scoped_api_key_required).
A key also sees only what you can see: links limited to teams you aren’t in stay hidden, unless you’re a workspace owner or administrator.
Scopes
Each key is scoped to limit what it can do. The scopes and the endpoints they unlock:
| Scope | Endpoints |
|---|---|
links:read | List links (GET /links), get a link (GET /links/{public_id}). See links. |
links:write | Create (POST /links), update (PATCH), suspend (DELETE) and re-enable (POST .../enable) a link, end an A/B test with a winner (POST .../ab/winner). |
analytics:read | A link’s click totals (GET /analytics/links/{public_id}). See analytics. |
workspaces:read | List and get workspaces (/workspaces). See workspaces. |
reports:read, reports:write | Report and alert rules (/reports/rules). See reports and alerts. |
tags:read, tags:write | A workspace’s tags (/workspaces/{public_id}/tags, /tags/{id}). See tags. |
utm-templates:read, utm-templates:write | A workspace’s UTM templates (/workspaces/{public_id}/utm-templates, /utm-templates/{id}). See UTM templates. |
destinations:read, destinations:write | A workspace’s report destinations (/workspaces/{public_id}/destinations). See destinations. |
teams:read, teams:write | A workspace’s teams (/workspaces/{public_id}/teams, /teams/{slug}). See teams. |
domains:read, domains:write | Custom domains: list, add, verify, remove (/domains). domains:write needs an account-wide key. See domains. |
conversions:read | Conversion summaries, events, timeline and attribution (/conversions/...). See conversions. |
conversions:write | Send leads, sales and refunds, and validate them (POST /conversions/leads, .../sales, .../refunds, and their /validations). |
read scopes cover the GET endpoints, write scopes the ones that change data. A write
scope doesn’t include its read scope: a key that creates links and lists them needs both
links:write and links:read. Give each key the narrowest scopes it needs.
A few endpoints need no key at all; see public endpoints.
Authentication errors
| Status | Code | Meaning |
|---|---|---|
401 | api_key_required | No key was sent. |
401 | invalid_api_key | The key is wrong, revoked or expired, or you’re no longer an active member of its workspace. |
403 | api_key_scope_not_allowed | The key lacks a scope; details.required_scope names it. |
403 | api_key_workspace_mismatch | A workspace key asked for something in another workspace. |
403 | account_scoped_api_key_required | The endpoint needs an account-wide key. |
403 | api_access_unavailable | The plan has no API access. |
Rate limits
Each key has two per-minute limits, set by the plan of the account the key belongs to (for a workspace key, the workspace owner’s plan):
| Plan | General endpoints | Analytics endpoints |
|---|---|---|
| Free | 10 | 5 |
| Starter | 600 | 120 |
| Professional | 600 | 120 |
| Agency | 1,200 | 240 |
Analytics endpoints are the ones that need analytics:read or conversions:read; every
other endpoint counts toward the general limit. Responses show the limit they count toward:
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
X-RateLimit-Window: 60
X-RateLimit-Policy: defaultX-RateLimit-Policy is default or analytics. Over the limit, you get 429:
{
"code": "api_rate_limit_exceeded",
"error": "API rate limit exceeded for the current plan.",
"hint": "Retry after the current rate-limit window or upgrade the workspace plan.",
"details": {
"limit": 10,
"window": "1 minute",
"api_tier": "basic",
"upgrade_url": "/profile/billing",
"rate_bucket": "default",
"remaining": 0,
"reset_after_sec": 60
}
}Wait for the window to pass before retrying.
Errors
Errors use a consistent shape:
{
"code": "conversion_identity_required",
"error": "idempotency_key is required",
"hint": "Send a stable key for this lead, such as your signup or form submission ID, so a retry is recorded once.",
"details": {
"field": "idempotency_key"
}
}code is stable and safe to branch on; error is a readable message. hint and
details are present when the endpoint can add useful context, and details.field names
the request field at fault. Errors from the endpoints that send leads, sales and refunds
also carry a request_id, the same value as their Shortn-Request-Id response header, so
you can find the call in the event log. A few older endpoints return only error.
Plan limits
When a request needs a feature your plan doesn’t include, or would go past a plan limit, you
get 403, with the details at the top level:
{
"code": "plan_limit_exceeded",
"error": "Active links limit reached for this workspace owner's current plan.",
"hint": "Upgrade to a plan that includes this feature or raises this limit.",
"feature": "active_links",
"limit": 25,
"current": 25,
"required_plan": null,
"upgrade_url": "/profile/billing"
}featurenames what was refused. Limits:active_links,custom_domains,destination_edits,partners,report_alert_rules,team_members,utm_templates,workspaces. Features:ab_testing,conversion_tracking,custom_share_preview,custom_short_codes,device_targeting,geo_targeting,language_targeting,link_expiration,password_protected_links,public_dashboard_sharing,qr_customization,webhooks_integrations.limitandcurrentare the limit and your usage; both are0for a feature.required_planis the lowest plan that allows it (starter,professionaloragency), ornullwhen any higher plan raises the limit.upgrade_urlis the billing page in the app.
Limits follow the plan of the workspace’s owner, not of the person calling.
Status codes
| Status | Meaning |
|---|---|
200, 201 | Success. Creating a link returns 201. |
400 | The request is invalid; see code and details. |
401 | Missing or invalid API key. |
403 | Missing scope, wrong workspace, or a plan limit. |
404 | Not found, or not visible to this key. |
409 | Conflict, such as a short code that’s taken. |
429 | Rate limit. |
503 | Analytics are temporarily unavailable; retry shortly. |