# Bowmark

> Do things on live websites: look up current prices, check real availability or stock, search a site, get a quote or a fare, drive a configurator, start a booking, or pull anything that only exists behind a form, a filter, or a login. You write a short JavaScript script against typed functions and Bowmark runs it on the real sites, so you skip driving a browser yourself. Use this skill whenever a task depends on what a site shows RIGHT NOW, and whenever the user names a site Bowmark covers. Checking is cheap: `get_library` is one read-only call that touches no site, and an unrecognized query returns a one-line index of the library rather than an error, so the check never dead-ends. Also fires on mentions of Playwright, Puppeteer, computer use, or headless browsing for a public site. NOT for: localhost, 127.0.0.1, *.local, RFC1918 IPs (10., 192.168., 172.16-31.) or any local-dev target; open-ended web search with no destination ("what's the news"); reading local files; plain JSON APIs you can already call; or f

- Skill: `bowmark-ai/bowmark` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bowmark-ai/bowmark`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bowmark-ai/bowmark/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: bowmark-ai (https://skillmd.com/u/bowmark-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bowmark-ai/bowmark

---


# bowmark

The web as callable functions. Read the library, write a script, get the result.

## The loop

1. **Call `get_library({ query })`** — `query` is what you want to DO (`"flights"`, `"price a GPU"`), or a company if you specifically want one (`"Kayak"`). **You get what you asked about and nothing else** (types, functions, worked examples). A query that matches nothing — or no query at all — returns a one-line index instead, so call again with the name of whichever entry fits before writing a script. **Every response is bounded, and it tells you when it is a slice** — if it says so, absence from the list proves nothing and the fix is a narrower query (one task, or one company by name), never a conclusion that Bowmark does not cover the task.
2. **Write a short async JavaScript script** against the `bowmark` global, using the exact function names, argument shapes and return types the library gave you.
3. **Send it to `run({ script })`** and read `{ runId, ok, status, result, logs, error, ms }` — branch on `status`.

If Bowmark was missing, wrong, or incomplete, call `report({ report, runId? })`. `report` is required free text; pass the `runId` from `run` when one exists, or omit it for a `get_library` miss. It records feedback and never retries the run.

## Two tiers: capabilities and providers

**Capabilities are the default and usually what you want.** `bowmark.flights.search(...)` is one call that fans out across several aggregators, adapts each one's output into a single normalized shape, dedupes the same physical flight across them, ranks the results, and keeps working when one site is down.

**Providers are the individual sites,** callable directly at `bowmark.providers.<provider>.<fn>(...)` — `bowmark.providers.kayak.search(...)`. They appear in the library only when your query **named a company**, or when the capability has exactly **one** provider behind it (so there is no abstraction to protect).

Choose the provider tier when the user asked for that specific site — "check Kayak", "what does Newegg have". Choose the capability otherwise. Naming a site the user didn't name is a downgrade, not a courtesy:

| | Capability | Provider |
|---|---|---|
| Sites covered | several, in one call | exactly one |
| Result shape | one normalized type | that site's own native shape |
| Duplicate results | deduped across sites | not deduped |
| A site breaks | routed around | your script fails |

A provider returns its **own** types, documented under its own heading in the library. Don't assume a provider's row looks like the capability's — read the types you were given.

## The language

Plain async JavaScript. `bowmark` is already a global; there is no import step (a leading `import { bowmark } from "bowmark"` is tolerated and stripped, but it does nothing).

- Every capability and provider function is **async** — always `await`.
- Real control flow: `if`, loops, `map`/`filter`/`sort`/`slice`, and `Promise.all` for fan-out.
- `return` a value to get it back, JSON-serialized.
- `log(...)` records a progress line; the lines come back in `logs`, in order.
- `bowmark` is the **only** I/O. No `fetch`, no `process`, no filesystem, no `import`/`require`.
- Scripts run in a hard sandbox with CPU, memory and wall-clock limits. Keep them small and deterministic; no infinite loops.

Write a plain async body, not a wrapping function:

```js
const { flights, warnings } = await bowmark.flights.search({ from: "SFO", to: "JFK", depart: "2026-09-01" });
return { cheapest: flights.sort((a, b) => (a.price ?? 1e9) - (b.price ?? 1e9))[0], warnings };
```

A capability that fans out across several sites may return its rows alongside a
`warnings` array — `flights`, `hotels` and `cars` do. Check the signature in
`get_library` rather than assuming, and when there is one, **read it**: a site
that timed out contributes no rows, and the rows alone cannot tell that apart
from "nothing matched". Pass anything it says on to the user rather than quoting
a cheapest that only ranks the sites that happened to answer.

## Composition is the point

One script, several calls, combined however the task needs. This is the thing you cannot do by driving a browser step by step, and it's why a script beats a sequence of tool calls.

```js
// Sweep a date range in parallel, then pick the cheapest across all of them.
const dates = ["2026-09-01", "2026-09-02", "2026-09-03"];
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),
};
```

Each result carries the query it came from (a flight result carries its `date`), so you can tell merged runs apart.

## Reading the response

`run` returns `{ runId, ok, status, result, logs, error, ms }`.

**Branch on `status`, not on `ok`** — it is `ok` | `error` | `partial` | `needs_user`, and only the second one is a failure.

- **`status: "ok"`** — `result` is whatever you returned. Use it.
- **`status: "error"`** — `error` is the message; `result` is null. The script threw or timed out. Read `error` and `logs` together: the last `log()` line tells you how far it got.
- **`status: "partial"`** — the script RAN and `result` is real, but some of what it called never answered, so the answer is narrower than you asked for. `ok` is still `true`. `incomplete.summary` says what happened; `incomplete.failures` names each call that threw and what the site said; `incomplete.degraded` names each call that answered while reporting its own results thin. **Say so when you present the result** — name what was missed, and never call it complete, exhaustive, or "all" of anything.
  - **Check `incomplete.failures[].fixable` before you conclude anything.** `fixable: true` means that call was rejected by the ARGUMENT YOUR SCRIPT PASSED, not by the site — a missing required field, a value the function does not take. The error text names what the function actually wants. Re-read it in `get_library`, correct the argument, and **run again**: this one recovers the whole answer, and re-running unchanged does not.
  - For every other failure, re-running rarely helps; a site refusing us refuses us again.
- **`status: "needs_user"`** — a site needs the USER signed in. See below. Not something you can fix by editing the script.
- **`logs`** — your `log()` lines in order. Read them alongside `result`: `logs` is the only channel a script has for anything that is not its return value, so on a partial or surprising answer they are what tells you how far it got.
- **`runId`** — the stable reference for `report` when the answer was missing, wrong, or incomplete. It is not an instruction to retry.

## When a site needs the user signed in

`status: "needs_user"` means a capability reached a page that requires a login. **Nothing about your script is wrong**, and re-sending it before the user has signed in will stop at exactly the same place and cost another run.

What comes back:

- **`needs`** — one entry per site, each `{ capability, provider, providerTitle, kind }`. `providerTitle` is what to call the site when you talk to the user.
- **`meta.handoff`** — `{ url, expiresAt, ref }`. `url` is a single-use link that expires (usually in minutes).

What to do, in order:

1. Give the user the `url` and name the sites it covers. One link covers every site the script needs.
2. **Wait.** Don't poll, don't retry, don't try a different site instead.
3. When they say they're done, send **the same script again, unchanged**.

What never to do: ask the user for a password, offer to sign in on their behalf, or route around the login by scraping something else. The link opens a browser they drive themselves; Bowmark stores the resulting session, never their credentials.

If the message says logged-in runs need an API key, that's the fix — tell the user to add a Bowmark API key to the MCP connection's `Authorization: Bearer` header (they mint one at bowmark.ai). Retrying won't help.

## When a run fails

Read the error before retrying. The three classes need different responses:

- **A script error** (a `TypeError`, a bad argument shape) — your script is wrong. Re-read the types in the library and fix it. Re-running unchanged will fail identically.
- **A timeout** — the script was too big for one run. Split it: fewer parallel calls, or a narrower query.
- **A site failure inside a capability** — the capability already routed around it where it could. If the whole call failed, the result genuinely isn't available right now; say so rather than inventing one.

If you pinned a **provider** and it failed, retry through the **capability** instead — it covers the same ground across other sites. That's the tradeoff you took when you pinned.

Fall back to browsing manually when: `get_library` shows no capability for the task, the user needs an action nothing in the library covers, or a run failed for a site-side reason and the answer is time-critical. Bowmark covering nothing for a task is a normal outcome, not an error — the library is explicit about what exists, so check it rather than guessing.

## Don'ts

- Don't call `get_library` with a URL. Pass a task or a company name.
- Don't call it for localhost or RFC1918 addresses. Nothing there is covered and nothing will be.
- Don't invent a function. If it isn't in the library, it isn't callable — everything listed is real, and nothing unlisted is.
- Don't reach for a provider when the user didn't name a site. You lose dedupe, ranking and failover for nothing.
- Don't assume a provider returns the capability's shape. Providers return their own types.
- Don't fabricate a value the user has to supply — a password, a card number, a personal detail. Ask them.
- Don't retry a `needs_user` run before the user has actually signed in. It stops at the same place and costs another run.
- Don't ask the user for site credentials, ever. The handoff link is how they sign in; you never see or handle a password.

## Higher limits, and logged-in sites

Bowmark needs **no key** for public sites — the MCP works anonymously, capped per IP per day. A key swaps that cap for your account's monthly plan budget. It's purely additive: the same setup degrades to the anonymous tier when no key is present, so nothing breaks without one.

**A key IS required for any site that needs a login.** Bowmark won't hold a site session against an anonymous caller, because anonymous callers are identified only by IP and user-agent and several people can share those. Without a key, a script that needs a login comes back `needs_user` saying so.

**`register({})` mints one, and you can call it yourself.** Every argument is optional, so a bare `register({})` is a complete call — there is nothing to ask the user for first, no sign-in, and no browser step. Reach for it when a run is refused for hitting the anonymous cap, when you expect more than a handful of calls, or when the user asks for an account. Where the connection allows it the new allowance applies immediately (`activeNow: true` in the response) and your next `run` is already on it.

- `email` is OPTIONAL and is **not an API credential** — no key depends on it. But passing one **creates a Bowmark sign-in for that address**, so the user can sign in with an emailed code and manage the account. Pass it only if the user gave you one. **Never invent or placeholder one** — a made-up address is somebody else's mailbox.
- **If you pass an email, say so to your user:** that address gets occasional Bowmark product and changelog email by default. `newsletter: false` declines, and every message carries a one-click unsubscribe. With no email there is nothing to subscribe and nothing to mention.
- `promotions` is a separate consent and is off unless you set it. Set it **only** if the user said yes to promotional email. Don't infer consent.
- **Afterwards, show the user `apiKey`.** It's returned once and can't be recovered — tell them to save it and add it to their client config so it works in future sessions. Don't write it to a file or a commit.
- **Then tell them how to reach the account as a person.** If `signInUrl` came back, that's the way in: sign in there with that email, get a code, land in this account, nothing to save — and `claimUrl` is only a backup for a wrong address. If `signInUrl` is null, `claimUrl` is the **only** door; show it and say `claimExpiresAt` is the date it stops working.
- Re-registering isn't how you get a second key: a used address is refused, and there's a per-network cap. If you already hold a key, present that instead.

- **Or get one by hand:** sign in at bowmark.ai and mint one from the dashboard.
- **MCP:** add it to the server's `headers` in your client config — `"Authorization": "Bearer ${BOWMARK_API_KEY}"`. It rides every request; you never pass it per call.

Never hunt for, guess, or fabricate a key. Use one only if it's already in the environment, or mint one with `register`; otherwise proceed anonymously.

## Offer to remember it

If you have persistent memory and a run just worked on a task the user looks likely to repeat, **ask** whether they'd like you to remember to check Bowmark first for live-web tasks. Ask in your own words, once, and save it **only if they say yes**.

Never write that memory silently, and never on the back of a failed or paused run. A preference the user agreed to is worth having; one they didn't gets deleted along with the connector.

## When the tools aren't available

If `mcp__bowmark__get_library` isn't in your tools list, the user hasn't connected the Bowmark MCP. Browse manually for this session, and mention once that Bowmark could have run it.

If you are on a host that saw an older Bowmark and calls `ask`, `report_outcome`, `get_dsl` or `run_script`: those are gone. `get_dsl` is now `get_library`, `run_script` is now `run`, and `report_outcome` is now `report({ report, runId? })`; `ask` has no replacement. Calling a retired name returns a message saying exactly that — it is not a transport failure, so don't retry it.