{
  "openapi": "3.0.3",
  "info": {
    "title": "Urlik Temp-Mail, QR & Media Downloader API",
    "version": "1.1.0",
    "description": "Three tools in one key: (1) a social-media downloader that pulls video/audio/photo from TikTok, Instagram, YouTube, Facebook, X, VK, Reddit, Vimeo and 1000+ more sites; (2) disposable @urlik.xyz email inboxes for sign-up testing and OTP/verification flows; (3) a customizable QR-code generator returning a hosted image URL."
  },
  "servers": [
    { "url": "https://urlik.xyz", "description": "Production" }
  ],
  "security": [
    { "RapidApiProxy": [] }
  ],
  "components": {
    "securitySchemes": {
      "RapidApiProxy": {
        "type": "apiKey",
        "in": "header",
        "name": "X-RapidAPI-Proxy-Secret",
        "description": "Injected automatically by the RapidAPI gateway. Direct callers may instead send a registered X-Api-Key."
      }
    },
    "schemas": {
      "Mailbox": {
        "type": "object",
        "properties": {
          "address": { "type": "string", "example": "kxdukdhvr@urlik.xyz" },
          "local": { "type": "string", "example": "kxdukdhvr" },
          "domain": { "type": "string", "example": "urlik.xyz" },
          "ttl_seconds": { "type": "integer", "example": 86400 }
        }
      },
      "MessageMeta": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "6664ae96e092a287823cb642" },
          "from": { "type": "string", "example": "hello@outlook.com" },
          "from_raw": { "type": "string", "example": "Service <hello@outlook.com>" },
          "subject": { "type": "string", "example": "Your verification code" },
          "date": { "type": "string", "format": "date-time" },
          "timestamp": { "type": "integer", "example": 1782558172 }
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "address": { "type": "string" },
          "from": { "type": "string" },
          "from_raw": { "type": "string" },
          "to": { "type": "string" },
          "subject": { "type": "string" },
          "date": { "type": "string", "format": "date-time" },
          "timestamp": { "type": "integer" },
          "text": { "type": "string" },
          "html": { "type": "string" }
        }
      },
      "Qr": {
        "type": "object",
        "properties": {
          "url": { "type": "string", "example": "https://urlik.xyz/cache/qr/aa21b753369afff5b41ec02440fb99cb.png" },
          "format": { "type": "string", "example": "png" },
          "data": { "type": "string", "example": "https://urlik.xyz" },
          "image_base64": { "type": "string", "description": "Present only when base64=1" }
        }
      },
      "MediaFormat": {
        "type": "object",
        "properties": {
          "quality": { "type": "string", "example": "1080p" },
          "type": { "type": "string", "enum": ["video", "best", "audio", "image"] },
          "ext": { "type": "string", "example": "mp4" },
          "height": { "type": "integer", "example": 1080 },
          "filesize": { "type": "integer", "description": "Bytes; 0 if unknown" },
          "download_url": { "type": "string", "description": "Signed, time-limited URL — GET it to stream the file" }
        }
      },
      "Media": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "uploader": { "type": "string" },
          "source": { "type": "string", "example": "TikTok" },
          "duration": { "type": "integer", "description": "Seconds (0 for images)" },
          "thumbnail": { "type": "string" },
          "expires_at": { "type": "integer", "description": "Unix time the download_url links stop working" },
          "formats": { "type": "array", "items": { "$ref": "#/components/schemas/MediaFormat" } }
        }
      }
    }
  },
  "paths": {
    "/api/download.json": {
      "get": {
        "summary": "Download media from 1000+ sites",
        "description": "Pass a public media URL and get the title, thumbnail and a list of formats — each with a signed, time-limited download_url you can GET to stream the file (MP4 video, MP3 audio, or the original image). Works with TikTok, Instagram, YouTube, Facebook, X, VK, Reddit, Vimeo, Pinterest and 1000+ more.",
        "operationId": "downloadMedia",
        "parameters": [
          { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Public URL of the video/photo to download." }
        ],
        "responses": {
          "200": { "description": "Media info + download links", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "return": { "$ref": "#/components/schemas/Media" } } } } } },
          "422": { "description": "No downloadable media found, or the post requires a login" },
          "502": { "description": "Source platform is temporarily blocking automated access" }
        }
      }
    },
    "/api/mailbox.json": {
      "get": {
        "summary": "Create / get a disposable address",
        "description": "Returns a fresh random @urlik.xyz inbox address. Pass `address` to request a specific name (3-30 chars: letters, digits, dots, dashes; role names like admin/support/no-reply are reserved).",
        "operationId": "getMailbox",
        "parameters": [
          { "name": "address", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional desired local-part or full address." }
        ],
        "responses": {
          "200": { "description": "Address issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "return": { "$ref": "#/components/schemas/Mailbox" } } } } } }
        }
      }
    },
    "/api/messages.json": {
      "get": {
        "summary": "List inbox",
        "description": "Lists messages received for a disposable address, newest first. Messages auto-expire after 24h.",
        "operationId": "listMessages",
        "parameters": [
          { "name": "address", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The inbox address (name or full @urlik.xyz)." }
        ],
        "responses": {
          "200": { "description": "Inbox list", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "return": { "type": "object", "properties": { "address": { "type": "string" }, "count": { "type": "integer" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/MessageMeta" } } } } } } } } }
        }
      }
    },
    "/api/message.json": {
      "get": {
        "summary": "Read a message",
        "description": "Returns one parsed message (plain text and HTML parts). The recipient is re-verified, so an address can only read its own mail.",
        "operationId": "getMessage",
        "parameters": [
          { "name": "address", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Message id from /api/messages.json" }
        ],
        "responses": {
          "200": { "description": "Parsed message", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "return": { "$ref": "#/components/schemas/Message" } } } } } },
          "404": { "description": "Message not found" }
        }
      }
    },
    "/api/qr.json": {
      "get": {
        "summary": "Generate a QR code",
        "description": "Encodes any link or text into a QR code and returns a hosted image URL (cached). Customize colors, size, error-correction and format.",
        "operationId": "generateQr",
        "parameters": [
          { "name": "data", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Link or text to encode (max 1200 chars)." },
          { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": ["png", "svg"], "default": "png" } },
          { "name": "fg", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Foreground hex, e.g. e94b0e" },
          { "name": "bg", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Background hex, e.g. ffffff" },
          { "name": "ecc", "in": "query", "required": false, "schema": { "type": "string", "enum": ["L", "M", "Q", "H"], "default": "M" } },
          { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 4, "maximum": 20, "default": 8 }, "description": "Module scale (pixels per module)." },
          { "name": "base64", "in": "query", "required": false, "schema": { "type": "string", "enum": ["0", "1"], "default": "0" }, "description": "Set 1 to also return an inline data URI." }
        ],
        "responses": {
          "200": { "description": "QR generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "return": { "$ref": "#/components/schemas/Qr" } } } } } }
        }
      }
    }
  }
}