Delivery and response shaping

Once metadata has been extracted, the next decision is how much of the response you want to keep and how directly you want to consume it.

Three response models

When you need	Use	Result
Full metadata plus any enriched fields	Default response	The full JSON payload under `data`
A smaller JSON payload with only a few fields	`filter`	Still JSON, but trimmed to the selected fields
One field as the response body	`embed`	The API URL returns that field directly

Keep the full JSON response

The default response is best when your application already expects structured data:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://github.com/microlinkhq' URL:

CLI Microlink API example

microlink https://github.com/microlinkhq

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://github.com/microlinkhq"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq')

Python Microlink API example

import requests

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

querystring = {
    "url": "https://github.com/microlinkhq"
}

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://github.com/microlinkhq"
}

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://github.com/microlinkhq"
];

$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://github.com/microlinkhq")
    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://github.com/microlinkhq')

Use the default JSON response when your app wants the full normalized payload and any optional enriched fields.

This is the best fit for backends, queues, automation jobs, and UI code that wants more than one field.

Trim the payload with filter

If you only need a few metadata fields, add filter:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://github.com/microlinkhq' URL with 'filter' API parameter:

CLI Microlink API example

microlink https://github.com/microlinkhq&filter=title,description,url

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://github.com/microlinkhq" \
  -d "filter=title,description,url"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  filter: "title,description,url"
})

Python Microlink API example

import requests

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

querystring = {
    "url": "https://github.com/microlinkhq",
    "filter": "title,description,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://github.com/microlinkhq",
  filter: "title,description,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://github.com/microlinkhq",
    "filter" => "title,description,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://github.com/microlinkhq")
    q.Set("filter", "title,description,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://github.com/microlinkhq', {
  filter: "title,description,url"
})

The response stays JSON, but only the selected fields are returned.

This is useful when you want minimal bandwidth without changing the response format. See the filter reference for dot notation and multi-field filters.

Return one field directly with embed

Use embed when you want the API URL itself to behave like a direct field endpoint:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://github.com/microlinkhq' URL with 'embed' API parameter:

CLI Microlink API example

microlink https://github.com/microlinkhq&embed=title

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://github.com/microlinkhq" \
  -d "embed=title"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  embed: "title"
})

Python Microlink API example

import requests

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

querystring = {
    "url": "https://github.com/microlinkhq",
    "embed": "title"
}

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://github.com/microlinkhq",
  embed: "title"
}

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://github.com/microlinkhq",
    "embed" => "title"
];

$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://github.com/microlinkhq")
    q.Set("embed", "title")
    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://github.com/microlinkhq', {
  embed: "title"
})

The API URL now returns the title field directly instead of the full JSON payload.

This is especially useful for:

text fields such as title or description
direct asset fields such as image.url or logo.url

For example, a direct preview image URL looks like:

<img
  src="https://api.microlink.io?url=https://github.com/microlinkhq&embed=image.url"
  alt="Preview image"
/>

Choose filter vs embed

If you need	Use
More than one field	`filter`
Exactly one field as a direct response	`embed`
The full payload and future flexibility	Default response

If the request needs an API key, cookies, or authorization headers, do not expose those values in public URLs or client-side code, especially when you use embed to create shareable direct-response URLs.

Keep authenticated metadata requests on your backend whenever possible.
Use
@microlink/proxy
for self-hosted protection.
Use
@microlink/edge-proxy
for edge-deployed protection.

See the authentication docs and private pages for the full setup.

Next step

Learn how to handle dynamic pages, SPAs, and timing-sensitive targets in page preparation.

Delivery and response shaping

Three response models

Keep the full JSON response

CLI Microlink API example

cURL Microlink API example

JavaScript Microlink API example

Python Microlink API example

Ruby Microlink API example

PHP Microlink API example

Golang Microlink API example

Trim the payload with filter

CLI Microlink API example

cURL Microlink API example

JavaScript Microlink API example

Python Microlink API example

Ruby Microlink API example

PHP Microlink API example

Golang Microlink API example

Return one field directly with embed

CLI Microlink API example

cURL Microlink API example

JavaScript Microlink API example

Python Microlink API example

Ruby Microlink API example

PHP Microlink API example

Golang Microlink API example

Choose filter vs embed

Security considerations

Next step