Options

Every method accepts an options object as its last argument. Its keys are routed automatically so you never have to remember how the underlying API call is shaped:

Method-specific keys — such as fullPage for screenshot, format for pdf, or selector for markdown — are nested under the right product parameter. Each method page lists its own keys.
headers — sent as HTTP request headers, never serialized into the URL.
Everything else — passed through as top-level API query parameters. The useful ones are listed below.

const { url } = await microlink.screenshot('https://example.com', {
  fullPage: true,
  device: 'iPhone 11'
})

Here fullPage nests under screenshot while device stays a top-level query parameter.

Shared options

Any method can combine its own keys with these. They control the browser session, the page lifecycle, and the cache behind every call.

Browser

device <string> — emulates a device preset: viewport, user agent, and capabilities (default: 'macbook pro 13').
viewport <object> — sets the browser visible area and device capabilities directly.
colorScheme <string> — sets the CSS color scheme preference: 'light', 'dark', or 'no-preference' (default).
mediaType <string> — sets the CSS media type, e.g. 'print' (default: 'screen').
javascript <boolean> — enables or disables JavaScript execution in the page (default: true).
animations <boolean> — enables or disables CSS animations and transitions (default: false).
adblock <boolean> — blocks ads, trackers, and cookie consent services (default: true).

A retina-density mobile capture in dark mode:

const { url } = await microlink.screenshot('https://example.com', {
  colorScheme: 'dark',
  viewport: {
    width: 640,
    height: 400,
    deviceScaleFactor: 2,
    isMobile: true
  }
})

Page

prerender <boolean> | <string> — controls whether the content is fetched with a headless browser (default: 'auto').
waitForSelector <string> — waits until the element matching the CSS selector appears.
waitForTimeout <string> | <number> — waits a fixed amount of time before processing the content.
waitUntil <string> | <string[]> — the browser lifecycle events to wait for (default: 'auto').
click <string> | <string[]> — clicks the elements matching the CSS selectors.
scroll <string> — scrolls to the element matching the CSS selector.
scripts <string> | <string[]> — injects scripts into the page, as code or URLs.
styles <string> | <string[]> — injects styles into the page, as CSS rules or URLs.
modules <string> | <string[]> — injects ES modules into the page.

Dismiss a consent dialog, hide the promo banner, and wait for the chart to render before capturing:

const { url } = await microlink.screenshot('https://example.com/dashboard', {
  click: '.cookie-accept',
  styles: ['.promo-banner { display: none }'],
  waitForSelector: '.chart'
})

Cache

ttl <string> | <number> — how long the response stays cached (default: '24h').
staleTtl <string> | <number> | <boolean> — serves a stale copy while a fresh one regenerates in the background (default: false).
force <boolean> — bypasses the cache to get a fresh copy (default: false).
cacheKey <string> — extends the cache key with a custom identifier.

Cache for a week, serving stale copies instantly while a fresh one regenerates behind the scenes:

const metadata = await microlink.metadata('https://example.com', {
  ttl: '7d',
  staleTtl: '1d'
})

Request

timeout <string> | <number> — the maximum time allowed for the request lifecycle (default: '30s' free / '60s' pro).
retry <number> — how many retries to perform under an internal browser error (default: 2).
proxy <string> | <object> — resolves any sub-request through an HTTP proxy server.
filename <string> — the filename associated with a generated asset.
ping <boolean> | <object> — verifies every URL in the payload is publicly reachable (default: true).
palette <boolean> — adds dominant colors and accessible color pairs to every image field (default: false).

On pro, give a slow page the full 60s, retry harder, and name the resulting document:

const { url } = await microlink.pdf('https://example.com/report', {
  timeout: '60s',
  retry: 3,
  filename: 'report.pdf'
})

Headers

Use headers to authenticate against the target page. Any header prefixed with x-api-header- is forwarded to the target site with the prefix stripped:

const markdown = await microlink.markdown('https://x.com/some/article', {
  headers: {
    'x-api-header-cookie': 'auth_token=…'
  }
})

See headers for the full behavior.

Client-level defaults

Options passed to createClient apply to every call, and per-call options win over them:

const microlink = createClient({
  apiKey: process.env.MICROLINK_API_KEY,
  ttl: '1d'
})

await microlink.pdf('https://example.com', { ttl: '12h' })

Two options only make sense at the client level:

apiKey <string> — authenticates every request and switches the client to the pro endpoint.
endpoint <string> — overrides the API endpoint, for example to point at a self-hosted or enterprise deployment. When omitted, the client picks https://api.microlink.io or https://pro.microlink.io based on whether an apiKey is present.

const microlink = createClient({
  apiKey: process.env.MICROLINK_API_KEY,
  endpoint: 'https://microlink.internal.example.com'
})