Bintu Web Reader

Bintu Data Extraction API

Quickstart

1. Authenticate

Send your service key in the X-API-Key header. Do not put API keys in URLs.

$BaseUrl = "https://your-bintu-api.onrender.com"

$ApiKey = $env:BINTU_API_KEY

2. Extract readable text

$url = "https://example.com"

$response = Invoke-RestMethod -Method Get -Uri "$BaseUrl/api/v1/scrape/text?url=$([uri]::EscapeDataString($url))" ` -Headers @{ "X-API-Key" = $ApiKey }

$response.text $response.approx_tokens $response.truncated

The response includes text, an approximate token count, and truncated. If a page returns very little readable text, the response may include low_yield: true and a short yield_hint, such as a note that the page appears to require JavaScript.

3. Use MCP

MCP discovery (initialize, tools/list, ping) is available without a key. Tool execution requires either the scoped MCP_API_KEY or the master API_KEY, sent as X-API-Key or Authorization: Bearer.

$body = @{

jsonrpc = "2.0" id = 1 method = "tools/call" params = @{ name = "bintu_scrape_text" arguments = @{ url = "https://example.com" max_tokens = 2000 } } } | ConvertTo-Json -Depth 10

Invoke-RestMethod -Method Post -Uri "$BaseUrl/mcp" -Headers @{ "X-API-Key" = $ApiKey "Accept" = "application/json, text/event-stream" } -ContentType "application/json" ` -Body $body

What bintu_scrape_text does

Fetches one public HTTP or HTTPS URL and returns its readable text, sized for an LLM context window. Only HTML/XHTML pages up to 1 MiB are supported; PDF, JSON, images, and pages that require JavaScript are not. Article or main content is preferred; navigation, headers, footers, ads, and cookie banners are dropped; repeated story blocks are removed (deduplicated_count); links appear as label (url); code is returned in fenced blocks with indentation kept; tables are pipe-delimited.

When to use it

• You need readable, token-bounded text from a public web page for an LLM context window.
• You want chunks sized for a vector database (mode=chunk).
• You want a short leading extract within a budget (mode=summarize).
• You want cache-aware extraction with provenance and token economics.

Input parameters

| persist | boolean | true | Allow a fresh successful result to be written to the persistent cache. false skips that write.

Output envelope

Every successful call returns the same JSON envelope (in structuredContent and as JSON in content[0].text):

\* Provenance fields are additive and may be absent.

Error semantics

Tool execution failures are returned in-band with isError: true and a stable error object at structuredContent.error (code, message, optional hint, optional retryable, optional retry_with), with the same code and message in content[0].text.

Retry behavior

Only upstream_rate_limited is retryable (retryable=true, retry_with="retry_after_delay"). Wait for the indicated delay before retrying. All other errors are non-retryable; do not retry them unchanged.

Cache behavior

Results may be served from memory or persistent cache (cache_hit, cache_layer). Set cache=false to bypass cache reads; set persist=false to skip the persistent write. URLs with credential-like query parameters are never stored. robots.txt is honored.

Token economics

approx_tokens is ceil(characters / 4), an estimate, not a tokenizer count. tokens_saved_estimate is the source-HTML estimate minus the returned-text estimate. html_tokens reports the source size the same way. Use these fields to budget LLM context before and after extraction.

Rate limits

The service applies a per-process burst limit (60 requests per 60 seconds by default). A burst-limit response (429 burst_rate_limit_exceeded on REST; upstream_rate_limited on MCP) includes a Retry-After hint. Pause and retry after that delay; do not retry immediately.

Common responses

Bintu is a FastAPI-based API for extracting readable text from public HTML pages. It limits upstream responses to 1 MiB, accepts HTML/XHTML only, pins outbound connections to validated public IPs, and applies a 60-request per-minute process-local burst limit.

Live API

The service is live on Render and ready to test:

• Base URL: https://bintu-api.onrender.com
• OpenAPI docs: https://bintu-api.onrender.com/docs
• Health check: https://bintu-api.onrender.com/healthz

Health check

curl https://bintu-api.onrender.com/healthz

Example response:

{

"status": "ok" }

Scrape text

For direct access to the deployed service, set your API key in PowerShell. The secure prompt avoids echoing the key as you type:

$env:BINTU_BASE_URL = "https://bintu-api.onrender.com"

$secure = Read-Host "Paste your Render API_KEY" -AsSecureString $env:BINTU_API_KEY = [System.Net.NetworkCredential]::new("", $secure).Password Remove-Variable secure

Send an authenticated scrape request:

$target = "https://www.iana.org/domains/reserved"

$encodedUrl = [uri]::EscapeDataString($target) $headers = @{ "X-API-Key" = $env:BINTU_API_KEY }

try { $result = Invoke-RestMethod -Uri "$env:BINTU_BASE_URL/api/v1/scrape/text?url=$encodedUrl" -Headers $headers $result | ConvertTo-Json -Depth 5 } catch { $response = $_.Exception.Response if ($response) { $statusCode = [int]$response.StatusCode $retryAfter = $response.Headers["Retry-After"] Write-Host "HTTP $statusCode; Retry-After: $retryAfter" $reader = [System.IO.StreamReader]::new($response.GetResponseStream()) try { $reader.ReadToEnd() } finally { $reader.Dispose() } } else { throw } }

Successful response:

{

"url": "https://www.iana.org/domains/reserved", "text": "# IANA-managed Reserved Domains\n## Example domains\n...", "truncated": false }

truncated is true if the extracted text exceeded the configured character limit. The API returns the requested URL in url.

For curl.exe in PowerShell, the same request can be made with:

curl.exe --get "$env:BINTU_BASE_URL/api/v1/scrape/text" `

--data-urlencode "url=https://www.iana.org/domains/reserved" --header "X-API-Key: $env:BINTU_API_KEY" --header "Accept: application/json"

The Render API_KEY is available in the service's Environment settings. Keep it private, do not commit it, and do not put it in a URL. The examples above keep it in the current PowerShell process environment. If no API key or proxy secret is configured (as in the default local development setup), authentication is not required. Interactive API docs are available at /docs — click Authorize (top right) and paste the key into ApiKeyAuth, or the Supabase session token into BearerAuth for the mobile endpoint, then use Try it out on any locked route.

Scrape chunks

Use POST /api/v1/scrape/chunks when the extracted page needs to be divided into model-friendly, approximately token-budgeted pieces. This is useful for long articles, documentation, and retrieval workflows.

Set the API key as shown in Scrape text, then send:

$target = "https://www.iana.org/domains/reserved"

$body