Extract

POST /v1/extract fetches one or more URLs and returns clean markdown. Handles HTML, PDF, DOCX, and SPA hydration; auto-escalates to a real Chrome render when needed.

Quick example

from brime import Brime

client = Brime()
result = client.extract(urls=[
    "https://example.com",
    "https://en.wikipedia.org/wiki/Generative_artificial_intelligence",
])

for r in result.results:
    print(r.url, r.method, r.content_type, len(r.markdown))
for f in result.failed:
    print("FAIL", f.url, f.error.code, f.error.message)

import { Brime } from "@brime-ai/brime";

const client = new Brime();
const result = await client.extract({
  urls: ["https://example.com", "https://en.wikipedia.org/wiki/Generative_artificial_intelligence"],
});

for (const r of result.results) {
  console.log(r.url, r.method, r.content_type, r.markdown.length);
}
for (const f of result.failed) {
  console.log("FAIL", f.url, f.error.code, f.error.message);
}

curl https://api.brime.dev/v1/extract \
  -H "Authorization: Bearer $BRIME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com", "https://en.wikipedia.org/wiki/Generative_artificial_intelligence"]}'

Request

Headers

Response

{
  "results": [
    {
      "url": "https://example.com",
      "markdown": "# Example Domain\n\nThis domain is for use in...",
      "method": "worker_static",
      "content_type": "html",
      "status": 200,
      "latency_ms": 312,
      "metadata": {
        "title": "Example Domain",
        "description": null,
        "author": null,
        "published_date": null,
        "canonical": "https://example.com/",
        "og_image": null,
        "language": "en"
      }
    }
  ],
  "failed": [
    {
      "url": "https://blocked.example.com",
      "error": {
        "code": "bot_challenge",
        "message": "Bot challenge detected; browser tier also failed",
        "needs_browser": false
      }
    }
  ],
  "request_id": "req_01J...",
  "credits_used": 2,
  "latency_ms": 1845
}

Result fields

metadata block

Always an object when present; each sub-field is a non-empty string or null. The block reflects what the engine could derive from the page; DOCX results always have all-null metadata.

Tier dispatch

The browser tier auto-escalates when:

• A bot challenge is detected (Cloudflare, hCaptcha, DataDome, etc.).
• A single-page app returned no content after static hydration.
• A static fetch returned a non-2xx status.

Pricing is 1 credit per deduped input URL regardless of tier — Chrome escalations are not surcharged. See pricing.

failed[].error.code

Smart-clean

The HTML → markdown pipeline runs a deterministic readability-style pre-processor by default. Six phases:

1. DOM parse (linkedom).
2. Noise selector strip — <script> / <style> / <nav> / <footer> / <aside>, cookie banners, ad containers, framework chrome (Wikipedia sidebars, etc.).
3. Semantic content cascade (<article> / <main> / [role="main"] priority, multi-container merge for CMS pages).
4. Density-scoring fallback when the cascade returns empty.
5. htmd_wasm HTML→markdown conversion.
6. Markdown post-process: CMS template tokens stripped, AEM UUID content-references removed, inline citations ([1], [1,2]) trimmed, "References" / "See also" section-cutoff.

Pass clean: false to opt out — you'll get the pre-refactor pipeline (regex strip → htmd, no post-process). Same response shape, lower latency (~180 ms faster on average), but noisier output. Use it for A/B testing or when smart-clean over-trims a specific site.

Smart-clean applies to both worker_static and chrome_render paths. PDF, DOCX, and hydration outputs are unaffected.

Edge cases

• Mixed success: a request with 5 URLs may return 4 in results and 1 in failed. The 200 status applies to the request as a whole; per-URL outcomes live in those arrays.
• Idempotent retries: if you re-send with the same Idempotency-Key within 24 h, you get the cached response and pay nothing.
• Empty urls: 400 invalid_request.
• More than 10 URLs: 400 invalid_request.
• chrome_render thin output: A successful Chrome render that yields fewer than 100 characters is demoted to failed[] with code: "render_failed" rather than returned as an empty results[] entry.

Errors