TypeScript SDK

Give your agents the live web from TypeScript. Every method and result is typed.

Install

npm install stophy

Try it without a key

import { Stophy } from "stophy";

const stophy = new Stophy();

const page = await stophy.scrape({ url: "https://example.com", formats: ["markdown"] });
console.log(page.data.markdown);

const results = await stophy.search({ query: "bun runtime", limit: 3 });
console.log(results.data?.web);

scrape, search, map and parse work without a key, within a small free allowance. Every other method throws a StophyError with the code apiKeyRequired.

Use an API key

Get a key at stophy.dev/signup. Set it as STOPHY_API_KEY, or pass it in:

const stophy = new Stophy({ apiKey: "st_..." });

new Stophy("st_...") works too. Each method sends one call to the Stophy API and returns its JSON as is. scrape returns { success, data }, and map returns { success, links }.

Read a site with a parser

A parser reads a site’s page and returns its data as JSON: Reddit posts, Google Maps places, Amazon products, YouTube videos and more. Send the page URL and the parser’s name:

const places = await stophy.parsed(
  "google-maps",
  "https://www.google.com/maps/search/dentists+in+Ljubljana",
);
console.log(places.data.json);

parsed calls scrape with the format { type: "json", parser }. The parser name is typed, so your editor lists every parser. await stophy.parsers() returns each parser with the page it reads and what it returns. The third argument sends the parser’s options, such as the next page:

const next = await stophy.parsed(
  "google-maps",
  "https://www.google.com/maps/search/dentists+in+Ljubljana",
  { page: 2 },
);

Paging needs an API key.

Crawl a site

crawl answers at once with an id. Ask crawl.status for the pages:

const job = await stophy.crawl({ url: "https://bun.com/docs", limit: 20 });
if (job.id) {
  const status = await stophy.crawl.status({ id: job.id });
  console.log(status.status, status.completed, status.total, status.data);
}

status is scraping until the crawl is completed. A status answer holds up to 100 finished pages. Wait until the status is completed. When the answer has a next link, send the cursor value from that link with the same id to get the rest. crawl.cancel({ id }) stops the crawl and keeps the pages already read. A crawl and its pages are kept for 24 hours. batch.scrape takes a list of URLs and works the same way, with batch.scrape.status and batch.scrape.cancel.

Extract fields from pages

const job = await stophy.extract({
  urls: ["https://example.com"],
  prompt: "What is this page for?",
});
if (job.id) {
  const result = await stophy.extract.result({ id: job.id });
  console.log(result.data, result.confidence);
}

extract.result throws a StophyError with the code notFound until the result is ready. Results are kept for 24 hours.

Handle errors

import { StophyError } from "stophy";

try {
  await stophy.scrape({ url: "not a url" });
} catch (error) {
  if (error instanceof StophyError) {
    console.log(error.code, error.message, error.retryable);
  }
}

StophyError has code, message, retryable, retryAfterSeconds, status, and requestId. The message says what went wrong and what to do next. The SDK retries network errors and the HTTP statuses 429, 500, 502, 503, and 504, and it waits as long as the API asks. If the API asks for a wait longer than 60 seconds, the SDK throws right away with retryAfterSeconds set.

Options

Option	Default	What it does
`apiKey`	`STOPHY_API_KEY`	Your API key
`baseUrl`	`STOPHY_BASE_URL`, or the Stophy API	The server to call
`maxRetries`	`2`	Retries per request. `0` turns retries off.
`timeoutMs`	`70000`	Time limit for each attempt. A timed-out attempt is not retried.

Each method also takes signal to cancel the request.

Check your account

const limits = await stophy.limits();
const usage = await stophy.usage();
const logs = await stophy.logs({ days: 7 });

limits returns your balance and rate limit. usage returns your all-time usage. logs returns your recent calls. All three need an API key.

​Install

​Try it without a key

​Use an API key

​Read a site with a parser

​Crawl a site

​Extract fields from pages

​Handle errors

​Options

​Check your account