{"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","contact":{"name":"Mayy Platform Engineering","url":"https://mayy.my.id/docs"}},"servers":[{"url":"https://mayy.my.id","description":"Current Production Gateway"},{"url":"https://mayy.my.id","description":"Global Production Server"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-mayy-api-key","description":"Pass MAYY_API_KEY via header x-mayy-api-key, Authorization: Bearer <KEY>, or query parameter ?mayy_api_key=<KEY>"}},"schemas":{"CreateLinkPayload":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Destination long URL (e.g. https://olshop.my.id/item/123)"},"title":{"type":"string","description":"Optional link title or description"},"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"},"description":"Array of tag identifiers"},"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"}}},"CreateLinkResponse":{"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"}}},"BulkExpandPayload":{"type":"object","required":["slugs"],"properties":{"slugs":{"type":"array","items":{"type":"string"},"description":"Array of slugs or short URLs to resolve (up to 100 items)"}}},"WebhookTestPayload":{"type":"object","required":["url","secret"],"properties":{"url":{"type":"string","description":"Target webhook listener URL"},"secret":{"type":"string","description":"HMAC secret key for signing"},"event":{"type":"string","enum":["link.created","link.clicked","link.expired","link.threshold_breach"],"default":"link.clicked"}}}}},"paths":{"/api/create":{"post":{"summary":"Create a shortened URL (Universal compatibility)","operationId":"createShortUrl","description":"Fast link creation supporting custom slugs, date prefixes, device routing (iOS/Android), and UTM parameters. Accepts JSON or URL-encoded payloads.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLinkPayload"}}}},"responses":{"200":{"description":"Created successfully (Plaintext fallback URL)","content":{"text/plain":{"schema":{"type":"string"}}}},"201":{"description":"Created successfully (JSON payload)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLinkResponse"}}}}}},"get":{"summary":"Create short URL via GET query parameter","operationId":"createShortUrlGet","description":"Create short links via standard HTTP GET query parameters. Perfect for microservices, olshop integrations, or webhook triggers.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"},"description":"Target long destination URL"},{"name":"aliasType","in":"query","required":false,"schema":{"type":"string","enum":["random","date_prefix","custom_random","exact_custom"]},"description":"Slug generation mode"},{"name":"customPrefix","in":"query","required":false,"schema":{"type":"string"},"description":"Prefix for custom_random"},{"name":"customSlug","in":"query","required":false,"schema":{"type":"string"},"description":"Exact slug for exact_custom"},{"name":"dateFormat","in":"query","required":false,"schema":{"type":"string","enum":["DDMMYYYY","YYYYMMDD","DD-MM-YYYY","YYYY-MM-DD"]},"description":"Date format for date_prefix"},{"name":"utm_source","in":"query","required":false,"schema":{"type":"string"},"description":"UTM source"},{"name":"utm_campaign","in":"query","required":false,"schema":{"type":"string"},"description":"UTM campaign"},{"name":"mayy_api_key","in":"query","required":false,"schema":{"type":"string"},"description":"API Key (optional if public limits apply)"}],"responses":{"200":{"description":"Short link URL returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLinkResponse"}},"text/plain":{"schema":{"type":"string"}}}}}}},"/api/v1/links":{"get":{"summary":"List and filter shortened links with pagination","operationId":"listLinks","description":"Query links with real-time filtering, pagination, tag search, and status filtering.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50},"description":"Number of links to return"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Search keywords in title, slug, or destination"},{"name":"tag","in":"query","schema":{"type":"string"},"description":"Filter by specific tag"},{"name":"status","in":"query","schema":{"type":"string","enum":["active","paused","expired"]},"description":"Filter by link lifecycle state"}],"responses":{"200":{"description":"Paginated list of short links","content":{"application/json":{"schema":{"type":"object","properties":{"links":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"}}}}}}}},"post":{"summary":"Create rich shortlink with advanced targeting and webhooks","operationId":"createV1Link","description":"Enterprise link provisioning with multi-device fallback routing and webhooks.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLinkPayload"}}}},"responses":{"201":{"description":"Link created successfully"}}}},"/api/v1/links/batch":{"post":{"summary":"Batch create up to 50 shortened links in parallel","operationId":"createBatchLinks","description":"Bulk create up to 50 links in a single optimized transactional operation with individual slug collision handling.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateLinkPayload"},"description":"Array of link items to create (up to 50)"}}}}}},"responses":{"200":{"description":"Batch process results summary"}}}},"/api/v1/links/{code}":{"get":{"summary":"Retrieve single shortlink details and analytics","operationId":"getLinkDetails","description":"Fetch complete metadata, clicks, device targets, and analytics for a specific slug.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"Shortlink slug or code (URL-encoded if contains prefix)"}],"responses":{"200":{"description":"Shortlink configuration and analytics"}}},"patch":{"summary":"Update shortlink destination, tags, or status","operationId":"updateLink","description":"Modify target URL, tags, expiration, or active status of an existing link.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"Shortlink slug or code"}],"responses":{"200":{"description":"Link updated successfully"}}},"delete":{"summary":"Delete a shortlink permanently","operationId":"deleteLink","description":"Permanently remove a shortened link document and clear routing cache.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"Shortlink slug or code"}],"responses":{"200":{"description":"Link deleted successfully"}}}},"/api/v1/links/{code}/qr":{"get":{"summary":"Generate high-res QR code for shortlink","operationId":"getLinkQr","description":"Render server-side vector SVG or high-DPI PNG QR codes with custom styling and colors.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"Shortcode identifier"},{"name":"format","in":"query","schema":{"type":"string","enum":["svg","png"],"default":"svg"},"description":"Image output format"},{"name":"size","in":"query","schema":{"type":"integer","default":320},"description":"Image resolution in pixels"},{"name":"dark","in":"query","schema":{"type":"string","default":"#000000"},"description":"Dark module color hex code"},{"name":"light","in":"query","schema":{"type":"string","default":"#ffffff"},"description":"Light background color hex code"},{"name":"download","in":"query","schema":{"type":"boolean","default":false},"description":"Set Content-Disposition attachment header"}],"responses":{"200":{"description":"QR Code image stream (SVG or PNG)","content":{"image/svg+xml":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/qr":{"get":{"summary":"Universal dynamic QR code generator for any URL or payload","operationId":"generateUniversalQr","description":"Generate instant vector QR codes for any arbitrary URL or string without saving to Firestore.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"},"description":"Payload string or URL to encode"},{"name":"format","in":"query","schema":{"type":"string","enum":["svg","png"],"default":"svg"},"description":"Image format"},{"name":"size","in":"query","schema":{"type":"integer","default":300},"description":"Pixel size"}],"responses":{"200":{"description":"QR Code binary stream","content":{"image/svg+xml":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v1/slugs/check":{"get":{"summary":"Pre-flight slug availability & collision verification","operationId":"checkSlugAvailability","description":"Pre-flight collision and availability verification with smart slug suggestions if taken.","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","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"available":{"type":"boolean"},"reason":{"type":"string"},"suggestions":{"type":"array","items":{"type":"string"}}}}}}}}}},"/api/v1/links/expand":{"post":{"summary":"Bulk resolve & expand shortlinks to destination metadata (Up to 100 items)","operationId":"expandLinksBulk","description":"High-throughput parallel resolver for up to 100 shortcodes with status flags and destination inspection.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkExpandPayload"}}}},"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","description":"Simulate webhook delivery to any endpoint and verify HMAC-SHA256 signature calculation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestPayload"}}}},"responses":{"200":{"description":"Round-trip response status, latency, request headers, and HMAC verification code"}}}},"/api/v1/analytics/timeseries":{"get":{"summary":"Query click timeseries, geo breakdown, and device distribution","operationId":"getTimeseriesAnalytics","description":"Granular click telemetry with hourly velocity, device breakdowns, referrers, and geo statistics.","parameters":[{"name":"code","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by specific link code (optional)"},{"name":"range","in":"query","schema":{"type":"string","enum":["24h","7d","30d","90d"],"default":"7d"},"description":"Timeseries window"}],"responses":{"200":{"description":"Aggregated analytics and timeseries data"}}}},"/api/v1/keys/verify":{"get":{"summary":"Inspect API Key permissions, token bucket rate limits, and scopes","operationId":"verifyApiKey","description":"Inspect MAYY_API_KEY authorization status, rate limit quota, and permitted capability scopes.","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","description":"Export OpenTelemetry / Prometheus plaintext metrics or JSON telemetry for Grafana / Datadog.","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["prometheus","json"],"default":"prometheus"},"description":"Output format"}],"responses":{"200":{"description":"Prometheus plaintext or JSON telemetry metrics"}}}}}}