Search the web
Results from a web search provider (Brave Search API): title, URL, snippet, and the page's date and site name when known. With fetch, the top pages also come back as Markdown, opened like /v1/fetch in a real browser inside a sandbox; one page failing never fails the search. The same search by the same project within an hour is answered from the cache (cached: true) and not counted. Each other search counts against the plan's searchesPerMonth; beyond it the plan's extraSearchesPer1000Usd applies, and a plan without one (Free) answers 402 plan_limit until the 1st (UTC). The query text and options are sent to Brave with the platform's own key, nothing about the caller; the query text is kept 30 days. 60 per minute per project; every page fetch opens also counts against the fetch/screenshot/pdf limit.
POST
/v1/searchRequest
| Method and path | POST/v1/search |
|---|---|
| Base URL | https://api.boxline.dev |
| Authentication | Your API key in the x-api-key header (or Authorization: Bearer). The examples read it from BOXLINE_API_KEY. |
| Rate limit | Yes. See Rate limits for the numbers and headers. |
Body
JSON with content-type: application/json. Required.
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
queryrequired | string | – | – | What to search for (at most 75 words). Search operators work: quotes, -word, site:example.com, filetype:pdf. 1 to 400 characters. |
limit | integer | 10 | – | From 1 to 20. |
country | string | – | – | Where the results come from (case-insensitive): AR AU AT BE BR CA CL DK FI FR DE GR HK IN ID IT JP KR MY MX NL NZ NO CN PL PT PH RU SA ZA ES SE CH TW TR GB US, or ALL. UK means GB. Default US. |
language | string | – | – | The language of the results (case-insensitive): ar eu bn bg ca zh-hans zh-hant hr cs da nl en en-gb et fi fr gl de el gu he hi hu is it ja jp kn ko lv lt ms ml mr nb pl pt-br pt-pt pa ro ru sr sk sl es sv ta te th tr uk vi. A region is dropped when the language alone is listed (de-AT is de); zh-CN is zh-hans, zh-TW zh-hant, no nb. Default en. |
recency | string | – | day, week, month, year | Only pages published or changed in the last day |
safeSearch | string | moderate | off, moderate, strict | |
fetch | boolean | integer | false | – | Also open the top pages and return them as Markdown: true = the top 3, or a number from 0 to 5. Needs the plan's quick APIs. |
proxy | object | – | – | For the pages fetch opens only (the search itself never goes through it); needs fetch. |
More examples:
{"query":"playwright connect over cdp","limit":5,"fetch":2}curl -X POST "https://api.boxline.dev/v1/search" \ -H "x-api-key: $BOXLINE_API_KEY" \ -H "content-type: application/json" \ -d '{"query": "best trail running shoes"}'import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst { results, cached } = await bx.search({ query: "best trail running shoes" });for (const r of results) console.log(r.title, r.url, r.content?.length ?? "");console.log("from the cache:", cached);from boxline import Boxlinebx = Boxline() # reads BOXLINE_API_KEY and BOXLINE_API_URLfound = bx.search("best trail running shoes")for r in found["results"]: print(r["title"], r["url"], len(r.get("content") or ""))print("from the cache:", found["cached"])boxline search "best trail running shoes"Responses
200 OK
The results.
Headers
RateLimit-Limit: Requests allowed in the current window of this route's limit. (Rate limits)RateLimit-Remaining: Requests left in the current window. (Rate limits)RateLimit-Reset: Seconds until the window starts again. (Rate limits)
Fields
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
query | string | – | – | The query as searched (white space collapsed). |
results | object[] | – | – | |
results[].title | string | – | – | |
results[].url | string | – | – | An http(s) URL. |
results[].snippet | string | – | – | Plain text. |
results[].publishedAt | string | – | – | When the page was published or last changed. Format: date-time. |
results[].siteName | string | – | – | The site's name, e.g. "GitHub", when known. |
results[].content | string | null | – | – | Fetched results only: the page as Markdown, or null when it could not be loaded. |
results[].page | object | null | – | – | Fetched results only; null when the page could not be loaded. |
results[].page.finalUrl | string | – | – | |
results[].page.status | integer | null | – | – | |
results[].page.title | string | – | – | |
results[].page.captcha | string | null | – | recaptcha, hcaptcha, turnstile, cloudflare, datadome, arkose, human | |
results[].page.ms | integer | – | – | |
results[].error | object | null | – | – | Fetched results only; null when the page loaded. |
results[].error.code | string | – | – | |
results[].error.message | string | – | – | |
ms | integer | – | – | The whole request |
cached | boolean | – | – | Answered from this project's cache (the same search within the last hour); not counted. |
{ "query": "playwright connect over cdp", "cached": false, "ms": 412, "results": [ { "title": "BrowserType | Playwright", "url": "https://playwright.dev/docs/api/class-browsertype", "snippet": "A CDP websocket endpoint or http url to connect to.", "siteName": "Playwright" }, { "title": "Connecting Playwright to an Existing Browser | BrowserStack", "url": "https://www.browserstack.com/guide/playwright-connect-to-existing-browser", "snippet": "Playwright can connect directly to an existing Chromium instance via CDP.", "publishedAt": "2025-12-23T09:55:22.000Z", "siteName": "BrowserStack" } ]}Errors
Errors have a matching HTTP status and the same body. code is stable, so check it in your code; message is for people. See Errors and request ids.
| Status | Codes | When |
|---|---|---|
| 400 Bad Request | invalid_request, invalid_json, invalid_cursor, invalid_idempotency_key, invalid_extension, variables_with_extensions, terms_not_accepted, invalid_reset_token, invalid_confirmation_code, wrong_password, no_password, invalid_next, invalid_oauth_token | The request is not valid. |
| 401 Unauthorized | unauthorized | Missing or invalid API key. |
| 402 Payment Required | feature_not_in_plan, spend_limit, out_of_credit, plan_limit, spend_limit, out_of_credit, organization, project, plan, credit | The plan does not include this, a monthly allowance or spending limit is used up, the organization has no credit left, or the plan allows no more of this. spend_limit and out_of_credit carry error.details.limit: organization, project, plan or credit. |
| 429 Too Many Requests | rate_limited, concurrency_limit | Too many requests, or the organization's concurrent sessions (its plan's) or the project's concurrencyCap are in use. |
| 503 Service Unavailable | no_capacity, proxy_unavailable, provider_unavailable, search_unavailable, webhooks_unavailable, mail_unavailable, browser_unreachable | No machine free in time, proxies not set up, the model provider is not configured or has no key, or web search is not set up or its provider is not answering, or webhook delivery is not set up, or an email cannot be sent, or the session's browser did not answer in time. |
{ "error": { "code": "not_found", "message": "session not found", "requestId": "req_4fJx0aQm2Lk9Pz7N" }}Learn more
These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.