Endpoint

Read

Read is our name for the scrape endpoint — one and the same. POST/api/scrape fetches a single URL, strips nav/ads/boilerplate with Mozilla Readability, and returns clean content in the formats you request. Metered per request by the bytes read — a larger page costs more. Every response returns the exact creditsUsed. This endpoint is live.

Request body

urlstringrequired

The absolute URL to read. Must include the scheme, e.g. https://example.com/blog/post.

formatsstring[]

Output formats to return. Supported: "markdown", "html", "text". Defaults to ["markdown"].

onlyMainContentboolean

Strip navigation, headers, footers, and boilerplate to keep just the primary article body. Defaults to true.

renderboolean | "auto"

Render the page in a real browser before reading, so client-side and SPA content is included. true always renders; "auto" renders only when a static fetch comes back empty. Live now; metered by real browser time.

waitMsnumber

Extra settle time after the page loads, in milliseconds, when rendering — useful for content that hydrates late. Capped at 10000. Only applies when render is in effect.

timeoutMsnumber

Maximum time to spend fetching and rendering, in milliseconds. Defaults to 30000 (30s). Capped at 60000.

Example request

curl -X POST https://synoppy.com/api/scrape \
  -H "Authorization: Bearer $SYNOPPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/post",
    "formats": ["markdown", "html"],
    "onlyMainContent": true,
    "timeoutMs": 20000
  }'

Response

On success the requested formats and page metadata are returned at the top level. Only the formats you asked for are populated.

{
  "success": true,
  "markdown": "# Post title\n\nClean article body...",
  "metadata": {
    "title": "Post title",
    "description": "A short summary of the page.",
    "language": "en",
    "wordCount": 842,
    "sourceUrl": "https://example.com/blog/post",
    "statusCode": 200,
    "rendered": false,
    "bytesIn": 48213
  },
  "latencyMs": 512,
  "creditsUsed": 1,
  "creditsRemaining": 4999
}

creditsUsed is metered per request and varies with the bytes read.

Response fields

successboolean

True when the page was read successfully.

markdownstring

Clean Markdown content. Present when markdown was requested.

htmlstring

Readable HTML (main content). Present when html was requested.

textstring

Plain text. Present when text was requested.

metadataobject

title, description, language, siteName, author, ogImage, sourceUrl, statusCode, wordCount, fetchedAt, rendered (whether a real browser was used), and bytesIn (bytes downloaded — the basis for read billing).

latencyMsnumber

End-to-end processing time in milliseconds.

creditsUsednumber

Credits charged for this call, metered per request (by bytes read, browser time, or AI tokens).

In code

import { Synoppy } from "@synoppy/sdk";
const synoppy = new Synoppy({ apiKey: process.env.SYNOPPY_API_KEY });

const res = await synoppy.read("https://example.com/blog/post", {
  formats: ["markdown"],
  render: "auto",
});
console.log(res.markdown);

Errors follow a consistent shape, documented in Errors.