Delivery and embedding

After a PDF is generated, you can either consume it as JSON or make the API URL return the PDF file directly. The right delivery mode depends on whether you are building an application workflow, a download link, or an embedded PDF preview.

Two delivery models

When you need	Use	Result
PDF metadata inside an app or backend workflow	Default JSON response	Read the asset from `data.pdf.url`
A direct PDF response for downloads or previews	`embed: 'pdf.url'`	The API URL itself returns the PDF file

JSON plus CDN URL

The default response gives you PDF metadata plus the CDN-hosted asset URL:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://rauchg.com/2014/7-principles-of-rich-web-applications' URL with 'pdf' & 'meta' API parameters:

CLI Microlink API example

microlink https://rauchg.com/2014/7-principles-of-rich-web-applications&pdf

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://rauchg.com/2014/7-principles-of-rich-web-applications" \
  -d "pdf=true" \
  -d "meta=false"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://rauchg.com/2014/7-principles-of-rich-web-applications', {
  pdf: true,
  meta: false
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://rauchg.com/2014/7-principles-of-rich-web-applications",
    "pdf": "true",
    "meta": "false"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://rauchg.com/2014/7-principles-of-rich-web-applications",
  pdf: "true",
  meta: "false"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://rauchg.com/2014/7-principles-of-rich-web-applications",
    "pdf" => "true",
    "meta" => "false"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://rauchg.com/2014/7-principles-of-rich-web-applications")
    q.Set("pdf", "true")
    q.Set("meta", "false")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://rauchg.com/2014/7-principles-of-rich-web-applications', {
  pdf: true,
  meta: false
})

Use data.pdf.url when your application already expects JSON and wants to keep the response metadata around.

This is the best fit for backend jobs, queues, notifications, and app code that stores the PDF URL after generation.

Direct PDF with embed

Set embed: 'pdf.url' to make the API URL return the PDF file itself:

CLI Microlink API example

microlink https://rauchg.com/2014/7-principles-of-rich-web-applications&pdf&embed=pdf.url

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://rauchg.com/2014/7-principles-of-rich-web-applications" \
  -d "pdf=true" \
  -d "meta=false" \
  -d "embed=pdf.url"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://rauchg.com/2014/7-principles-of-rich-web-applications', {
  pdf: true,
  meta: false,
  embed: "pdf.url"
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://rauchg.com/2014/7-principles-of-rich-web-applications",
    "pdf": "true",
    "meta": "false",
    "embed": "pdf.url"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://rauchg.com/2014/7-principles-of-rich-web-applications",
  pdf: "true",
  meta: "false",
  embed: "pdf.url"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://rauchg.com/2014/7-principles-of-rich-web-applications",
    "pdf" => "true",
    "meta" => "false",
    "embed" => "pdf.url"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://rauchg.com/2014/7-principles-of-rich-web-applications")
    q.Set("pdf", "true")
    q.Set("meta", "false")
    q.Set("embed", "pdf.url")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://rauchg.com/2014/7-principles-of-rich-web-applications', {
  pdf: true,
  meta: false,
  embed: "pdf.url"
})

The API URL becomes a direct PDF URL that can power download links, iframe previews, or embedded viewers.

See the embed reference for the full behavior and supported fields.

HTML download links

Use the API URL directly in an anchor element when you want a one-click download:

<a
  href="https://api.microlink.io?url=https://rauchg.com/2014/7-principles-of-rich-web-applications&pdf&meta=false&embed=pdf.url"
  download="article.pdf"
>
  Download PDF
</a>

This is the simplest way to add on-demand PDF downloads to a product, dashboard, or internal tool.

Embedded PDF previews

Use the same URL inside an <iframe> or <embed> element when you want an in-app preview:

<iframe
  src="https://api.microlink.io?url=https://rauchg.com/2014/7-principles-of-rich-web-applications&pdf&meta=false&embed=pdf.url"
  width="100%"
  height="800"
  title="PDF preview"
></iframe>

This works well for admin panels, invoice previews, or internal document review flows.

Markdown and CMS links

Markdown usually links to PDFs rather than rendering them inline:

[Download the PDF](https://api.microlink.io?url=https://rauchg.com/2014/7-principles-of-rich-web-applications&pdf&meta=false&embed=pdf.url)

Delivery with customization

All PDF parameters still work when you use embed. For example, a letter-sized PDF with margins:

CLI Microlink API example

microlink https://rauchg.com/2014/7-principles-of-rich-web-applications&pdf.format=Letter&pdf.margin=1cm&embed=pdf.url

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://rauchg.com/2014/7-principles-of-rich-web-applications" \
  -d "pdf.format=Letter" \
  -d "pdf.margin=1cm" \
  -d "meta=false" \
  -d "embed=pdf.url"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://rauchg.com/2014/7-principles-of-rich-web-applications', {
  pdf: {
    format: "Letter",
    margin: "1cm"
  },
  meta: false,
  embed: "pdf.url"
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://rauchg.com/2014/7-principles-of-rich-web-applications",
    "pdf.format": "Letter",
    "pdf.margin": "1cm",
    "meta": "false",
    "embed": "pdf.url"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://rauchg.com/2014/7-principles-of-rich-web-applications",
  pdf.format: "Letter",
  pdf.margin: "1cm",
  meta: "false",
  embed: "pdf.url"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://rauchg.com/2014/7-principles-of-rich-web-applications",
    "pdf.format" => "Letter",
    "pdf.margin" => "1cm",
    "meta" => "false",
    "embed" => "pdf.url"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://rauchg.com/2014/7-principles-of-rich-web-applications")
    q.Set("pdf.format", "Letter")
    q.Set("pdf.margin", "1cm")
    q.Set("meta", "false")
    q.Set("embed", "pdf.url")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://rauchg.com/2014/7-principles-of-rich-web-applications', {
  pdf: {
    format: "Letter",
    margin: "1cm"
  },
  meta: false,
  embed: "pdf.url"
})

Customize the final PDF and return it directly in a single URL.

Filtering JSON responses

If you still want JSON but only need the pdf field, use filter:

CLI Microlink API example

microlink https://rauchg.com/2014/7-principles-of-rich-web-applications&pdf&filter=pdf

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://rauchg.com/2014/7-principles-of-rich-web-applications" \
  -d "pdf=true" \
  -d "meta=false" \
  -d "filter=pdf"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://rauchg.com/2014/7-principles-of-rich-web-applications', {
  pdf: true,
  meta: false,
  filter: "pdf"
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://rauchg.com/2014/7-principles-of-rich-web-applications",
    "pdf": "true",
    "meta": "false",
    "filter": "pdf"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://rauchg.com/2014/7-principles-of-rich-web-applications",
  pdf: "true",
  meta: "false",
  filter: "pdf"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://rauchg.com/2014/7-principles-of-rich-web-applications",
    "pdf" => "true",
    "meta" => "false",
    "filter" => "pdf"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://rauchg.com/2014/7-principles-of-rich-web-applications")
    q.Set("pdf", "true")
    q.Set("meta", "false")
    q.Set("filter", "pdf")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://rauchg.com/2014/7-principles-of-rich-web-applications', {
  pdf: true,
  meta: false,
  filter: "pdf"
})

The response only includes the pdf field. This is useful for JSON workflows, but unnecessary when you already use embed.

See the filter reference for dot notation and multiple fields.

Custom filename
PRO

Use filename when the generated asset needs a readable, user-facing name:

CLI Microlink API example

microlink https://rauchg.com/2014/7-principles-of-rich-web-applications&pdf&filename=rich-web-applications

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://rauchg.com/2014/7-principles-of-rich-web-applications" \
  -d "pdf=true" \
  -d "meta=false" \
  -d "filename=rich-web-applications"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://rauchg.com/2014/7-principles-of-rich-web-applications', {
  pdf: true,
  meta: false,
  filename: "rich-web-applications"
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://rauchg.com/2014/7-principles-of-rich-web-applications",
    "pdf": "true",
    "meta": "false",
    "filename": "rich-web-applications"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://rauchg.com/2014/7-principles-of-rich-web-applications",
  pdf: "true",
  meta: "false",
  filename: "rich-web-applications"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://rauchg.com/2014/7-principles-of-rich-web-applications",
    "pdf" => "true",
    "meta" => "false",
    "filename" => "rich-web-applications"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://rauchg.com/2014/7-principles-of-rich-web-applications")
    q.Set("pdf", "true")
    q.Set("meta", "false")
    q.Set("filename", "rich-web-applications")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://rauchg.com/2014/7-principles-of-rich-web-applications', {
  pdf: true,
  meta: false,
  filename: "rich-web-applications"
})

Helpful for downloads, archives, generated reports, and user-visible document workflows.

Security considerations

If the request needs an API key, cookies, or authorization headers, do not expose those values in client-side download or preview URLs. Keep the request on the server side or protect it with a proxy:

Use
@microlink/proxy
for self-hosted protection.
Use
@microlink/edge-proxy
for edge-deployed protection.

Read more in the authentication docs and the private pages guide.

Next step

Learn how to optimize PDF requests for freshness, cache behavior, and response time in caching and performance.