Tutorial

Screenshot API for Notion + Productivity Tools

Fill a Notion database's Files property with screenshots of each row's URL, using the Screenshotly API and Notion's File Upload API.

Asad AliOctober 10, 20259 min read

A Notion database of tools, competitors or research links is easier to scan with a picture of each page. This guide builds one complete workflow: a Node.js script that finds rows with a URL but no screenshot, captures each page with the Screenshotly API and attaches the image to the row.

At the end are two variations, for Airtable and for Slack link previews.

How it was tested: the script was run with @notionhq/client 5.31 against offline mocks of the Notion API and the Screenshotly API. The Screenshotly mock validates each request against the production schema. The Notion requests match Notion's documented file upload flow.

How it works

  1. Find rows to fill: query the database's data source for pages where URL is not empty and Screenshot is empty.
  2. Capture: POST https://screenshotly.app/api/screenshot. The response body is the JPEG.
  3. Upload to Notion: create a file upload, send the bytes, then attach the upload to the page's Screenshot property. Notion requires the attach step within one hour of creating the upload.

Set up the database and keys

  1. In your Notion database, add two properties:
    • URL with the type URL
    • Screenshot with the type Files & media
  2. Create a Notion integration, copy its token, and share the database with the integration.
  3. Find the data source ID. Since Notion API version 2025-09-03, databases contain data sources, and queries go to a data source. Retrieving the database through the API returns its data_sources list with each ID.
  4. Create a Screenshotly API key. The free plan includes 100 captures in total, at up to 5 per minute.

Set three environment variables: NOTION_TOKEN, NOTION_DATA_SOURCE_ID and SCREENSHOTLY_API_KEY.

The script

Install the SDK with npm install @notionhq/client (version 5.12 or later), then save this as notion-screenshots.mjs:

// notion-screenshots.mjs — Node.js 18+, @notionhq/client v5.12+
import notionClient from '@notionhq/client';

const { Client } = notionClient; // the SDK is published as CommonJS

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  notionVersion: '2026-03-11', // file uploads are documented on this version
});
const DATA_SOURCE_ID = process.env.NOTION_DATA_SOURCE_ID;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function capture(url) {
  const response = await fetch('https://screenshotly.app/api/screenshot', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.SCREENSHOTLY_API_KEY,
      'Content-Type': 'application/json',
    },
    // A JPEG of the first screen stays well under Notion's 5 MiB free-workspace limit.
    body: JSON.stringify({ url, width: 1280, height: 800, format: 'jpeg', quality: 80, blockAds: true }),
  });
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Screenshotly ${response.status}: ${error.error} ${error.message ?? ''}`);
  }
  return Buffer.from(await response.arrayBuffer());
}

async function attachScreenshot(page) {
  const url = page.properties.URL.url;
  const image = await capture(url);

  // 1. Create the upload, 2. send the bytes, 3. attach it within one hour.
  const upload = await notion.fileUploads.create({
    mode: 'single_part',
    filename: 'screenshot.jpg',
    content_type: 'image/jpeg',
  });
  await notion.fileUploads.send({
    file_upload_id: upload.id,
    file: { filename: 'screenshot.jpg', data: new Blob([image], { type: 'image/jpeg' }) },
  });
  await notion.pages.update({
    page_id: page.id,
    properties: {
      Screenshot: {
        files: [{ type: 'file_upload', file_upload: { id: upload.id }, name: 'screenshot.jpg' }],
      },
    },
  });
}

const { results } = await notion.dataSources.query({
  data_source_id: DATA_SOURCE_ID,
  filter: {
    and: [
      { property: 'URL', url: { is_not_empty: true } },
      { property: 'Screenshot', files: { is_empty: true } },
    ],
  },
  page_size: 25,
});

for (const page of results) {
  try {
    await attachScreenshot(page);
    console.log(`Captured ${page.properties.URL.url}`);
  } catch (error) {
    console.error(`Skipped ${page.properties.URL.url}: ${error.message}`);
  }
  await sleep(13_000); // the Screenshotly free plan allows 5 captures per minute
}

Run it with node notion-screenshots.mjs. Each row gets a screenshot.jpg in its Screenshot property, and the script logs which URLs it captured or skipped.

What each part does

  • notionVersion: '2026-03-11' is the API version Notion's file upload docs use. It also supports the data source query.
  • The capture asks for a 1280 × 800 JPEG at quality 80 with blockAds: true, which blocks known ad requests and hides common cookie-banner elements. All of these are available on the free plan.
  • fileUploads.create → fileUploads.send → pages.update is Notion's three-step upload. pages.update replaces the whole Files list, which is fine here because the property starts empty.
  • Errors are logged per row, so one blocked page doesn't stop the run. The Screenshotly API rejects private and internal addresses (400 Unsafe URL), and some sites block automated browsers.
  • The 13-second pause keeps the free plan under 5 captures per minute. On Basic (40 per minute) and above you can shorten it. Notion's own limit is an average of 3 requests per second, which three Notion calls per row stays well under.
  • page_size: 25 handles 25 rows per run. Run it on a schedule, for example with cron or a CI job every hour, and new rows are picked up on the next run.

Refreshing screenshots

The filter only picks rows with an empty Screenshot property. To refresh old captures, clear the property (or add a date property such as Captured on and filter on it). Every refresh uses one capture from your quota.

Showing the image in the page body

To show the screenshot inside the page instead of in a property, attach the upload to an image block in place of the pages.update call:

await notion.blocks.children.append({
  block_id: page.id,
  children: [{ type: 'image', image: { type: 'file_upload', file_upload: { id: upload.id } } }],
});

If you want both, create a separate upload for each. To show screenshots as cards in a gallery view, keep the property version and choose the Screenshot property as the card preview.

Variation: Airtable

Airtable can store the screenshot in an attachment field. Airtable's Web API has an upload attachment endpoint that accepts the file as base64, up to 5 MB:

// image is the Buffer returned by capture(url) above
await fetch(
  `https://content.airtable.com/v0/${BASE_ID}/${recordId}/Screenshot/uploadAttachment`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.AIRTABLE_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      contentType: 'image/jpeg',
      filename: 'screenshot.jpg',
      file: image.toString('base64'),
    }),
  },
);

The token needs the data.records:write scope. Airtable allows 5 requests per second per base. Airtable also documents adding attachments from a public URL. On Screenshotly Basic and above, "storage": { "enabled": true } returns such a URL, but it expires after 24 hours, so the attachment must be created before then.

A Slack app can show a screenshot when someone shares a link. Subscribe to the link_shared event for your domains (an app can register up to five unfurl domains), then reply with chat.unfurl and an image block.

Two constraints shape the design:

  • Slack's image block needs a publicly hosted image URL. Upload the capture to your own storage or CDN and use that URL, rather than a Screenshotly link that expires after 24 hours.
  • Slack doesn't send link_shared for messages posted by apps or integrations, so bot-posted links won't trigger a preview.

Capture at width: 1200, height: 630 for a wide preview, and cache by URL so a link shared ten times is captured once.

Making it reliable

  • Cache: most pages in a research or tools database change rarely. Capture once and refresh monthly. On Basic and above, "cache": true with a cacheTtl of up to 86,400 seconds (24 hours) also returns repeat requests from cache.
  • Pages that render late: add "waitForNetworkIdle": true, a "delay" of up to 10,000 ms, or "waitForSelector" to the capture body.
  • Signed-in pages: Basic and above can send cookies or headers with the capture. The API can't log in for you, so the session must come from your own system.
  • Element screenshots: "selector": "#pricing" captures one element, and "clip" captures a fixed rectangle. Both work on every plan.
  • No-code instead of a script: Make and n8n can call the capture API too. Check that their Notion modules support file uploads before relying on them; otherwise keep the upload step in a script.

Ready to add screenshots to your Notion workspace?

Create a free API key →. It includes 100 captures to try the script.

See also:

notion
airtable
automation
no-code

About the Author

Asad Ali

Asad Ali

CTO at ZTABS and the developer behind Screenshotly. Writes about screenshot automation, API design, and building reliable SaaS backends with Next.js, Node.js, and TypeScript.

Credentials: CTO at ZTABS, full-stack developer, builder and maintainer of Screenshotly and its official JavaScript and Python clients

Frequently Asked Questions

Can I auto-populate a Notion database with screenshots of each linked URL?

Yes. A small script queries the database for rows that have a URL but no screenshot, captures each URL with the Screenshotly API, uploads the image with Notion's File Upload API and attaches it to a Files & media property. Run it on a schedule to pick up new rows.

Why upload the file instead of using an external image URL?

Notion external images must point directly at a hosted image, and Screenshotly's download links are signed and expire after 24 hours. Uploading the file stores a copy in Notion, so the screenshot keeps working.

How large can the screenshot be?

Notion limits uploads to 5 MiB per file on free workspaces, and single-part uploads to 20 MB. A 1280 × 800 JPEG of a page's first screen is usually far below that. Full-page PNGs of long pages can exceed it, so use JPEG or a viewport capture for Notion thumbnails.

Ready to capture your first screenshot?

Get started with 100 free screenshots. No credit card required.

Related Articles