SDKs

Official SDKs wrap the API with typed methods, retries, and sensible defaults, and cover every live endpoint. Clients are available for Node.js/TypeScript, Python, Ruby, and Go. Use the language client instead of raw HTTP when you can.

Methods

Every client exposes all nine endpoints. Method names are idiomatic per language (camelCase in TypeScript/Go, snake_case in Python; option keys follow the same convention):

• read(url) → /api/scrape — any URL to clean markdown, HTML, or text
• search(query) → /api/search — ranked live-web results, optionally read to markdown
• crawl(url) → /api/crawl — clean markdown for every page on a site
• map(url) → /api/map — every URL on a domain
• extract(url) → /api/extract — structured JSON from a page (prompt or JSON Schema)
• classify(url) → /api/classify — NAICS/SIC industry codes, or your own labels
• enrich(input) → /api/brand — brand profile from a domain, URL, or work email
• images(url) → /api/images — every image on a page with alt text
• screenshot(url) → /api/screenshot — capture a URL as a PNG data URL

Install

# Node.js / TypeScript
npm install @synoppy/sdk

# Python
pip install synoppy

# Ruby
gem install synoppy

# Go
go get github.com/Synoppy/synoppy-go

TypeScript

import { Synoppy } from "@synoppy/sdk";

const client = new Synoppy({ apiKey: process.env.SYNOPPY_API_KEY });

const result = await client.read("https://example.com", {
  formats: ["markdown"],
  onlyMainContent: true,
});

console.log(result.markdown);

Python

import os
from synoppy import Synoppy

client = Synoppy(api_key=os.environ["SYNOPPY_API_KEY"])

result = client.read(
    "https://example.com",
    formats=["markdown"],
    only_main_content=True,
)

print(result["markdown"])

Ruby

require "synoppy"

client = Synoppy::Client.new(api_key: ENV["SYNOPPY_API_KEY"])

result = client.read("https://example.com", formats: ["markdown"])

puts result["markdown"]

Go

package main

import (
	"context"
	"fmt"

	"github.com/Synoppy/synoppy-go"
)

func main() {
	client := synoppy.New("YOUR_API_KEY")

	result, err := client.Read(context.Background(), "https://example.com", synoppy.ReadOptions{
		Formats: []string{"markdown"},
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(result.Markdown)
}

Authentication works the same as the HTTP API; read Authentication for key handling.

Error handling

A non-2xx response raises a typed SynoppyErrorcarrying the API's code and status:

// TypeScript
import { Synoppy, SynoppyError } from "@synoppy/sdk";

const client = new Synoppy({ apiKey: process.env.SYNOPPY_API_KEY });

try {
  const page = await client.read("https://example.com");
  console.log(page.markdown, page.creditsUsed);
} catch (err) {
  if (err instanceof SynoppyError) console.error(err.code, err.status, err.message);
}

# Python
from synoppy import Synoppy, SynoppyError

client = Synoppy(api_key="syn_live_...")

try:
    page = client.read("https://example.com")
    print(page["markdown"], page["creditsUsed"])
except SynoppyError as err:
    print(err.code, err.status, err)

Every successful response carries creditsUsed and creditsRemaining — see Credits. Building an agent? Skip the glue code and use the framework integrations or the MCP server.