Integration Paths

Choose how DataBlue fits your runtime: Playground, REST, Python, Node.js, or MCP.

Which Surface Should You Use?

Surface	Choose it when	Avoid it when
Playground	You are exploring options, comparing formats, or reproducing a request manually	The workflow must run unattended in production
REST API	You want complete HTTP control or use a language without an official SDK	You would otherwise rebuild SDK concerns such as models, retries, and job polling
Python SDK	You use Python, FastAPI, Django, notebooks, ETL, RAG, or data pipelines	Your runtime cannot install Python packages
Node SDK	You use Node.js 18+, TypeScript, serverless functions, or JavaScript backends	You need a synchronous client
MCP server	An AI agent should discover and call DataBlue through explicit tools	You need low-level control inside a conventional application request path

Playground

Use the Playground to test a source and compare outputs before writing code.

Open the DataBlue Playground.
Start with Scrape and https://example.com.
Select markdown, links, and images.
Run the request and inspect Response, Metadata, and each requested output tab.
Use the generated-code action to translate the successful configuration into application code.

Use the Playground to learn and reproduce. Use REST, an SDK, or MCP for repeatable automation.

REST API

REST is the portable contract. Every request uses HTTPS, JSON, and the Bearer credential described in Authentication.

Example

curl --fail-with-body --silent --show-error \
  -X POST "https://api.datablue.dev/v1/scrape" \
  -H "Authorization: Bearer $DATABLUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown", "links"]
  }' | jq .

REST gives you direct control over

HTTP timeouts, connection pooling, and retry policy.
Request and response logging with your own redaction rules.
Job polling cadence, cancellation, pagination, and webhook ingestion.
Any programming language capable of sending HTTPS requests.

Python SDK

Install datablue==2.1.0 on Python 3.10+. It includes sync and async clients with typed models.

Example

python -m pip install "datablue==2.1.0"

Example

import os
from datablue import DataBlue

with DataBlue(api_key=os.environ["DATABLUE_API_KEY"]) as client:
    result = client.scrape(
        "https://example.com",
        formats=["markdown", "links"],
    )
    print(result.data.markdown)

Async Python

Example

import os
from datablue import AsyncDataBlue

async with AsyncDataBlue(api_key=os.environ["DATABLUE_API_KEY"]) as client:
    result = await client.scrape(
        "https://example.com",
        formats=["markdown", "links"],
    )
    print(result.data.markdown)

Continue with Python SDK for configuration, models, jobs, errors, and Data API helpers.

Node.js and TypeScript SDK

The official package is @datablue/sdk@1.0.0 and requires Node.js 18 or newer. The client is typed and asynchronous.

Example

npm install "@datablue/sdk@1.0.0"

Example

import { DataBlue } from "@datablue/sdk";

const client = new DataBlue({
  apiKey: process.env.DATABLUE_API_KEY,
});

const result = await client.scrape("https://example.com", {
  formats: ["markdown", "links"],
});

console.log(result.data?.markdown);

Continue with Node SDK for typed options, job methods, error classes, and Data API helpers.

MCP Server for AI Agents

@datablue/mcp runs locally over stdio on Node.js 18+. It reads the API key from the environment.

Example

DATABLUE_API_KEY="wh_your_api_key" \
  npx --yes --prefer-online @datablue/mcp@latest

Codex

Example

codex mcp add datablue \
  --env DATABLUE_API_KEY=<your-key> \
  -- npx --yes --prefer-online @datablue/mcp@latest

Claude Code

Example

claude mcp add --transport stdio datablue \
  --env DATABLUE_API_KEY=<your-key> \
  -- npx --yes --prefer-online @datablue/mcp@latest

Standard MCP JSON configuration

Example

{
  "mcpServers": {
    "datablue": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "@datablue/mcp@latest"],
      "env": {
        "DATABLUE_API_KEY": "<your-key>"
      }
    }
  }
}

Shipped MCP tools

Tool	Purpose
`datablue_search_google`	Search live Google results through DataBlue SERP
`datablue_scrape_url`	Scrape one public URL with selected formats
`datablue_batch_scrape`	Scrape up to 20 explicit URLs with shared options
`datablue_extract`	Extract structured facts from one or more URLs
`datablue_map_site`	Discover URLs from a site
`datablue_start_crawl`	Start a bounded asynchronous crawl
`datablue_get_job_status`	Check a crawl or search job
`datablue_list_data_apis`	List docs-ready Data APIs with current parameters and available weights
`datablue_run_data_api`	Run one API returned by the catalog tool

Continue with MCP Server for resources, prompts, guards, complete configuration, and troubleshooting.

Capability Matrix

Capability	Playground	REST	Python	Node	MCP
Scrape	Yes	Yes	`scrape()`	`scrape()`	`datablue_scrape_url`
Crawl	Yes	Job API	Blocking or manual job	Blocking or manual job	Start and status tools
Search	Yes	Job API	Blocking or manual job	Blocking or manual job	Google search tool
Map	Yes	Yes	`map()`	`mapUrl()`	`datablue_map_site`
Extract	Yes	Yes	`extract()`	`extract()`	`datablue_extract`
Data APIs	Endpoint-specific	Endpoint-specific	Named and generic helpers	Named and generic helpers	Catalog and runner tools
Webhooks	Request options	Yes	Selected job methods	Selected job methods	Not the primary agent workflow

A Practical Adoption Path

Prove the output in the Playground.
Reproduce the request with curl so the HTTP contract is understood.
Move into Python or Node if an official SDK matches your runtime.
Add bounded jobs, structured errors, storage, and observability.
Add MCP separately when an agent needs controlled access to the same platform.