API Reference

BlueWeb API Documentation

Extract structured data from any website with a single API call. Describe what you want in natural language and get clean JSON back.

Base URL

https://blueweb.ai/api/v1

Auth

Bearer bw_live_*

Format

JSON

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard.

http

Authorization: Bearer bw_live_xxxxxxxxxxxxxxxxxxxxxxxx

API access requires a Pro ($49/mo) or Scale ($99/mo) plan. Free and Starter plans can only use the dashboard. View pricing

Endpoints

POST/api/v1/extract

Submit a URL for data extraction. Returns immediately with a job ID. Extraction runs asynchronously — poll the result endpoint for completion.

Request Body

Parameter	Type	Description
`url`required	string	The web page URL to extract data from
`prompt`required	string	Natural language description of the data to extract

Response 202 Accepted

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "poll_url": "/api/v1/extractions/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Example

bash

curl -X POST https://blueweb.ai/api/v1/extract \
  -H "Authorization: Bearer bw_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com",
    "prompt": "Extract all post titles, points, and comment counts"
  }'

GET/api/v1/extractions/{id}

Retrieve extraction results by job ID. Poll this endpoint until status is "completed" or "failed".

Path Parameters

Parameter	Type	Description
`id`required	string	The extraction job ID

Response 200 OK

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://news.ycombinator.com",
  "prompt": "Extract all post titles, points, and comment counts",
  "status": "completed",
  "error": null,
  "data": [
    {
      "title": "Show HN: I built an open-source data pipeline",
      "points": 142,
      "comment_count": 58
    },
    {
      "title": "The SQLite Virtual Machine",
      "points": 89,
      "comment_count": 23
    }
  ],
  "fields": ["title", "points", "comment_count"],
  "pages_used": 1,
  "duration_ms": 3200,
  "created_at": "2026-02-25T12:00:00.000Z"
}

Status Values

Status	Description
`pending`	Job created, waiting to start
`processing`	Extraction in progress
`completed`	Data extracted successfully
`failed`	Extraction failed — check the `error` field

GET/api/v1/extractions

List your recent extractions, ordered by creation date (newest first).

Query Parameters

Parameter	Type	Description
`limit`	number	Results per page (max 100)(default: `20`)
`offset`	number	Number of results to skip(default: `0`)

Response 200 OK

json

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "url": "https://news.ycombinator.com",
      "prompt": "Extract all post titles, points, and comment counts",
      "status": "completed",
      "pageCount": 1,
      "durationMs": 3200,
      "createdAt": "2026-02-25T12:00:00.000Z"
    }
  ],
  "limit": 20,
  "offset": 0
}

Error Handling

All errors return a JSON object with an error field.

Status	Meaning	Example
400	Bad Request	{"error": "Invalid url"}
401	Unauthorized	{"error": "Invalid or missing API key"}
404	Not Found	{"error": "Extraction not found"}
429	Rate Limited	{"error": "Monthly page limit reached"}

Code Examples

JavaScript / TypeScript

typescript

const API_KEY = "bw_live_your_api_key";
const BASE = "https://blueweb.ai/api/v1";

// 1. Submit extraction
const { id } = await fetch(`${BASE}/extract`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/products",
    prompt: "Extract all product names and prices",
  }),
}).then(r => r.json());

// 2. Poll for results
let result;
do {
  await new Promise(r => setTimeout(r, 2000));
  result = await fetch(`${BASE}/extractions/${id}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  }).then(r => r.json());
} while (result.status === "processing" || result.status === "pending");

console.log(result.data);
// [{ product_name: "Widget Pro", price: "$29.99" }, ...]

Python

python

import requests, time

API_KEY = "bw_live_your_api_key"
BASE = "https://blueweb.ai/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. Submit extraction
job = requests.post(f"{BASE}/extract", headers=headers, json={
    "url": "https://example.com/products",
    "prompt": "Extract all product names and prices",
}).json()

# 2. Poll for results
while True:
    result = requests.get(f"{BASE}/extractions/{job['id']}", headers=headers).json()
    if result["status"] in ("completed", "failed"):
        break
    time.sleep(2)

print(result["data"])
# [{"product_name": "Widget Pro", "price": "$29.99"}, ...]

Usage & Limits

Each extraction consumes 1 page from your monthly allowance. Usage resets at the start of each calendar month.

Plan	Price	Pages/month	API Access
Free	$0	20	Dashboard only
Starter	$29/mo	2,000	Dashboard only
Pro	$49/mo	10,000	Yes
Scale	$99/mo	50,000	Yes

MCP Server

Use BlueWeb directly from AI assistants like Claude via our MCP server. Run it via npx and configure your AI assistant to use it.

bash

npx -y blueweb-mcp-server

Add to your Claude Desktop, Claude Code, or Cursor configuration:

json

{
  "mcpServers": {
    "blueweb": {
      "command": "npx",
      "args": ["-y", "blueweb-mcp-server"],
      "env": {
        "BLUEWEB_API_KEY": "bw_live_your_api_key"
      }
    }
  }
}

Ready to start extracting?

Create your free account and get 20 pages/month — no credit card required.

Get started free Generate API key