Getting started with the Shortn API

Shortn manages short links, QR codes, campaigns, tags, bio pages and domains in a workspace. The API is being rolled out behind workspace feature flags. An API key does not enable access to a disabled feature.

Authentication

Create a key in Settings → API keys. Only workspace owners and admins can manage keys. Copy the secret when it is created; it is shown once. Give each integration the scopes it needs. The key's permissions are intersected with its creator's current workspace role. Revocation, membership removal and role changes apply to subsequent requests.

Send Authorization: Bearer sk_live_… over HTTPS to https://api.shortn.at. Session cookies do not authenticate REST requests. Never put secrets in URLs or client-side code.

curl https://api.shortn.at/v1/workspace \
  -H "Authorization: Bearer $SHORTN_API_KEY"

Create a link

Use a key with links:write. Keep the same Idempotency-Key when retrying a POST. Use a new key for a different operation. A reused key with a different payload is rejected.

curl https://api.shortn.at/v1/links \
  -H "Authorization: Bearer $SHORTN_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-integration-create-001' \
  --data '{"url":"https://example.com","title":"Example"}'

Pagination and filters

List endpoints return bounded pages. Use the returned nextCursor as the next request's cursor, preserving the other filters. A missing next cursor ends the list. The reference documents each endpoint's supported limit, search and filter parameters. For a large link library, use tag and campaign filters alongside keyword search; keep selections by stable link ID across pages. Do not download the whole library to populate a picker.

Expand related metadata

Link lists and all link lookup routes accept ?expand=tags,campaign. Each link keeps its compact tags and utm fields. Optional full records appear in expanded.tags and expanded.campaign. Both are arrays: a link can have multiple tags and campaigns, and repeated references are returned once.

Requesting tags requires tags:read; campaigns requires campaigns:read, in addition to links:read. A missing scope returns 403. Unknown expansion names return 400. Omit expand to keep the compact response and avoid the related reads. Expansion joins only the requested page (at most 200 links), with workspace isolation and legacy reference support. Deleted, merged without a surviving alias, or foreign-workspace references are omitted. Campaign link counts are computed without returning the campaign's full link ID list.

curl 'https://api.shortn.at/v1/links?limit=50&expand=tags,campaign' \
  -H "Authorization: Bearer $SHORTN_API_KEY"

Errors and retries

Errors use application/problem+json with a stable code. Dates are ISO strings and IDs are strings. Check HTTP status and code; do not parse human-readable error text. Rate limits apply per key and expose RateLimit-* headers. On a 429, respect Retry-After. Retry transient failures with backoff, preserving the idempotency key for POST requests. Feature, role and scope failures require configuration changes rather than repeated retries.

See the API reference, its markdown version, and the webhook guide.