{"openapi":"3.1.0","info":{"title":"Mayy Link Platform API","description":"High-performance, resilient API for creating shortened URLs, date-prefixed links, custom aliases, batch operations, QR code generation, UTM campaign tracking, Prometheus metrics, and real-time telemetry on mayy.my.id.","version":"3.5.0"},"servers":[{"url":"https://mayy.my.id","description":"Production API Gateway"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-mayy-api-key","description":"Pass MAYY_API_KEY via x-mayy-api-key, Authorization: Bearer <KEY>, or ?mayy_api_key=<KEY>"}}},"paths":{"/api/create":{"post":{"summary":"Create a shortened URL (Universal compatibility)","operationId":"createShortUrl","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Destination long URL (e.g. https://olshop.my.id/item/123)"},"title":{"type":"string","description":"Optional link title"},"aliasType":{"type":"string","enum":["random","date_prefix","custom_random","exact_custom"],"description":"Slug generation strategy"},"dateFormat":{"type":"string","enum":["DDMMYYYY","YYYYMMDD","DD-MM-YYYY","YYYY-MM-DD"],"description":"Format when aliasType is date_prefix"},"customPrefix":{"type":"string","description":"Prefix when aliasType is custom_random"},"customSlug":{"type":"string","description":"Exact slug when aliasType is exact_custom"},"overwrite":{"type":"boolean","description":"Whether to overwrite if custom slug exists"},"tags":{"type":"array","items":{"type":"string"}},"utm_source":{"type":"string","description":"UTM campaign source"},"utm_medium":{"type":"string","description":"UTM campaign medium"},"utm_campaign":{"type":"string","description":"UTM campaign name"},"iosUrl":{"type":"string","description":"iOS device destination redirect"},"androidUrl":{"type":"string","description":"Android device destination redirect"}},"required":["url"]}}}},"responses":{"200":{"description":"Created successfully (Plaintext fallback)","content":{"text/plain":{"schema":{"type":"string"}}}},"201":{"description":"Created successfully (JSON)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"shortUrl":{"type":"string"},"shortCode":{"type":"string"},"qrCodeUrl":{"type":"string"},"analyticsUrl":{"type":"string"},"longUrl":{"type":"string"},"aliasType":{"type":"string"},"executionTimeMs":{"type":"number"}}}}}}}},"get":{"summary":"Create short URL via GET query parameter","operationId":"createShortUrlGet","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"}},{"name":"aliasType","in":"query","required":false,"schema":{"type":"string"}},{"name":"customPrefix","in":"query","required":false,"schema":{"type":"string"}},{"name":"customSlug","in":"query","required":false,"schema":{"type":"string"}},{"name":"dateFormat","in":"query","required":false,"schema":{"type":"string"}},{"name":"utm_source","in":"query","required":false,"schema":{"type":"string"}},{"name":"utm_campaign","in":"query","required":false,"schema":{"type":"string"}},{"name":"mayy_api_key","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Short link URL returned"}}}},"/api/v1/links":{"get":{"summary":"List and filter shortened links with pagination","operationId":"listLinks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["active","paused","expired"]}}],"responses":{"200":{"description":"Paginated list of short links"}}},"post":{"summary":"Create rich shortlink with advanced targeting and webhooks","operationId":"createV1Link","security":[{"ApiKeyAuth":[]}],"responses":{"201":{"description":"Link created successfully"}}}},"/api/v1/links/batch":{"post":{"summary":"Batch create up to 50 shortened links in parallel","operationId":"createBatchLinks","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Batch process results summary"}}}},"/api/v1/links/{code}":{"get":{"summary":"Retrieve single shortlink details and analytics","operationId":"getLinkDetails","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Shortlink configuration and analytics"}}},"patch":{"summary":"Update shortlink destination, tags, or status","operationId":"updateLink","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Link updated successfully"}}},"delete":{"summary":"Delete a shortlink permanently","operationId":"deleteLink","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Link deleted successfully"}}}},"/api/v1/links/{code}/qr":{"get":{"summary":"Generate high-res QR code for shortlink","operationId":"getLinkQr","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["svg","png"],"default":"svg"}},{"name":"size","in":"query","schema":{"type":"integer","default":320}},{"name":"dark","in":"query","schema":{"type":"string","default":"#000000"}},{"name":"light","in":"query","schema":{"type":"string","default":"#ffffff"}},{"name":"download","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"QR Code image in SVG or PNG format"}}}},"/api/qr":{"get":{"summary":"Universal dynamic QR code generator for any URL or payload","operationId":"generateUniversalQr","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["svg","png"],"default":"svg"}},{"name":"size","in":"query","schema":{"type":"integer","default":300}}],"responses":{"200":{"description":"QR Code stream"}}}},"/api/v1/analytics/timeseries":{"get":{"summary":"Query click timeseries, geo breakdown, and device distribution","operationId":"getTimeseriesAnalytics","parameters":[{"name":"code","in":"query","required":false,"schema":{"type":"string"}},{"name":"range","in":"query","schema":{"type":"string","enum":["24h","7d","30d","90d"],"default":"7d"}}],"responses":{"200":{"description":"Aggregated analytics and timeseries data"}}}},"/api/v1/slugs/check":{"get":{"summary":"Pre-flight slug availability & collision verification","operationId":"checkSlugAvailability","parameters":[{"name":"slug","in":"query","required":true,"schema":{"type":"string"},"description":"Desired slug to check (e.g. flash-sale-2026)"}],"responses":{"200":{"description":"Availability status, collision diagnosis, and alternative slug suggestions"}}}},"/api/v1/links/expand":{"post":{"summary":"Bulk resolve & expand shortlinks to destination metadata (Up to 100 items)","operationId":"expandLinksBulk","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slugs":{"type":"array","items":{"type":"string"},"description":"Array of slugs or short URLs to resolve"}}}}}},"responses":{"200":{"description":"Resolved destination URLs, expiration flags, clicks, and device routing rules"}}}},"/api/v1/webhooks/test":{"post":{"summary":"Simulate & test webhook dispatch with HMAC SHA-256 signatures","operationId":"testWebhookDispatch","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Target webhook listener URL"},"secret":{"type":"string","description":"HMAC secret key"},"event":{"type":"string","enum":["link.created","link.clicked","link.expired","link.threshold_breach"],"default":"link.clicked"}}}}}},"responses":{"200":{"description":"Round-trip response status, latency, request headers, and HMAC verification code"}}}},"/api/v1/keys/verify":{"get":{"summary":"Inspect API Key permissions, token bucket rate limits, and scopes","operationId":"verifyApiKey","responses":{"200":{"description":"API Key active status, rate limit tier, and capability scopes"}}}},"/api/metrics":{"get":{"summary":"Prometheus metrics or JSON health telemetry exporter","operationId":"getPrometheusMetrics","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["prometheus","json"],"default":"prometheus"}}],"responses":{"200":{"description":"Prometheus plaintext or JSON telemetry metrics"}}}}}}