HTTP API
The base URL, the auth header, and the endpoints — for a caller with no MCP client and nothing installed.
Bowmark is an HTTP API behind an API key. Nothing needs to be installed and no MCP client is required — if your code can send a request, it can use Bowmark.
This page is the reference: the base URL, the header, the endpoints. For worked
examples in Node, Python and curl, go to
Scripting § No install at all.
Base URL and auth
https://api.bowmark.aiNot bowmark.ai — that host serves the marketing site and these docs, and will 404 an
API path. Every endpoint below takes the same header:
Authorization: Bearer $BOWMARK_API_KEYThere is no anonymous tier and no public browsing: every call — GET /v1/library
included — is refused with 401 without a key. Sign up at
bowmark.ai/sign-up, create a key at
bowmark.ai/dashboard/keys, and add a payment method at
bowmark.ai/dashboard/billing.
The two calls
Everything a caller does is one of these, in this order — read the library, then send a script written against it.
GET /v1/library?query=… | Read the vocabulary. Returns the typed function library for a task or a site. Read-only, touches no site, costs nothing, and an unrecognized query returns the whole index rather than an error — so the call cannot dead-end. |
POST /v1/run | Execute a script written against that library, on the live sites. Body is {"script":"…"}; the script is async JavaScript and returns its result. |
curl -sS "https://api.bowmark.ai/v1/library?query=flights" \
-H "Authorization: Bearer $BOWMARK_API_KEY"curl -sS -X POST https://api.bowmark.ai/v1/run \
-H "Authorization: Bearer $BOWMARK_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"script":"const { offers } = await bowmark.pcparts.search(\"RTX 5080\"); return offers.slice(0,3);"}'run answers { ok, result, logs, error, ms }. What you may write inside script — the
bowmark.* globals, log, talk, pay, and the read.page fallback for a site with no
provider — is Scripting.
`/v1/library` returns markdown by default
It is a document meant to go straight into a model's context, so the default response is
text/markdown. Send Accept: application/json to get the machine shape instead.
Generating types
GET /v1/manifest?units=… | The same library as a machine-readable manifest, for a code generator rather than a model. units is required and comma-separated (?units=flights,providers.kayak) — there is deliberately no whole-catalog form, so call /v1/library first to find the ids. |
You usually do not need this: the @bowmark/web and bowmark-web
packages are generated from it and ship the types
already.
What is not here
The routes above are the whole caller-facing surface. Everything else under /v1/ —
the login handoff, secrets, files, saved connections, the per-company MCP servers — is
machinery the SDK and the sandbox drive on your behalf, documented where it is used rather
than as a route list. If you are reaching for one of those directly, email
support@bowmark.ai and tell us what you are building; that is
a gap in this page, not in the API.
Where to go next
- Quickstart — one
curl, a real answer off three live retailers. - Scripting § No install at all — the same two
endpoints with worked Node, Python and
curlexamples, and the PythonurllibUser-Agent caveat that costs a 403 if you miss it. - Installation — if your client does speak MCP, wire it up once and skip the HTTP layer entirely.