{"openapi":"3.0.3","info":{"title":"ShortLink Developer API","version":"1.0.0","description":"High-performance programmatic REST API for creating and managing short links, tracking analytics, configuring branded domains, and streaming real-time webhook events.","contact":{"name":"ShortLink Developer Support","url":"https://urlshortpilot.com/docs"}},"servers":[{"url":"https://urlshortpilot.com","description":"Production Server"},{"url":"http://localhost:3000","description":"Local Development Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key (sl_live_...)","description":"Supply your API key in the Authorization header as: `Bearer <your_api_key>`"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid URL provided."},"requestId":{"type":"string","example":"req_9f81a7b3c2"}}}}},"LinkDto":{"type":"object","properties":{"id":{"type":"string","example":"cmukhztbt0001ekjo7nsshkvc"},"shortCode":{"type":"string","example":"launch2026"},"customAlias":{"type":"string","nullable":true,"example":"launch2026"},"shortUrl":{"type":"string","example":"https://urlshortpilot.com/launch2026"},"destinationUrl":{"type":"string","example":"https://brand.com/campaign"},"title":{"type":"string","nullable":true,"example":"Spring Launch Campaign"},"status":{"type":"string","enum":["ACTIVE","ARCHIVED","DISABLED","EXPIRED"],"example":"ACTIVE"},"passwordProtected":{"type":"boolean","example":false},"expiresAt":{"type":"string","format":"date-time","nullable":true},"maxClicks":{"type":"integer","nullable":true,"example":5000},"createdAt":{"type":"string","format":"date-time"}}}}},"paths":{"/api/v1/links":{"get":{"summary":"List and search short links","description":"Returns paginated short links for the authenticated user or API key.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":25}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["ACTIVE","ARCHIVED","DISABLED"]}}],"responses":{"200":{"description":"List of links"},"401":{"description":"Unauthorized"}}},"post":{"summary":"Create a short link","description":"Generates a new shortened link with optional UTM parameters, password, and smart routing rules.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Unique client key to prevent accidental duplicate creations on network retries."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","example":"https://brand.com/article"},"title":{"type":"string","example":"Product Update"},"customAlias":{"type":"string","example":"product-v2"},"domainId":{"type":"string","nullable":true},"password":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"maxClicks":{"type":"integer","nullable":true},"utm":{"type":"object","properties":{"source":{"type":"string","example":"newsletter"},"medium":{"type":"string","example":"email"},"campaign":{"type":"string","example":"v2-launch"}}}}}}}},"responses":{"201":{"description":"Link created successfully"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/links/{id}":{"get":{"summary":"Retrieve a link","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Link details"},"404":{"description":"Link not found"}}},"patch":{"summary":"Update a link","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Link updated"},"404":{"description":"Link not found"}}},"delete":{"summary":"Delete or archive a link","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"archive","in":"query","schema":{"type":"boolean"},"description":"Set true to archive instead of delete"}],"responses":{"200":{"description":"Link deleted or archived"}}}},"/api/v1/links/{id}/analytics":{"get":{"summary":"Get link analytics","description":"Returns aggregated click metrics, geographic distribution, and device breakdowns.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"range","in":"query","schema":{"type":"string","enum":["today","7d","30d","90d"]}}],"responses":{"200":{"description":"Analytics data"}}}},"/api/v1/links/bulk":{"post":{"summary":"Batch link creation","description":"Create multiple short links programmatically in a single request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["links"],"properties":{"links":{"type":"array","items":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"title":{"type":"string"},"customAlias":{"type":"string"}}}}}}}}},"responses":{"201":{"description":"Bulk import results"}}}},"/api/v1/account/usage":{"get":{"summary":"Get account plan usage","description":"Returns current plan limits, links created, click quotas, and API request usage.","responses":{"200":{"description":"Usage report"}}}},"/api/v1/qr":{"get":{"summary":"Generate QR code","description":"Generates SVG, PNG, or DataURL QR code images.","parameters":[{"name":"url","in":"query","schema":{"type":"string"}},{"name":"code","in":"query","schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["dataurl","svg","png"]}},{"name":"size","in":"query","schema":{"type":"integer","default":300}}],"responses":{"200":{"description":"QR code image or payload"}}}},"/api/v1/webhooks":{"get":{"summary":"List webhook endpoints","responses":{"200":{"description":"List of endpoints"}}},"post":{"summary":"Create a webhook endpoint","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["link.created","link.updated","link.archived","link.deleted","link.expired","link.limit_reached","domain.verified","domain.failed","link.clicked"]}}}}}}},"responses":{"201":{"description":"Webhook created"}}}}}}