# ContentExtractAPI

> Convert webpages and HTML to clean Markdown, plain text, or structured JSON. Built for RAG ingestion, AI agents, docs pipelines, and content monitoring.

Free tool: https://contentextract-api.vercel.app — paste a URL, get Markdown. No login required for first conversions.

API: https://contentextract-api.vercel.app/api — create a free key (100 credits) and start converting.

MCP: https://contentextract-api.vercel.app/mcp — install via npx or configure Claude Desktop / Cursor directly.

## API Reference

### POST /api/convert

Convert one URL or paste raw HTML. Accepts JSON body with exactly one of:
- `url` (string, URI) — fetch and extract a public webpage
- `html` (string) — convert pasted HTML without a network request

Optional fields:
- `format` — "markdown" (default) | "text" | "json"
- `sourceUrl` — base URL for resolving relative links when using html mode

Authentication: pass API key as `Authorization: ce_your_key` header. Anonymous users get 5 conversions/day.

Returns:
```json
{
  "result": {
    "url": "https://example.com",
    "title": "Example Domain",
    "markdown": "# Example Domain\n\n...",
    "text": "Example Domain...",
    "json": { "title": "...", "headings": [], "links": [], "images": [], "text": "..." }
  },
  "output": "# Example Domain\n\n...",
  "usage": { "mode": "api_key", "usage": { "creditsRemaining": 99 } }
}
```

### POST /api/bulk

Convert 1–20 URLs at once.

Body: `{ "urls": ["https://example.com", "https://..."] }`

Returns: `{ "jobId": "uuid", "status": "complete", "results": [...] }`

### GET /api/jobs/:id

Retrieve a completed bulk job by ID.

### GET /api/usage

Returns anonymous daily usage or API-key credit balance.

### POST /api/keys

Create a free-tier API key (100 credits). Body: `{ "label": "my agent" }`

Returns the raw key once: `{ "key": "ce_...", "record": { "plan": "free", "creditsRemaining": 100 } }`

## Quickstart

```bash
# 1. Create a free API key
curl -X POST https://contentextract-api.vercel.app/api/keys \
  -H "content-type: application/json" \
  -d '{"label":"my agent"}'

# 2. Convert a webpage to Markdown
curl -X POST https://contentextract-api.vercel.app/api/convert \
  -H "authorization: ce_your_key" \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com","format":"markdown"}'
```

## MCP Setup (Claude Desktop / Cursor)

Install: `npx contentextract-mcp`

Config (~/.claude/claude_desktop_config.json or ~/.cursor/mcp.json):
```json
{
  "mcpServers": {
    "contentextractapi": {
      "command": "npx",
      "args": ["-y", "contentextract-mcp"],
      "env": { "CONTENTEXTRACT_API_KEY": "ce_your_key" }
    }
  }
}
```

Tools exposed: convert_webpage, convert_html, bulk_convert