# Parse API

> Turn any website into a structured API with a single request.

Parse lets AI agents and developers create, manage, and call web scraping APIs programmatically.

## Product updates

- Changelog: https://parse.bot/changelog

## Industry solutions

Parse turns repeatable web workflows into deterministic, low-latency APIs for specific industries:

- Ecommerce and price aggregation: https://parse.bot/industries/ecommerce
- Shipping and logistics: https://parse.bot/industries/shipping-logistics
- Healthcare operations and legacy portals: https://parse.bot/industries/healthcare
- Real estate and property data: https://parse.bot/industries/real-estate
- Travel and hospitality: https://parse.bot/industries/travel-hospitality
- Financial services and insurance: https://parse.bot/industries/financial-services
- Recruiting and job data: https://parse.bot/industries/recruiting-job-data
- AI agents and MCP assistants: https://parse.bot/industries/ai-agents

## Product comparisons

Parse is intentionally narrower than a generic web fetcher or cloud browser. It is designed for known, recurring workflows that benefit from a typed contract, direct network execution, and automatic maintenance.

- Parse vs Firecrawl: https://parse.bot/compare/firecrawl
- Parse vs Browserbase: https://parse.bot/compare/browserbase
- Comparison overview: https://parse.bot/compare

## Reliability & self-healing

Parse APIs are managed and monitored — not raw scrapers you maintain. What this means for an agent deciding whether to use one:

- **Automatically tested.** Every endpoint is health-checked on a schedule with test probes. Each marketplace API exposes a real "last verified" timestamp and recent check results.
- **Self-healing.** When a source site changes and a check fails, the API is automatically queued for repair and re-verified. Marketplace APIs are shared, so a fix reaches everyone using it.
- **Fixable on demand — by you or your agent.** Every API stays attached to the agent that built it. If you need a new endpoint, a new field, or a fix, describe it in plain English via the `revise_api` MCP tool (or the revise box on the API page) and it rebuilds against the live site in minutes. You do not have to wait for Parse to add a site or a route — the tool does it.
- **Self-documenting errors.** A call to a missing or changed endpoint returns a clean status with the list of available endpoints and a repair hint, so an agent can recover or trigger a fix instead of failing.

These APIs are independent, maintained REST wrappers over public data — where a site has no official API (or only a limited one), Parse gives a stable, monitored contract over it and keeps it working as the site changes.

## Marketplace catalog

Looking for a ready-made API for a specific site (Zillow, LinkedIn, etc.) instead of building one? Browse the marketplace:

- Catalog page: https://parse.bot/marketplace
- Machine-readable index of every listed API: https://parse.bot/marketplace/llms.txt
- Browse by category: https://parse.bot/marketplace (chip filter at the top of the page)

## Base URL

https://api.parse.bot

## Authentication

Two options:

1. **OAuth 2.1 (recommended)** — just set the URL. Your MCP client opens a browser for login. No API key needed.
2. **API Key** — pass `X-API-Key` header. Get your key at https://parse.bot/settings.

## MCP Server

The fastest way to use Parse from an AI agent. Connect any MCP-compatible client (Claude Code, Cursor, etc.) and get full API management + all your endpoints as callable tools.

POST https://api.parse.bot/mcp

### Option 1: OAuth (recommended)
{
  "mcpServers": {
    "parse": {
      "url": "https://api.parse.bot/mcp"
    }
  }
}

### Option 2: API Key
{
  "mcpServers": {
    "parse": {
      "url": "https://api.parse.bot/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

### OAuth Discovery
- Protected Resource Metadata: https://api.parse.bot/.well-known/oauth-protected-resource
- Authorization Server Metadata: https://api.parse.bot/.well-known/oauth-authorization-server

### MCP Tools Available

Platform tools (always available):
- create_api: Create a new API from a URL + optional task description
- list_apis: List all your APIs with optional status filter
- get_api: Get full details for an API by task_id, including a spec_url for its complete OpenAPI document
- revise_api: Modify a completed API with natural language instructions
- call_endpoint: Call any endpoint by scraper_id + endpoint_name + params

Endpoint tools (dynamic, generated from your completed APIs):
- Each completed API's endpoints are exposed as individual tools
- Named as {api_slug}__{endpoint_name}
- Call them directly with the endpoint's parameters

## Python SDK

Typed Python clients generated by the `parse` CLI — the same contract as REST/MCP, with autocomplete and typed responses. Managed with uv; run inside a uv project (`uv init` first if there's no pyproject.toml). Install:

uv add parse-sdk
uv run parse login --api-key YOUR_KEY          # non-interactive auth (CI/agents); bare `parse login` opens browser OAuth, `--no-web` to paste a key
uv run parse init                              # one-time: scaffold parse_apis + first sync (non-interactive once creds exist)
uv run parse add --marketplace <slug|id|url>   # pull a pinned marketplace API's typed client
uv run parse add <account-slug>                # or one of your own APIs

Use it:
from parse_apis.<slug> import <ApiClass>
client = <ApiClass>()
client.<resource>.<method>(...)          # typed args + typed responses
# run it in the project env: uv run python app.py

`uv run parse add --marketplace` pins a snapshot of the shared canonical (won't change underneath you; `--version N` to pick a release). Repos declare what they need in a committed `[tool.parse]` table in pyproject.toml; `uv run parse sync` reconciles the generated `parse_apis` package to it (`uv run parse sync --check` reports drift in CI). `uv run parse doctor` self-diagnoses install/auth issues.

Full SDK guide: https://docs.parse.bot/sdk

## REST API

### Quick Start

1. Create an API: `POST /dispatch` with `{"url": "https://example.com", "task": "get product prices"}`
2. Poll status: `GET /dispatch/tasks/{task_id}` until `status` is `completed`
3. Call endpoints: `POST /scraper/{scraper_id}/{endpoint_name}` with parameters from the spec

### Create an API
POST /dispatch
Body: {"url": "https://...", "task": "optional description of data needed"}
Returns: {"task_id": "...", "matched": true/false}
- matched=true: existing API found, ready immediately
- matched=false: build job queued, poll until completed

### List Your APIs
GET /dispatch/tasks?status=completed&limit=50&offset=0

### Get API Details
GET /dispatch/tasks/{task_id}
Returns full spec with `generated_api.endpoints[]` containing method, endpoint_name, input_params, return_schema, and execution_base_url.

### Execute an Endpoint
POST /scraper/{scraper_id}/{endpoint_name}
Body: endpoint parameters as JSON
Header: X-API-Key

### Revise an API
POST /dispatch/tasks/{task_id}/revise
Body: {"revision": "add search by category"}

### Fetch OpenAPI 3.1
GET /v1/apis/{scraper_id}/openapi.json
Optional: ?version=N to pin an available version
Header: X-API-Key

### Export as MCP Tools
GET /dispatch/tasks/{task_id}/export/mcp

## OpenAPI Spec

Full OpenAPI 3.1 specification: https://api.parse.bot/openapi.json

## Documentation

https://docs.parse.bot