Bowmark AI Run API
The Run API from Bowmark AI — 1 operation(s) for run.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/bowmark-ai:bowmark-ai-run-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Bowmark Run API
version: 1.0.0
description: 'Run real tasks on live websites over plain HTTP. Two calls: read the typed function library for your task with `GET /v1/library`, then send a short async JavaScript script written against it to `POST /v1/run`. Or call one site''s functions directly: every site in `GET /v1/sites` has its own spec at `/v1/sites/{site}/openapi.json`. Guide: https://bowmark.ai/docs/api. Get a key at https://bowmark.ai/dashboard/keys.'
contact:
email: support@bowmark.ai
url: https://bowmark.ai/docs/api
termsOfService: https://bowmark.ai/terms
servers:
- url: https://api.bowmark.ai
security:
- bearer: []
- apiKeyHeader: []
tags:
- name: Run
paths:
/v1/run:
post:
operationId: run
summary: Run a script against the library on live sites
description: 'The script is the body of an async function: use `await` freely and `return` the result. It runs in a sandbox with the `bowmark` global and `log()`. Read `GET /v1/library` first for the exact function names.'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- script
properties:
script:
type: string
egress:
type: string
enum:
- default
- link
description: Optional. `link` sends every request of the run through your own Chrome (Bowmark Link) and fails with "Link not connected" when it is not open, never falling back to Bowmark's route. Any other value is a 400.
example:
script: const { offers } = await bowmark.pcparts.search("RTX 5080"); return offers.slice(0, 3);
responses:
'200':
description: 'The run was accepted. That includes a script that threw (`status: error`) or paused for a sign-in (`status: needs_user`).'
content:
application/json:
schema:
$ref: '#/components/schemas/RunEnvelope'
'400':
description: The body was malformed. `error` says what to send.
content:
application/json:
schema:
$ref: '#/components/schemas/RunEnvelope'
'401':
description: No API key, or a key that was refused.
content:
application/json:
schema:
$ref: '#/components/schemas/RunEnvelope'
'402':
description: The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.
content:
application/json:
schema:
$ref: '#/components/schemas/RunEnvelope'
'429':
description: Too many runs in flight on this account. Nothing was started or charged.
content:
application/json:
schema:
$ref: '#/components/schemas/RunEnvelope'
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait.
'503':
description: A failure on Bowmark's side. Retry.
content:
application/json:
schema:
$ref: '#/components/schemas/RunEnvelope'
tags:
- Run
components:
schemas:
RunEnvelope:
type: object
description: What a run returns. `status` says whether the SCRIPT succeeded. A script that threw or paused for a login is still HTTP 200. Branch on `status`, not on the HTTP code.
required:
- ok
- status
- result
- logs
- error
- ms
properties:
runId:
type: string
description: Stable id for this run. Quote it in a support or `report` message.
ok:
type: boolean
description: False only when the run produced nothing usable.
status:
type: string
enum:
- ok
- error
- partial
- needs_user
description: '`partial`: the result is real but some calls failed (see `incomplete`); `ok` stays true. `needs_user`: a person must sign in to a site first. Relay `meta.handoff.url` to them, then run again.'
egress:
type: string
enum:
- default
- link
description: 'The egress the run was given, present only when the request asked for one. `link`: every request went through the caller''s own Chrome (Bowmark Link).'
result:
description: Whatever the script `return`ed. Any JSON value.
logs:
type: array
items:
type: string
description: Lines the script wrote with `log(...)`.
error:
type:
- string
- 'null'
description: Why the run failed, in plain words. Null on success.
ms:
type: integer
description: How long the script itself ran, in milliseconds.
queuedMs:
type: integer
description: How long the run waited for a worker before starting. Present only when it was a second or more.
needs:
type: array
description: The sign-ins this script is waiting on. Present when `status` is `needs_user`.
items:
type: object
required:
- capability
- provider
- providerTitle
- kind
properties:
capability:
type: string
provider:
type: string
providerTitle:
type: string
description: The site's name, to show a person.
kind:
type: string
incomplete:
type: object
description: 'Present only when `status` is `partial`: which calls did not answer.'
properties:
summary:
type: string
totalCalls:
type: integer
additionalProperties: true
emptyHanded:
type: object
description: Present when the script returned nothing while its calls returned rows, usually a filter that matched none of the site's own labels. Lists the label values the calls actually returned.
additionalProperties: true
notes:
type: array
description: Caveats a call attached to a complete answer. Never changes `status`.
items:
type: object
properties:
path:
type: string
notes:
type: array
items:
type: string
meta:
type: object
properties:
handoff:
type: object
description: A single-use sign-in link for a person to open. Expires at `expiresAt`.
properties:
ref:
type: string
url:
type: string
format: uri
expiresAt:
type: string
format: date-time
concurrency:
type: object
description: 'On a 429: how many runs are in flight and when to retry.'
properties:
limit:
type: integer
inFlight:
type: integer
retryAfterSeconds:
type: integer
additionalProperties: true
notice:
type: object
description: Set when the account owner has not accepted the current Terms. Relay it to them.
additionalProperties: true
securitySchemes:
bearer:
type: http
scheme: bearer
description: Your Bowmark API key (`bmk_…`), from https://bowmark.ai/dashboard/keys.
apiKeyHeader:
type: apiKey
in: header
name: X-Bowmark-Key
description: The same key, for a client that cannot set `Authorization`.
externalDocs:
description: HTTP API guide
url: https://bowmark.ai/docs/api