ai.bowmark/bowmark

Tools

• add_connection

  Get a sign-in link for one site, so the user can sign Bowmark in to it right now, before any run needs it. Pass the site as a domain (`youtube.com`), a URL, or a provider id. **Call this whenever the user asks to log in, sign in, connect or link an account on a site** — never send them to the Bowmark Link extension or the dashboard to do it themselves. It returns `url`, a single-use link that expires (`expiresAt`). Give the user that URL and say which site it is for. On that page they sign in with Bowmark's own browser, or, in desktop Chrome with Bowmark Link installed, press "Use Chrome extension" to send the login that Chrome already holds. Then call `wait_for_sign_in` with the returned `ref`: it answers the moment they finish, and every later run uses the new login. When Bowmark cannot sign in to that site, it says so and returns `sites`, the sites it can sign in to. Tell the user plainly. Do not offer a workaround that asks for their password. A public page on that site still works without a login: `get_library` shows what can read it. To sign back in to a saved login that stopped working, pass its `id` from `list_connections` as `connection`. The fresh session goes into the SAME id.

  shallow
• delete_connection

  Start deleting a saved login by the `id` `list_connections` returned. **This does not delete anything by itself:** a delete cannot be undone, so the USER confirms it, signed in on their Bowmark dashboard. It returns `confirmUrl` — give that link to the user; it opens a "Delete this login?" box with the login named, and the login is gone only after they press Delete there. Nothing you can call completes it for them. Only call this when the user asked to remove a saved login. To sign out of a site, use `logout_connection` instead. Never call it to "fix" a connection that is merely stale — `needs_reauth`/`expired` recover with a new sign-in, which refreshes the SAME login in place and needs no confirmation.

  shallow
• get_library

  **Use this whenever a task touches a live website.** It answers, definitively and cheaply, whether Bowmark can already DO the thing: 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. **Checking is cheap, so check.** One read-only call, no site is touched, and an unrecognized query returns a one-line index instead of an error, so the check never dead-ends and never costs you an attempt. If nothing fits, you have lost one cheap call and can use your normal approach. What comes back is the callable **function library** you write against: the runtime globals (`log`) PLUS, for each capability your query named, its namespace, TypeScript types, functions, and worked examples. Everything listed is real and callable. The language rules and how to run a script are on the `run` tool description. Pass `query` — what you want to DO (`"flights"`, `"price a GPU"`) or, if you have one in mind, the COMPANY or site (`"Kayak"`, `"newegg.com"`). A phrase in the user's own words is fine; it is matched against the whole library. **You get what you asked about and nothing else.** If nothing matches — or you send no query — you get instead a one-line index: pick whichever entry fits and CALL AGAIN with its name to get the types and examples you need to write a script. **Every response is bounded, and it says so when it is a slice.** A broad query can match more than one response carries; when that happens the answer opens with a partial-answer line naming what it left out. **Read it before concluding anything** — absence from a sliced list means nothing, and the fix is one narrower query (a single task, or a single company by name), which always returns that entry in full. Only an answer that does NOT say it is a slice supports the conclusion that a task is uncovered. **Two tiers come back.** CAPABILITIES (`bowmark.flights.search(...)`) are the default and usually what you want: one call fans out across several sites, dedupes, ranks, and routes around a site that's failing. PROVIDERS (`bowmark.providers.kayak.search(...)`) are the individual sites, callable directly — they appear only when your query NAMED a company, or when the capability has just one provider behind it. A direct provider call gets that site's own raw shape and no failover, so prefer the capability unless you specifically want that site. Loop: call `get_library` → write a JS script against the `bowmark` global → send it to `run`.

  shallow
• get_secret_link

  Return the dashboard link for one stored secret this account holds, so you can answer "where is my Acme password?" with somewhere to go. **It returns a URL, never a value** — opening it requires the user to be signed in and to confirm who they are, and only their own browser can read what comes back.

  shallow
• lease_ip

  Some sites (LinkedIn, marked 📍 in `get_library`) only accept a login from the address it signed in from. A dedicated IP is one address that only this account uses, and once the account holds one, every sign-in link and every later call on that login uses it automatically. Call with no arguments first. If the account already holds one, it says so and nothing is bought. Otherwise it returns `priceCents` and a `message` with the price for `termDays` days in `country` (default US). The price is charged up front and is not refundable. If something must happen first (a card on file, a one-time identity check), `mustFirst` names it with the link that fixes it: give your user that link and stop. **Never buy without asking.** Tell your user the exact price and buy only if they agree, by calling again with `confirmPriceCents` set to the price they agreed to. A live price above that is refused before any charge, and repeating the same call cannot buy two. Pass `another: true` only when your user asked for a second IP.

  shallow
• list_connections

  List the saved logins this account holds — which site, which account, whether it is still good, and when it was last used. A live one means a script can reach that site's signed-in pages with no sign-in step and usually no browser. Useful before a task that needs an account: a connection marked `needs_reauth` or `expired` is why a run would pause and ask the user to sign in again. Revoking one is deliberately not a tool — it is the user's to do, at https://bowmark.ai/dashboard/connections.

  shallow
• list_secrets

  List the stored secrets this account holds, by NAME. Returns name, type, which hosts each may be used against, when it expires and when it was last used — never a value, and no Bowmark endpoint returns one. **Call this BEFORE `request_secret`.** A secret the user has already set is ready to use; asking for it again sends them to a page for nothing. In a script, refer to one by name: `bowmark.secret('acme_pw')`.

  shallow
• logout_connection

  Sign a saved login out by the `id` `list_connections` returned. Bowmark drops the cookies it held, and where the site supports it (`siteLogout: "supported"` in the reply) the session is ended ON THE SITE too — `siteSignedOut: true` means Bowmark checked the site no longer accepts it. The saved login is KEPT, status `logged_out`, so the user can sign back in to the same entry later. Call this when the user asks to sign out of a site. `delete_connection` is the other action: it hands the user a link to forget the entry entirely, which leaves the site session alive.

  shallow
• register

  **Creates a free Bowmark account and returns an API key.** Call it when a `run` is refused for hitting the anonymous limit, when you expect to make more than a handful of calls, or any time the user says they want an account. **Every argument is optional. `register({})` is a complete, valid call** and returns a working key. Do NOT stop to ask the user for anything before calling this — there is nothing required to ask for. WHAT IT BUYS: anonymous callers share one small daily allowance per IP address with everything else behind it. A registered account gets its own monthly allowance, an order of magnitude larger. The response says both numbers. Where the connection allows it the new allowance applies IMMEDIATELY, with no configuration change — `activeNow: true` in the response means your very next `run` is already on it. `email` is OPTIONAL and no key depends on it — it is not a credential, and nothing you do with the API authenticates with it. **But passing one CREATES A BOWMARK SIGN-IN for that address**, so the person can sign in at bowmark.ai with an emailed code and manage the account without keeping any link. Pass it only if the user actually gave you one. **Never invent one and never pass a placeholder** — that creates a sign-in for somebody else's mailbox. **IF YOU PASS AN `email`, TELL YOUR USER THIS:** that address is subscribed to occasional Bowmark product and changelog email by default. Pass `newsletter: false` to decline, and say so plainly rather than deciding for them — every message carries a one-click unsubscribe either way. With no `email` there is nothing to subscribe and nothing to mention. `promotions` is a SEPARATE consent and is OFF unless you set it. **Only set it if the user has actually said yes to promotional email.** Do not infer consent from enthusiasm, and do not set it to be helpful. AFTER IT RETURNS: show the user `apiKey`. It is returned exactly once and cannot be recovered — tell them to save it and to add it to their Bowmark MCP config as `Authorization: Bearer <key>` so it works from every future session. Do not put the key in a file, a commit, or anywhere it outlives the conversation. **HOW THEY REACH THE ACCOUNT AS A PERSON.** If `signInUrl` came back, that is the way in: they sign in there with the email you passed, Bowmark sends a code, and they land in this account. Nothing to save. `claimUrl` is then 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, because after that they can use the key but never manage or revoke the account. Re-registering is not how you get a second key: an address that already has an account is refused, and there is a per-network cap. If you already hold a key, present it instead.

  shallow
• report

  Record what was missing, wrong, or incomplete so Bowmark can build it. Pass the `runId` returned by `run` when this report is about a run; omit it when `get_library` did not cover the task. This records feedback only and does not retry a run.

  shallow
• request_secret

  Create a named, empty slot for a secret and get back a link the user opens to fill it in. They type the value on a Bowmark page and choose how long it lives, from 5 minutes to never. It is encrypted in their own browser before it leaves, so nothing on the way — this connection included — ever sees it. **Give the user the link. Never ask them to type a password, API key or one-time code to you.** A secret in this conversation is in your context, in the transcript and in the logs. **Name it for the person, not for your script.** The name you pass is the heading on the page they open and the row they see in their secret list months later, so make it `<site>_<what it is>`: `letterboxd_password`, `stripe_api_key`, `acme_totp_seed`. A run id, a timestamp, a uuid or a bare `password` is refused. Call `list_secrets` first: if the name already exists and is set, use it instead. `name` is lowercase letters, digits, `_`, `.` and `-`. `hosts` narrows where the value may be used and is worth passing — a secret is refused against any other site.

  shallow
• run

  **Executes the task on the real websites** (the search, the price check, the availability lookup, the configurator, the booking flow) and returns what came back. Runs a script you authored against the `get_library` vocabulary, on the live sites, and returns `{ ok, result, logs, error, ms }`. Call `get_library` FIRST — it gives the exact function names, argument shapes, and return types; this description is the LANGUAGE + how-to (get_library is just the vocabulary). THE LANGUAGE — plain async JavaScript: • `bowmark` is a ready global (no import). Call capabilities off it — `await bowmark.<capability>.<method>(...)` — always `await`, they're async. • Individual sites are callable too, at `await bowmark.providers.<provider>.<fn>(...)`. Use one when you specifically want THAT site; otherwise prefer the capability, which fans out across sites and routes around failures. • Real control flow: `await`, `if`, loops, array methods (`map`/`filter`/`sort`/`slice`), and `Promise.all` for fan-out. • `return` a value to get it back (JSON-serialized). `log(...)` for progress lines. • `bowmark` is the ONLY I/O — no `fetch`, `process`, filesystem, or `import`/`require`. Write a plain async body, not a wrapping function. • Keep scripts small and deterministic — no infinite loops. Runs in a hard sandbox with CPU + memory + wall-clock limits. SENDING IT: pass the script text as `run({ script })` — `script` is the only argument (there is no `site` argument; the library exposes every capability under `bowmark`). `result` is whatever you returned; `logs` are your `log()` lines in order; on a throw/timeout `ok:false` and `error` is set. CHECK `status` BEFORE `ok`. It is `ok` | `error` | `partial` | `needs_user`. • `partial` means the script RAN and `result` is real and usable, but some of what it called never answered — so the result is narrower than what you asked for. `ok` is still `true`; this is not a failure. `incomplete.summary` says what happened in one sentence, `incomplete.failures` names each call that threw and what the site said, and `incomplete.degraded` names each call that answered while reporting its OWN results thin. You MUST say so when you present the result: name what was missed, and do not describe it as complete, exhaustive, or 'all' of anything. A `partial` you report as whole is a wrong answer, not a slightly smaller right one. • Before you conclude a `partial` is final, check `incomplete.failures[].fixable`. `fixable: true` means YOUR ARGUMENT was rejected, not the site — the error text names what that function actually takes, so re-read it in `get_library`, fix the argument and run again; that recovers the whole answer. For any other failure re-running usually returns the same thing. • `needs_user` means a site needs the USER signed in — it is NOT a failure and NOT something you can fix by editing the script. `needs` lists the sites; `meta.handoff.url` is a single-use link that expires (`meta.handoff.expiresAt`). Give the user that URL, say which sites it covers, and WAIT. When they tell you they're done, send the SAME script again unchanged. Do NOT retry before then — it will stop at the same place and cost another run. Do NOT try to log in yourself, ask them for a password, or work around it with a different site. • Logged-in runs need a Bowmark API key on the connection; if you get `needs_user` saying so, tell the user to add one rather than retrying. `trace` is the execution trace — every capability you called and the providers it fanned out to under the hood: `[{ kind:'capability', capability:'flights', method:'search', ms }, { kind:'provider', capability:'flights', provider:'google_flights', fn:'search', results, status, ms }, …]`. The script never visits websites — it calls capabilities that route to providers, and the trace is the receipt. Composition is the point — call a method MULTIPLE times and combine results. To sweep a date range, call the search per date inside `Promise.all` and sort/filter the merged array (each flight result carries its `date`, so you can tell the runs apart). See the `get_library` examples for the exact shape. SOME capabilities return their rows alongside a `warnings` array — `{ flights, warnings }`, `{ hotels, warnings }`, `{ cars, warnings }`. Others return a bare array. The signature in `get_library` tells you which; go by it rather than assuming. Where there IS a `warnings` array it names any site dropped from the fan-out, and the rows themselves look identical with or without it. Read it, and pass on anything it says rather than quoting a 'cheapest' that only ranks the sites that happened to answer. Dropping `warnings` from what you return does not hide it — the run comes back `status: 'partial'` regardless, because the runtime counts what your script CALLED, not what it chose to report.

  shallow
• run_view

  Used by the inline run view to draw a run's progress. You do not need to call this — `run` returns the result.

  shallow
• wait_for_sign_in

  Wait until the user finishes a sign-in link, so you know the moment they are done without asking them. Pass `ref`: `meta.handoff.ref` from a paused run, or `ref` from `add_connection`. **Call it right after you give the user the link, in the same turn.** Write the link in your reply first, so they can see it while this waits. It holds for up to `waitMs` (default 45000, at most 50000) and answers the moment the sign-in finishes. It returns `state`: • `done`: every site on the link is signed in. Send the SAME script again now (or carry on with the task after `add_connection`). Do not ask the user whether they are done. • `pending`: not yet; `remaining` names the sites still missing. Call it again with the same `ref`. Keep going while the link is live (`expiresAt`, 15 minutes); a person often takes a few minutes. • `cancelled`: the user pressed Cancel. Tell them, and do not re-send the script unless they ask. • `expired`: the link ran out first. Send the SAME script again; it pauses with a fresh link. • `unknown`: no link with that ref on this account. A ref starting `site:` cannot be watched: wait for the user instead. If the user replies while you are waiting, answer them; the link is still live and you can wait again.

  shallow

Embed this server’s score

Tool count and median score across every tool in this server’s corpus — honest in a way a single cherry-picked tool’s badge wouldn’t be.

[![Vouch score](https://vouch.tools/api/servers/ab4b9b93-85ac-4a17-9329-2767a408a189/badge.svg)](https://vouch.tools/servers/ab4b9b93-85ac-4a17-9329-2767a408a189)