{"openapi":"3.1.0","info":{"title":"Smart Link API","version":"1.0.0","summary":"Create smart short links that open the native app, and read their click analytics.","description":"REST API for Smart Link (smartlink.sh). Requires a Pro subscription. Authenticate with an API key from the dashboard: `Authorization: Bearer sl_live_...`. Limits: 60 requests per minute per key and 1000 new links per day per account. Clicks count requests to a short link with bots excluded; a click is not a confirmed app open.","contact":{"name":"Smart Link support","email":"support@smartlink.sh","url":"https://smartlink.sh/contact"},"termsOfService":"https://smartlink.sh/terms"},"externalDocs":{"description":"API documentation","url":"https://smartlink.sh/docs/api"},"servers":[{"url":"https://smartlink.sh/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Account","description":"The API key’s owner"},{"name":"Links","description":"Create and manage smart links"},{"name":"Analytics","description":"Click analytics"},{"name":"QR codes","description":"QR codes for short links"}],"paths":{"/me":{"get":{"tags":["Account"],"operationId":"getMe","summary":"Get the key’s account, subscription, and rate limits","responses":{"200":{"description":"Account details","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Me"}}}}}},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key’s account has no active Pro subscription (SUBSCRIPTION_REQUIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMITED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until you can retry"}}},"500":{"description":"Unexpected server error (INTERNAL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/links":{"get":{"tags":["Links"],"operationId":"listLinks","summary":"List links","description":"Newest first. Filter by search text, short code, platform, or active state.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"search","in":"query","description":"Case-insensitive match on destination, title, or short code","schema":{"type":"string"}},{"name":"shortCode","in":"query","description":"Exact short code","schema":{"type":"string"}},{"name":"platform","in":"query","schema":{"$ref":"#/components/schemas/Platform"}},{"name":"isActive","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"A page of links","content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Link"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Invalid query parameters (VALIDATION_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key’s account has no active Pro subscription (SUBSCRIPTION_REQUIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMITED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until you can retry"}}},"500":{"description":"Unexpected server error (INTERNAL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Links"],"operationId":"createLink","summary":"Create a link","description":"The platform (YouTube, Instagram, TikTok, ...) is detected from originalUrl. For an app in both stores, send the App Store URL as originalUrl and iosUrl, and the Google Play URL as androidUrl.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLinkRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Link"}}}}}},"400":{"description":"Invalid body (VALIDATION_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key’s account has no active Pro subscription (SUBSCRIPTION_REQUIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"customCode is already taken (CONFLICT)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMITED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until you can retry"}}},"500":{"description":"Unexpected server error (INTERNAL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/links/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Link id","schema":{"type":"string"}}],"get":{"tags":["Links"],"operationId":"getLink","summary":"Get a link","responses":{"200":{"description":"The link","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Link"}}}}}},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key’s account has no active Pro subscription (SUBSCRIPTION_REQUIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No link with this id in your account (NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMITED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until you can retry"}}},"500":{"description":"Unexpected server error (INTERNAL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Links"],"operationId":"updateLink","summary":"Update a link","description":"Send any subset of fields. The destination URL cannot be changed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLinkRequest"}}}},"responses":{"200":{"description":"Updated link","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Link"}}}}}},"400":{"description":"Invalid body (VALIDATION_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key’s account has no active Pro subscription (SUBSCRIPTION_REQUIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMITED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until you can retry"}}},"500":{"description":"Unexpected server error (INTERNAL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Links"],"operationId":"deleteLink","summary":"Delete a link","description":"Permanently deletes the link and its click history. To pause a link, PATCH isActive=false.","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","const":true}}}}}}}},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key’s account has no active Pro subscription (SUBSCRIPTION_REQUIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMITED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until you can retry"}}},"500":{"description":"Unexpected server error (INTERNAL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/links/{id}/analytics":{"get":{"tags":["Analytics"],"operationId":"getLinkAnalytics","summary":"Analytics for one link","parameters":[{"name":"id","in":"path","required":true,"description":"Link id","schema":{"type":"string"}},{"name":"days","in":"query","description":"Look back this many days (1-366). Default 30. Ignored when from/to are set.","schema":{"type":"integer","minimum":1,"maximum":366,"default":30}},{"name":"from","in":"query","description":"Range start (ISO 8601 date or date-time).","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Range end (ISO 8601). A date-only value includes the whole day. Default now.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Link analytics","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/LinkAnalytics"}}}}}},"400":{"description":"Invalid range; at most 366 days (VALIDATION_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key’s account has no active Pro subscription (SUBSCRIPTION_REQUIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMITED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until you can retry"}}},"500":{"description":"Unexpected server error (INTERNAL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analytics":{"get":{"tags":["Analytics"],"operationId":"getAccountAnalytics","summary":"Analytics across all links","parameters":[{"name":"days","in":"query","description":"Look back this many days (1-366). Default 30. Ignored when from/to are set.","schema":{"type":"integer","minimum":1,"maximum":366,"default":30}},{"name":"from","in":"query","description":"Range start (ISO 8601 date or date-time).","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Range end (ISO 8601). A date-only value includes the whole day. Default now.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Account analytics","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AccountAnalytics"}}}}}},"400":{"description":"Invalid range; at most 366 days (VALIDATION_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key’s account has no active Pro subscription (SUBSCRIPTION_REQUIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMITED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until you can retry"}}},"500":{"description":"Unexpected server error (INTERNAL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/links/{id}/qr":{"get":{"tags":["QR codes"],"operationId":"getLinkQrCode","summary":"QR code for a link","parameters":[{"name":"id","in":"path","required":true,"description":"Link id","schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["svg","png"],"default":"svg"}},{"name":"size","in":"query","schema":{"type":"integer","minimum":128,"maximum":2048,"default":512}}],"responses":{"200":{"description":"The QR code image","content":{"image/svg+xml":{"schema":{"type":"string"}},"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid format or size (VALIDATION_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key’s account has no active Pro subscription (SUBSCRIPTION_REQUIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMITED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until you can retry"}}},"500":{"description":"Unexpected server error (INTERNAL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"sl_live_<32 characters>","description":"Create a key in Dashboard → API."}},"schemas":{"Platform":{"type":"string","enum":["YOUTUBE","INSTAGRAM","TWITTER","FACEBOOK","LINKEDIN","REDDIT","TIKTOK","SPOTIFY","AMAZON","APPSTORE","PLAYSTORE","OTHER"]},"Link":{"type":"object","properties":{"id":{"type":"string"},"shortCode":{"type":"string"},"shortUrl":{"type":"string","format":"uri","examples":["https://smartlink.sh/l/abc123"]},"originalUrl":{"type":"string","format":"uri"},"platform":{"anyOf":[{"$ref":"#/components/schemas/Platform"},{"type":"null"}]},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"ogImage":{"type":["string","null"]},"iosUrl":{"type":["string","null"]},"androidUrl":{"type":["string","null"]},"isActive":{"type":"boolean"},"isPasswordProtected":{"type":"boolean"},"expiresAt":{"type":["string","null"],"format":"date-time"},"clickCount":{"type":"integer","description":"All recorded clicks, including bots"},"source":{"type":["string","null"],"enum":["DASHBOARD","API","MCP","PUBLIC","BIO",null]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreateLinkRequest":{"type":"object","required":["originalUrl"],"properties":{"originalUrl":{"type":"string","format":"uri","maxLength":2048},"iosUrl":{"type":"string","format":"uri","description":"App Store URL for iPhone visitors"},"androidUrl":{"type":"string","format":"uri","description":"Google Play URL for Android visitors"},"customCode":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[A-Za-z0-9_-]+$","description":"Custom short code; some words are reserved"},"title":{"type":"string","minLength":1,"maxLength":200},"password":{"type":"string","minLength":4,"maxLength":64,"writeOnly":true},"expiresAt":{"type":"string","format":"date-time","description":"Must be in the future"}}},"UpdateLinkRequest":{"type":"object","minProperties":1,"properties":{"title":{"type":"string","minLength":1,"maxLength":200},"isActive":{"type":"boolean"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"null removes the expiry"},"password":{"type":["string","null"],"minLength":4,"maxLength":64,"writeOnly":true,"description":"null removes password protection"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"pages":{"type":"integer"}}},"LinkAnalytics":{"type":"object","properties":{"url":{"type":"object","properties":{"id":{"type":"string"},"shortCode":{"type":"string"},"originalUrl":{"type":"string"},"title":{"type":"string"},"platform":{"type":"string"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"range":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"totalClicks":{"type":"integer","description":"All-time clicks (bots excluded)"},"clicksToday":{"type":"integer"},"clicksThisWeek":{"type":"integer"},"clicksThisMonth":{"type":"integer"},"clicksInPeriod":{"type":"integer","description":"Clicks inside the requested range; denominator for breakdowns"},"uniqueVisitors":{"type":"integer","description":"Distinct per-day visitors in the range"},"deviceBreakdown":{"type":"array","items":{"type":"object","properties":{"device":{"type":"string"},"clicks":{"type":"integer"},"percentage":{"type":"number","description":"Share of clicksInPeriod, 0-100"}}}},"browserBreakdown":{"type":"array","items":{"type":"object","properties":{"browser":{"type":"string"},"clicks":{"type":"integer"},"percentage":{"type":"number","description":"Share of clicksInPeriod, 0-100"}}}},"osBreakdown":{"type":"array","items":{"type":"object","properties":{"os":{"type":"string"},"clicks":{"type":"integer"},"percentage":{"type":"number","description":"Share of clicksInPeriod, 0-100"}}}},"countryBreakdown":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"clicks":{"type":"integer"},"percentage":{"type":"number","description":"Share of clicksInPeriod, 0-100"}}}},"referrerBreakdown":{"type":"array","items":{"type":"object","properties":{"referrer":{"type":"string"},"clicks":{"type":"integer"},"percentage":{"type":"number","description":"Share of clicksInPeriod, 0-100"}}}},"campaignBreakdown":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"clicks":{"type":"integer"},"percentage":{"type":"number","description":"Share of clicksInPeriod, 0-100"}}}},"clicksByDay":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"clicks":{"type":"integer"}}}},"recentClicks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"shortCode":{"type":"string"},"device":{"type":"string"},"browser":{"type":"string"},"os":{"type":"string"},"country":{"type":"string"},"userAgent":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"clicksByHour":{"type":"array","description":"Last 24 hours, per UTC hour","items":{"type":"object","properties":{"hour":{"type":"string","format":"date-time"},"clicks":{"type":"integer"}}}}}},"AccountAnalytics":{"type":"object","properties":{"totalUrls":{"type":"integer"},"activeUrls":{"type":"integer"},"range":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"totalClicks":{"type":"integer","description":"All-time clicks (bots excluded)"},"clicksToday":{"type":"integer"},"clicksThisWeek":{"type":"integer"},"clicksThisMonth":{"type":"integer"},"clicksInPeriod":{"type":"integer","description":"Clicks inside the requested range; denominator for breakdowns"},"uniqueVisitors":{"type":"integer","description":"Distinct per-day visitors in the range"},"deviceBreakdown":{"type":"array","items":{"type":"object","properties":{"device":{"type":"string"},"clicks":{"type":"integer"},"percentage":{"type":"number","description":"Share of clicksInPeriod, 0-100"}}}},"browserBreakdown":{"type":"array","items":{"type":"object","properties":{"browser":{"type":"string"},"clicks":{"type":"integer"},"percentage":{"type":"number","description":"Share of clicksInPeriod, 0-100"}}}},"osBreakdown":{"type":"array","items":{"type":"object","properties":{"os":{"type":"string"},"clicks":{"type":"integer"},"percentage":{"type":"number","description":"Share of clicksInPeriod, 0-100"}}}},"countryBreakdown":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"clicks":{"type":"integer"},"percentage":{"type":"number","description":"Share of clicksInPeriod, 0-100"}}}},"referrerBreakdown":{"type":"array","items":{"type":"object","properties":{"referrer":{"type":"string"},"clicks":{"type":"integer"},"percentage":{"type":"number","description":"Share of clicksInPeriod, 0-100"}}}},"campaignBreakdown":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"clicks":{"type":"integer"},"percentage":{"type":"number","description":"Share of clicksInPeriod, 0-100"}}}},"clicksByDay":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"clicks":{"type":"integer"}}}},"recentClicks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"shortCode":{"type":"string"},"device":{"type":"string"},"browser":{"type":"string"},"os":{"type":"string"},"country":{"type":"string"},"userAgent":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"topUrls":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"shortCode":{"type":"string"},"originalUrl":{"type":"string"},"title":{"type":"string"},"clicks":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}}}}},"Me":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]}}},"key":{"type":"object","properties":{"id":{"type":"string"},"prefix":{"type":"string"}}},"subscription":{"type":"object","properties":{"isActive":{"type":"boolean"},"currentPeriodEnd":{"type":["string","null"],"format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"}}},"rateLimits":{"type":"object"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["UNAUTHORIZED","SUBSCRIPTION_REQUIRED","VALIDATION_ERROR","NOT_FOUND","CONFLICT","RATE_LIMITED","INTERNAL"]},"message":{"type":"string"}}}}}}}}