Mayy.my.id

Smart Link & QR Platform

Developer Platform & API Reference

Mayy REST API & Intelligence Routing Documentation

Integrate URL shortening, smart OS-based redirects, A/B split-testing, calendar date prefixes, and dynamic QR generation into your applications, webhooks, and marketing automation pipelines.

Base API URL

https://mayy.my.id/api

Authentication

MAYY_API_KEY / Bearer

Response Format

application/json

Redirect Latency

< 18ms Serverless Edge

Interactive Code Examples

Select use-case and programming language

curl -X POST https://mayy.my.id/api/create \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "url": "https://example.com/web-app",
    "aliasType": "exact_custom",
    "customSlug": "download-app",
    "tags": ["mobile", "app-launch"],
    "deviceTargets": {
      "ios": "https://apps.apple.com/app/id123456789",
      "android": "https://play.google.com/store/apps/details?id=com.example.app",
      "desktop": "https://example.com/download/desktop"
    }
  }'

REST API Endpoints Specification

Version 2.4
POST/api/create

Creates a new shortened URL with full support for OS-based smart routing, multi-variant A/B testing, password protection, expiration timestamps, organization tags, and custom vanity aliases.

JSON Request Body Parameters

FieldTypeRequiredDescription
urlstringYesPrimary master destination URL (e.g. https://example.com/landing).
aliasTypestringNo"random" | "date_prefix" | "custom_random" | "exact_custom" (Default: "random")
dateFormatstringNoDate format when using date_prefix mode: "DDMMYYYY", "YYYYMMDD", "DD-MM-YYYY", or "YYYY-MM-DD".
customPrefixstringNoBase prefix for custom_random mode (e.g. "promo" → promo-xK9p).
customSlugstringNoExact vanity slug for exact_custom mode (e.g. "summer-launch").
deviceTargetsobjectNoSmart OS targets: { "ios": string, "android": string, "desktop": string }.
abTestingobjectNoA/B split configuration: { "enabled": true, "variants": [{ "id": "v1", "url": "...", "weight": 50 }] }.
passwordstringNoSecret PIN or password required before completing destination redirect.
expiresAtstringNoISO 8601 timestamp (e.g. 2026-12-31T23:59:59Z) after which link returns HTTP 410.
tagsstring[]NoArray of organization tags (e.g. ["marketing", "newsletter"]).
mayyApiKeystringOptional*API Secret key if required by your instance. Can also be supplied via Authorization: Bearer <key>, x-mayy-api-key, or x-api-key header. (Aliases: apiKey, key, secret).

Sample HTTP 200 ResponseStatus 200 OK

{
  "success": true,
  "shortCode": "download-app",
  "shortUrl": "https://mayy.my.id/download-app",
  "longUrl": "https://example.com/web-app",
  "aliasType": "exact_custom",
  "tags": ["mobile", "app-launch"],
  "deviceTargets": {
    "ios": "https://apps.apple.com/app/id123456789",
    "android": "https://play.google.com/store/apps/details?id=com.example.app",
    "desktop": "https://example.com/download/desktop"
  },
  "createdAt": "2026-08-14T07:15:00.000Z"
}
GET/api/create?url=...

Query-parameter based URL generation for rapid CLI scripts, Raycast / Alfred workflows, and browser extensions without building JSON bodies.

curl "https://mayy.my.id/api/create?url=https://example.com&aliasType=date_prefix&dateFormat=DDMMYYYY"
AUTHAPI Key Authentication (MAYY_API_KEY)

When MAYY_API_KEY is configured on the instance, all API requests must provide the key using any of the following methods:

1. HTTP Headers (Recommended)

Authorization: Bearer <YOUR_KEY>
x-mayy-api-key: <YOUR_KEY>
x-api-key: <YOUR_KEY>

2. Query Parameters or Body

?mayy_api_key=<YOUR_KEY> (or ?api_key=...)
{ "mayyApiKey": "<YOUR_KEY>" } (in JSON body)

How Smart OS Routing Operates

When a visitor accesses a short link, the server analyzes the incoming HTTP User-Agent header. If matching iOS, Android, or Desktop signatures are detected and corresponding targets exist in deviceTargets, the visitor is immediately dispatched to their native store or web app.

• iOS → Apple App Store / TestFlight
• Android → Google Play / APK Deep Link
• Desktop → Web Landing / DMG / EXE Portal

A/B Traffic Split Algorithm

A/B testing evaluates variant weights cumulatively using a pseudo-random floating index. Telemetry counters record impression distributions in real-time, letting growth teams measure conversion rates between page variants without heavy client-side JavaScript snippet flicker.

• 50% → Variant A (Default CTA)
• 50% → Variant B (Video Testimonial CTA)
• Real-time variant click telemetry logged

Dynamic QR Studio & Vector SVG

Because QR codes encode the high-speed short URL rather than the complex destination, you can update the destination link anytime after print materials are in circulation. Codes can be downloaded in scalable Vector SVG (ideal for large billboard prints) or High-Res PNG.

UTM Tracking & Attribution

Attach standard Google Analytics tracking tags (utm_source, utm_medium, utm_campaign, utm_term, utm_content). Inbound traffic preserving UTM query parameters flows through seamlessly to your analytics dashboard.

HTTP Status Codes & Response Handling

Mayy uses standard HTTP response codes to communicate redirect and API statuses clearly:

Status CodeMeaningCondition & Behavior
200 OKSuccessShort link created or telemetry data retrieved successfully.
307 Temporary RedirectRedirectionVisitor successfully redirected to destination (or smart OS / A/B variant).
400 Bad RequestInvalid InputMissing destination URL, invalid URL format, or custom alias already exists.
401 UnauthorizedPIN ProtectedLink requires a passcode or user authentication is required.
403 ForbiddenRestricted DomainTarget domain is not included in the instance ALLOWED_DOMAINS whitelist.
404 Not FoundNonexistent LinkThe requested short code does not exist or has been deleted.
410 Gone / ExpiredExpired LinkThe link has passed its configured expiresAt timestamp and is inactive.

Ready to automate your links?

Test the API right now in your terminal or use our interactive web dashboard.

Go to App DashboardExplore Marketing Guides