Create a free Bowmark account for more calls
registerCreates 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent | No | OPTIONAL free-text name for this account, so the user can tell their keys apart later ("claude-code on my laptop", "research-bot"). Purely a label. | |
| No | OPTIONAL contact address. It 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 supplied one; omit it entirely otherwise. Never invent, guess, or placeholder this — an address you made up is somebody else's mailbox. | ||
| newsletter | No | OPTIONAL, and it DEFAULTS TO TRUE — occasional product and changelog email to the address you passed. Set false to decline. It does nothing at all when no `email` is given, since there is no address to reach. If you are passing an email, tell your user it subscribes them and that you can decline for them. | |
| promotions | No | OPTIONAL, and a SEPARATE consent from `newsletter`. Set true ONLY if the user explicitly agreed to promotional email. Defaults to false. Do not infer this. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| No | |||
| error | No | ||
| apiKey | No | ||
| reason | No | ||
| message | No | ||
| claimUrl | No | ||
| accountId | No | ||
| activeNow | No | ||
| keyPrefix | No | ||
| signInUrl | No | ||
| newsletter | No | ||
| promotions | No | ||
| claimExpiresAt | No | ||
| freeCallsPerMonth | No |