Microlink API

Microlink API automates browser actions via HTTP GET. Given a URL, it returns structured data (metadata, screenshots, PDFs, scraped content).

Endpoints

• •Free: https://api.microlink.io — unauthenticated, 50 reqs/day
• •Pro: https://pro.microlink.io — authenticated via x-api-key header, starts at 14,000 reqs/month

Query parameters support both camelCase and snake_case.

Authentication

Pass API key as x-api-key request header. Verify with x-pricing-plan: pro in response headers.

Never expose API keys in client-side code. Use proxy or edge-proxy for frontend usage.

Response Format (JSend)

{
  "status": "success",
  "data": { "title": "...", "description": "...", "image": { "url": "...", "width": 1280, "height": 720, "type": "jpg", "size": 120116, "size_pretty": "120 kB" }, "url": "..." },
  "message": "optional error message",
  "more": "optional docs link"
}

Status values: 'success' (2xx), 'fail' (4xx), 'error' (5xx).

Default Data Fields

Extracted automatically from any URL: title, description, author, publisher, date (ISO 8601), lang (ISO 639-1), url, image, video, logo.

Media fields include: width, height, type, size, size_pretty. Playable media adds duration, duration_pretty.

Additional HTTP info: statusCode, headers, redirects.

Core Parameters

Screenshot Options

PDF Options

Browser Control

Cache Control

Cache headers: x-cache-status (HIT/MISS/BYPASS), x-cache-ttl.

Pro-Only Parameters

headers, proxy, ttl, staleTtl, filename require a Pro plan.

• •headers: Custom HTTP headers. Use x-api-header-* prefix for sensitive headers
• •proxy: Custom proxy URL or automatic proxy resolution for anti-bot bypass
• •filename: Custom name for generated screenshot/PDF assets

Embed Pattern

Use embed to serve assets directly (no JSON wrapper):

<img src="https://api.microlink.io/?url=https://example.com&screenshot=true&meta=false&embed=screenshot.url">

Common embed fields: screenshot.url, pdf.url, image.url, logo.url, video.url.

function Parameter

Execute custom JS with Puppeteer access. Receives { page, html, response } plus any query params:

const { data } = await mql('https://example.com', {
  function: '({ page }) => page.evaluate("document.title")',
  meta: false
})
console.log(data.function)

Supports compression (lz#, gz#, br# prefixes) and NPM packages: cheerio, lodash, got, jsdom, @mozilla/readability, ioredis, @aws-sdk/client-s3, youtube-dl-exec, and others.

Error Codes

For complete details, see api-reference.md.

MQL (Microlink Query Language)

MQL is the official Node.js/browser HTTP client for Microlink API (@microlink/mql).

Installation

npm install @microlink/mql --save

Environments

• •Node.js: const mql = require('@microlink/mql')
• •Edge/WinterCG: import mql from '@microlink/mql/lightweight'
• •Browser: import mql from 'https://esm.sh/@microlink/mql'

Basic Usage

const mql = require('@microlink/mql')
const { status, data, response } = await mql('https://example.com')

API Signature

mql(url, [options], [httpOptions])

• •url: Target URL (required)
• •options: Any Microlink API parameter + apiKey, cache, retry
• •httpOptions: Passed to underlying HTTP client (got/ky)

Additional methods: mql.stream(), mql.buffer().

Error Handling

const { MicrolinkError } = mql
try {
  const { data } = await mql('https://example.com', { screenshot: true })
} catch (error) {
  // error.status, error.code, error.message, error.statusCode
}

Client-Side Caching (Node.js only)

const cache = new Map()
const { data } = await mql('https://example.com', { cache })
// data.response.fromCache → true on second call

Custom Data Extraction (Scraping)

Define rules with three primitives: selector (CSS), attr (what to extract), type (validation).

Single Field

const { data } = await mql('https://kikobeats.com', {
  data: {
    avatar: { selector: '#avatar', type: 'image', attr: 'src' }
  }
})

Multiple Fields

const { data } = await mql('https://news.ycombinator.com', {
  data: {
    headline: { selector: '.titleline > a', attr: 'text' },
    link: { selector: '.titleline > a', attr: 'href', type: 'url' }
  }
})

Collections (selectorAll)

const { data } = await mql('https://news.ycombinator.com', {
  data: {
    stories: { selectorAll: '.titleline > a', attr: 'text' }
  }
})

Fallback Rules

data: {
  title: [
    { selector: 'meta[property="og:title"]', attr: 'content' },
    { selector: 'title', attr: 'text' },
    { selector: 'h1', attr: 'text' }
  ]
}

Nested Rules

data: {
  stats: {
    selector: '.profile',
    attr: {
      followers: { selector: '.followers', type: 'number' },
      stars: { selector: '.stars', type: 'number' }
    }
  }
}

Whole-Page Serialization

data: {
  content: { attr: 'markdown' }  // omit selector for full page
}

attr Values

Standard HTML attributes plus: 'html', 'outerHTML', 'text', 'markdown', 'val'.

type Values

'auto', 'string', 'number', 'boolean', 'date', 'image', 'url', 'audio', 'video', 'email', 'author', 'publisher', 'title', 'description', 'lang', 'logo', 'object', 'regexp', 'ip'.

evaluate

Execute JS in browser context instead of CSS selectors:

data: {
  version: { evaluate: 'window.next.version', type: 'string' }
}

CLI

npm install @microlink/cli --global
microlink <url> [flags]

Flags: --api-key, --colors, --copy, --pretty.

Additional Resources

• •For full API parameter reference, see api-reference.md