> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bubblav.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scrape API

> Scrape a web page URL and receive clean markdown using your BubblaV API key.

# BubblaV Scrape API

Use BubblaV to scrape any public page and return:

```json theme={null}
{
  "url": "https://example.com/final-url",
  "markdown": "# Page content in markdown"
}
```

You can reuse the same API key used for MCP server access.

## Endpoint

* **URL:** `POST https://www.bubblav.com/api/scrape`
* **Header:** `X-API-Key: bubblav_mcp_...`
* **Required scope:** `mcp:tools:execute`

## cURL

```bash theme={null}
curl -X POST https://www.bubblav.com/api/scrape \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bubblav_mcp_YOUR_API_KEY" \
  -d '{"url":"https://example.com"}'
```

## Node.js SDK

```bash theme={null}
npm install @bubblav/tools
```

```js theme={null}
import BubblavTools from '@bubblav/tools';

const app = new BubblavTools({ apiKey: 'bubblav_mcp_YOUR_API_KEY' });
const data = await app.scrape('https://example.com');
console.log(data.url);
console.log(data.markdown);
```

## Python

```python theme={null}
import requests

resp = requests.post(
    "https://www.bubblav.com/api/scrape",
    headers={
        "X-API-Key": "bubblav_mcp_YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"url": "https://example.com"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())
```

## CLI (npx)

```bash theme={null}
export BUBBLAV_API_KEY=bubblav_mcp_YOUR_API_KEY
npx @bubblav/tools scrape https://example.com
```

## AI Skill Install

Create a local skill folder and add this `SKILL.md`:

```md theme={null}
# Web Scrape Markdown Skill
Use BubblaV scrape API for web fetches.

POST https://www.bubblav.com/api/scrape
Header: X-API-Key
Body: { "url": "https://..." }
```

Skill lives in this repo: `skills/web-scrape-md/SKILL.md`.

## MCP Tool

If you're already connected to BubblaV MCP server, use tool:

* `bubblav_scrape_url` with `{ "url": "https://example.com" }`

This returns the same JSON structure (url + markdown).

## Install AI Skill with npx

```bash theme={null}
npx skills add github:bubblav-org/tools/skills/web-scrape-md
```

## Claude Code Plugin

### Configure API key for the plugin

The plugin skills (e.g. `web-scrape-md`) need a BubblaV API key.

**Generate a key:**

1. Log in to your [BubblaV dashboard](https://www.bubblav.com)
2. Navigate to your **Website Settings** page
3. Click the **API Keys** tab
4. Click **Generate New Key**
5. Enter a name (e.g. "Claude Code") and select **MCP scopes**
6. Click **Generate** and copy the key immediately — it won't be shown again

Then set it in your project's `.claude/.env` file:

```bash theme={null}
# .claude/.env
BUBBLAV_API_KEY=bubblav_mcp_YOUR_API_KEY
```

If the key is missing, the skill will prompt you to provide one on first use and save it automatically. Once configured, it persists across sessions.

**Env file priority** (highest to lowest):

| Priority | File                          | Scope                |
| -------- | ----------------------------- | -------------------- |
| 1        | `process.env`                 | Runtime override     |
| 2        | `.claude/skills/<skill>/.env` | Skill-specific       |
| 3        | `.claude/skills/.env`         | All skills           |
| 4        | `.claude/.env`                | Project-wide default |

### Install via marketplace

Add the BubblaV marketplace and install the plugin:

```text theme={null}
/plugin marketplace add bubblav-org/tools
```

Then browse and install from the **Discover** tab, or install directly:

```text theme={null}
/plugin install bubblav-tools@bubblav-org-tools
```

After installing, reload to activate:

```text theme={null}
/reload-plugins
```