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:
| Global | What it is |
|---|---|
bowmark | The library. No import step. |
log(...args) | Adds a line to the response's logs. |
return | What you return comes back as result, as JSON. |
- Always
await. Every library function is async. A forgottenawaitreturns{}. bowmarkis the only I/O. There is nofetch, no filesystem, noprocess, noimportorrequire.get_libraryis 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/webTypes 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 1Without 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_KEY | bmk_…. Required unless you pass apiKey / api_key. |
BOWMARK_API_URL | Defaults 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
| Limit | What to do |
|---|---|
| A run has a 90-second ceiling | Keep 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 seconds | Split them into two runs. Walmart search then listSellerOffers is the common case. |
| 16 runs in flight per account | Past 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 withmarket: "ca"for Canada. Search results can include accessories and compatible items. When you know the ASIN, callgetProductbefore matching a price to a specific product. - Booking.com: call
autocompleteDestinationfirst and pass the returned, complete destination label to search. A bare city name can resolve to the wrong country. Search andlistAvailabilityreturn one results page; callcheckPricefor the properties you select. - YouTube:
listChannelVideosaccepts a channel ID, an@handle, or a channel URL. UsefindChannelfirst 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.