Write a script

Find the functions you need with get_library, then call them in a short JavaScript script with run, from an agent or from your own Node or Python code.

Two calls

Every Bowmark task is two calls, in this order.

Look up the functions. get_library({ query }) returns the functions that match what you want to do, with their arguments and return types. It touches no website. A query that matches nothing returns an index of the whole library. For your own code, start with GET /v1/library?query=<site-or-task> rather than downloading the full library list.

// An agent's MCP tool call. From your own code, use GET /v1/library?query=flights.
get_library({ query: "flights" })

Pass what you want to do (flights, price a GPU) or a site's name or hostname (kayak.com). When the answer says it is a slice of a longer list, ask a narrower query.

Run a script. run({ script }) runs plain async JavaScript against those functions and returns what the script returns.

const { flights, warnings } = await bowmark.flights.search({
  from: "SFO",
  to: "JFK",
  depart: new Date(Date.now() + 30 * 864e5).toISOString().slice(0, 10), // 30 days out
});
return { flights: flights.slice(0, 3), warnings };

Every flights.search argument is listed on Flights and hotels.

An agent calls both as MCP tools. Your own code calls them over HTTP (No install at all) or through the client packages below.

Call read.page, read.pages, browser_agent and web_form_fields through run(), never inside session(). A session() refuses them.

The shape of a script

Write a plain async body, not a wrapping function. These globals are bound for you:

GlobalWhat it is
bowmarkThe library. No import step.
log(...args)Adds a line to the response's logs.
returnWhat you return comes back as result, as JSON.
  • Always await. Every library function is async. A forgotten await returns {}.
  • bowmark is the only I/O. There is no fetch, no filesystem, no process, no import or require.
  • get_library is not a global. Look functions up before you write the script.
  • Keep it small. A run has time and memory limits. See Limits.

Calls inside one script share state. Add to a cart, then read the cart, and it is the same cart. Two separate runs do not share anything.

Call a site

There are two kinds of function, spelled the same everywhere:

// A capability: one task, answered by every site that can serve it. Use this by default.
const { flights } = await bowmark.flights.search({ from: "SFO", to: "JFK", depart });

// A provider: one named site, when you want that site's answer.
const rows = await bowmark.providers.kayak.search({ from: "SFO", to: "JFK", depart });

Every site Bowmark covers is listed at /sites. A site with no functions can still be read with read.page. For typed JSON out of a page instead of parsing text, give browser_agent an outputSchema; its first example is at the top of that page.

Call several sites in one script

Use Promise.all to call many things at once, then combine the answers in the same script.

const day = (n) => new Date(Date.now() + n * 864e5).toISOString().slice(0, 10);
const dates = [day(30), day(31), day(32)]; // three days, a month out
const runs = await Promise.all(
  dates.map((depart) => bowmark.flights.search({ from: "SFO", to: "JFK", depart })),
);

return {
  cheapest: runs
    .flatMap((r) => r.flights)
    .sort((a, b) => (a.price ?? 1e9) - (b.price ?? 1e9))
    .slice(0, 5),
  warnings: runs.flatMap((r) => r.warnings),
};

Return the warnings too. They name any site that was left out of an answer. See Read the response.

From your own code

Install it

npm i @bowmark/web

Types for the whole library ship inside the package. Source: github.com/bowmark-ai/web.

The package ships TypeScript source, so plain node app.mjs fails with ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING. Run it with npx tsx app.ts or bun app.ts, or through any bundler (Next.js, Vite, esbuild). The examples use top-level await: add "type": "module" to package.json or name the file app.mts.

Needs Python 3.11 or newer. Use the current install command on Install before copying a Python example. The optional stubs package adds autocomplete.

Neither package exports get_library. To see what you can call, use GET /v1/library, /sites, or the CAPABILITIES.md and PROVIDERS.md lists.

One call

import { bowmark } from "@bowmark/web";

const { tracks } = await bowmark.music.search("aphex twin", 3);
console.log(tracks[0].title);
import asyncio
from bowmark_web import bowmark


async def main() -> None:
    found = await bowmark.music.search("aphex twin", 3)
    print(found["tracks"][0]["title"])


asyncio.run(main())

Both read your key from BOWMARK_API_KEY. Sign up at bowmark.ai/sign-up and create a key at bowmark.ai/dashboard/keys.

Several calls: use session()

Each plain bowmark.<unit>.<fn>() call starts fresh. Wrap a multi-step flow in session() so every call shares the same state, like a cart.

import { session } from "@bowmark/web";

const itemCount = await session(async (bm) => {
  const found = await bm.providers.gymshark.search({ query: "hoodie" });
  await bm.providers.gymshark.addToCart({ variantId: found.products[0].variantId });
  return (await bm.providers.gymshark.getCart()).itemCount; // 1
});
from bowmark_web import session

async with session() as bm:
    found = await bm.providers.gymshark.search({"query": "hoodie"})
    await bm.providers.gymshark.addToCart(
        {"variantId": found["products"][0]["variantId"]}
    )
    cart = await bm.providers.gymshark.getCart()   # itemCount is 1

Without session(), the second call gets an empty cart and no error. session() runs in your process. Do not put it inside a script string: there, calls already share state.

read.page, read.pages, browser_agent, and web_form_fields cannot run in a session() or as a plain call. Call them through run().

Bowmark does not write rows into Google Sheets. The google_sheets provider reads existing sheets, and the drive_google provider can create an empty sheet and export one as CSV, but neither provider appends or updates cells. Save generated data with bowmark.files instead, or write to a sheet in your own code after the run.

run() from your own code

run() sends a script string, exactly like the agent's run tool. Use it to make many calls in one round trip, and for read.page and browser_agent.

import { run } from "@bowmark/web";

const envelope = await run(`
  const { rates } = await bowmark.shipping.estimate({ fromZip: "94103", toZip: "10001", weightOz: 48 });
  return rates.slice(0, 3);
`);
if (!envelope.ok) throw new Error(envelope.error ?? `Bowmark run ${envelope.status}. Check incomplete.cutOff.`);
envelope.result;
from bowmark_web import run

envelope = await run('''
  const { rates } = await bowmark.shipping.estimate({ fromZip: "94103", toZip: "10001", weightOz: 48 });
  return rates.slice(0, 3);
''')
if not envelope["ok"]:
    raise RuntimeError(envelope["error"] or f"Bowmark run {envelope['status']}. Check incomplete.cutOff.")
rates = envelope["result"]

run() returns the response instead of throwing. Check ok before reading result; its error explains a failure. Every field is on Read the response. The script string is not type-checked.

A request header is not a page header

headers on a client config sends headers to Bowmark's API. headers: true on read.page returns the target page's response headers. read.page itself is always a GET and does not accept a caller-supplied request header, cookie, body or Authorization token. For a site behind your own login, use a saved connection; Bowmark does not turn an API token you supply into a third-party POST request.

Configuration

Variable
BOWMARK_API_KEYbmk_…. Required unless you pass apiKey / api_key.
BOWMARK_API_URLDefaults to https://api.bowmark.ai.

Both are read at call time, so a .env loader that runs after your import still works. Every entry point also takes apiKey / api_key, baseUrl / base_url, headers, timeout and onLog / on_log.

Errors the client throws, and what to do about each, are on Read the response.

No install at all

Anything that can send JSON over HTTP can use Bowmark. Both endpoints need Authorization: Bearer <key>.

curl -s "https://api.bowmark.ai/v1/library?query=flights" \
  -H "Authorization: Bearer $BOWMARK_API_KEY"

curl -s -X POST https://api.bowmark.ai/v1/run \
  -H "Authorization: Bearer $BOWMARK_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"script":"const { rates } = await bowmark.shipping.estimate({ fromZip: \"94103\", toZip: \"10001\", weightOz: 48 }); return rates.slice(0, 3);"}'
const res = await fetch("https://api.bowmark.ai/v1/run", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.BOWMARK_API_KEY}`,
  },
  body: JSON.stringify({
    script: `const { rates } = await bowmark.shipping.estimate({ fromZip: "94103", toZip: "10001", weightOz: 48 });
             return rates.slice(0, 3);`,
  }),
});
const { status, result } = await res.json();
import json, os, urllib.request

req = urllib.request.Request(
    "https://api.bowmark.ai/v1/run",
    data=json.dumps({
        "script": 'const { rates } = await bowmark.shipping.estimate({ fromZip: "94103", toZip: "10001", weightOz: 48 });'
                  " return rates.slice(0, 3);"
    }).encode(),
    headers={
        "content-type": "application/json",
        "user-agent": "my-app/1.0",  # required with urllib, see below
        "authorization": f"Bearer {os.environ['BOWMARK_API_KEY']}",
    },
)
with urllib.request.urlopen(req, timeout=180) as r:
    out = json.load(r)
print(out["status"], out["result"])

Python urllib: set a User-Agent

The API refuses Python's default urllib User-Agent with a 403. Send any other user-agent header, as above. requests, httpx, aiohttp and the bowmark_web package are not affected.

To check your bill from code, call GET /v1/usage with the same key. See Cost at volume.

Files

bowmark.files.save({ name, text }) always creates a new file, even when name is already in use. Two runs that save state.json leave two files. To keep only the latest, delete the previous one by its id with bowmark.files.delete(id), or give each run its own name. Use bowmark.files.list() to find the ids.

Limits

LimitWhat to do
A run has a 90-second ceilingKeep each run well inside it, and set any client timeout above it. Make calls in parallel inside a run; spread long jobs across several runs.
Two slow calls in a row can pass 90 secondsSplit them into two runs. Walmart search then listSellerOffers is the common case.
16 runs in flight per accountPast it, POST /v1/run answers 429 with Retry-After. Nothing ran or was charged: send fewer at a time.

Common provider limits

  • Amazon: use bowmark.providers.amazon.searchProducts({ keywords, market: "com.br" }) for Brazil, and the same generic provider with market: "ca" for Canada. Search results can include accessories and compatible items. When you know the ASIN, call getProduct before matching a price to a specific product.
  • Booking.com: call autocompleteDestination first and pass the returned, complete destination label to search. A bare city name can resolve to the wrong country. Search and listAvailability return one results page; call checkPrice for the properties you select.
  • YouTube: listChannelVideos accepts a channel ID, an @handle, or a channel URL. Use findChannel first when you only have a plain channel name.

A run cut off by a limit returns what finished. See A run that hit a limit.

Cost at volume

Each run is billed for what it used. Rates are on Pricing. To learn what one of your scripts costs, run it, then read this month's itemized bill:

curl -s https://api.bowmark.ai/v1/usage \
  -H "Authorization: Bearer $BOWMARK_API_KEY"
# { "month": "2026-11", "totalUsd": 1.42, "lines": [{ "sku", "quantity", "unit", "usd" }], ... }

Pass ?month=YYYY-MM for a past month. Compare totalUsd before and after a few runs, then multiply. To run a script on a schedule, see Run on a schedule.