List links and their metrics (coming soon)

GET

/api/v3/links

const url = 'https://api.tryletterhead.com/api/v3/links?api=true&page=1&limit=50';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.tryletterhead.com/api/v3/links?api=true&page=1&limit=50' \
  --header 'Authorization: Bearer <token>'

Returns a paginated, deduplicated list of the links that appear across your letters, each with its enriched metadata (title, description, site name, author, image) and the categories our crawler assigned it. Every entry also lists the letters it appeared in.

Authorizations

bearerAuth

Parameters

Query Parameters

api

required

boolean

When set to true, this endpoint will accept authorization with your API Key.

page

integer

default: 1 >= 1

1-based page number. Minimum 1. Defaults to 1.

limit

integer

default: 50 >= 1 <= 100

Links per page. Minimum 1, maximum 100. Defaults to 50.

Responses

200

200 OK

application/json

object

items

object

links

Array<object>

object

urlMd5

A stable hash of the link’s URL, usable as a per-link key.

string

url

The link’s URL as it was stored.

string

pageTitle

The linked page’s title, as our crawler found it.

string

pageDescription

The linked page’s description, as our crawler found it.

string

pageKeywords

Keywords the linked page declares, as our crawler found them.

string

siteName

The linked page’s site name.

string

authorName

The linked page’s author, when the page declares one.

string

language

The linked page’s declared language.

string

pageImage

The linked page’s preview image URL, when one was found.

string

publishedTime

The linked page’s declared publish time.

string

canonicalUrl

The linked page’s canonical URL, when our crawler resolved one; otherwise empty.

string

enrichmentSource

Where this link’s metadata came from.

string

iabCategories

The IAB category names our crawler assigned to this link.

Array<string>

appearances

Every letter this link appeared in, each with its publication date.

Array<object>

object

letterUniqueId

The identifier of a letter this link appeared in.

string

publicationDate

The publication date of that letter.

string

page

The page number this response represents, echoing the page parameter.

integer

limit

The page size used, echoing the limit parameter.

integer

hasMore

Whether another page of links is available after this one.

boolean

message

string

total

integer

Example

{
  "items": {
    "links": [
      {
        "urlMd5": "9e107d9d372bb6826bd81d3542a419d6",
        "url": "https://example.com/an-article",
        "pageTitle": "An Article Worth Reading",
        "pageDescription": "A summary of the article.",
        "pageKeywords": "news, community",
        "siteName": "Example News",
        "authorName": "Jane Doe",
        "language": "en",
        "pageImage": "https://example.com/an-article/image.jpg",
        "publishedTime": "2026-06-18T14:22:03+00:00",
        "canonicalUrl": "https://example.com/an-article",
        "enrichmentSource": "crawler",
        "iabCategories": [
          "News and Politics"
        ],
        "appearances": [
          {
            "letterUniqueId": "35f725edbi",
            "publicationDate": "2026-06-18"
          }
        ]
      }
    ],
    "page": 1,
    "limit": 50,
    "hasMore": false
  },
  "message": "Links retrieved.",
  "total": 1
}

Still can’t find what you need? Contact support.