# Options

## Table of Contents

- [Shared options](#shared-options)
  - [Browser](#browser)
  - [Page](#page)
  - [Cache](#cache)
  - [Request](#request)
- [Headers](#headers)
- [Client-level defaults](#client-level-defaults)

---

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](https://microlink.io/docs/sdk/methods/screenshot), `format` for [pdf](https://microlink.io/docs/sdk/methods/pdf), or `selector` for [markdown](https://microlink.io/docs/sdk/methods/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.

```js
const{url}=awaitmicrolink.screenshot('https://example.com',{

fullPage:true,

device:'iPhone 11'

})
```

Here `fullPage` nests under [screenshot](https://microlink.io/docs/api/parameters/screenshot) while `device` stays a top-level [query parameter](https://microlink.io/docs/api/parameters/device).

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

A retina-density mobile capture in dark mode:

```js
const{url}=awaitmicrolink.screenshot('https://example.com',{

colorScheme:'dark',

viewport:{

width:640,

height:400,

deviceScaleFactor:2,

isMobile:true

}

})
```

### Page

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

```js
const{url}=awaitmicrolink.screenshot('https://example.com/dashboard',{

click:'.cookie-accept',

styles:['.promo-banner { display: none }'],

waitForSelector:'.chart'

})
```

### Cache

- [ttl](https://microlink.io/docs/api/parameters/ttl) `<string> | <number>` — how long the response stays cached (default: `'24h'`).
- [staleTtl](https://microlink.io/docs/api/parameters/staleTtl) `<string> | <number> | <boolean>` — serves a stale copy while a fresh one regenerates in the background (default: `false`).
- [force](https://microlink.io/docs/api/parameters/force) `<boolean>` — bypasses the cache to get a fresh copy (default: `false`).
- [cacheKey](https://microlink.io/docs/api/parameters/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:

```js
constmetadata=awaitmicrolink.metadata('https://example.com',{

ttl:'7d',

staleTtl:'1d'

})
```

### Request

- [timeout](https://microlink.io/docs/api/parameters/timeout) `<string> | <number>` — the maximum time allowed for the request lifecycle (default: `'30s'` free / `'60s'` pro).
- [retry](https://microlink.io/docs/api/parameters/retry) `<number>` — how many retries to perform under an internal browser error (default: `2`).
- [proxy](https://microlink.io/docs/api/parameters/proxy) `<string> | <object>` — resolves any sub-request through an HTTP proxy server.
- [filename](https://microlink.io/docs/api/parameters/filename) `<string>` — the filename associated with a generated asset.
- [ping](https://microlink.io/docs/api/parameters/ping) `<boolean> | <object>` — verifies every URL in the payload is publicly reachable (default: `true`).
- [palette](https://microlink.io/docs/api/parameters/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:

```js
const{url}=awaitmicrolink.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:

```js
constmarkdown=awaitmicrolink.markdown('https://x.com/some/article',{

headers:{

'x-api-header-cookie':'auth_token=…'

}

})
```

See [headers](https://microlink.io/docs/api/parameters/headers) for the full behavior.

## Client-level defaults

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

```js
constmicrolink=createClient({

apiKey:process.env.MICROLINK_API_KEY,

ttl:'1d'

})

awaitmicrolink.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](https://microlink.io/docs/api/basics/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.

```js
constmicrolink=createClient({

apiKey:process.env.MICROLINK_API_KEY,

endpoint:'https://microlink.internal.example.com'

})
```