# Diffbot — how to use (mcp.ai)

Connect your Diffbot account and use 35 tools for artificial intelligence straight from your AI agent. Connect with your own API key. Diffbot provides AI-powered tools to extract and structure data from web pages, transforming unstructured web content into structured, linked data.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_diffbot?ms=1787291460000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `diffbot_combine_entity_profiles`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/diffbot`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/diffbot/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/diffbot/combine/entity/profiles` — Combine multiple entity profiles into a unified view using the Diffbot Knowledge Graph. Returns enhanced person or organization data by matching on identifying attributes like name, email, employer, o
  - body: { ip?: string, url?: string[], name?: string[], type?: string, email?: string, phone?: string, title?: string, filter?: string, school?: string, search?: boolean, refresh?: boolean, customId?: string, employer?: string, jsonmode?: string, location?: string, threshold?: number, filterExclude?: string, nonCanonicalFacts?: boolean }
- `POST https://api.mcp.ai/api/diffbot/create/bulk` — Tool to submit a bulk extract job to process multiple URLs with Extract APIs. Use when you need to process many URLs asynchronously using any Extract API. The job will process URLs in the background a
  - body: { name: string, urls: string, apiUrl: string, notifyEmail?: string, notifyWebhook?: string }
- `POST https://api.mcp.ai/api/diffbot/create/custom/api` — Tool to create or update the parameters and ruleset of a Custom API. Use this when you need to define custom extraction rules for specific websites that require tailored parsing logic beyond standard 
  - body: { api: string, notes?: string[], rules?: object[], testUrl?: string, useProxy?: string, prefilters?: string[], urlPattern: string, renderOptions?: string, xForwardHeaders?: object }
- `POST https://api.mcp.ai/api/diffbot/create/kg/bulk/enhance` — Tool to submit a bulk enhance job to enrich multiple entities asynchronously. Use when you need to process many Person or Organization records in batch. The API accepts entity descriptions and returns
  - body: { name?: string, size?: integer, search?: boolean, refresh?: boolean, entities: object[], jsonmode?: string, threshold?: number, webhookurl?: string, nonCanonicalFacts?: boolean }
- `POST https://api.mcp.ai/api/diffbot/delete/custom/api` — Tool to delete custom API definitions for a given URL pattern. Removes custom extraction rules from your account. Use when you need to remove previously configured custom APIs.
  - body: { api: string, urlPattern: string }
- `POST https://api.mcp.ai/api/diffbot/delete/kg/enhance/bulkjob` — Tool to delete an Enhance Bulkjob. Removes the bulk job and its results from the system. Use when cleaning up completed or failed jobs.
  - body: { bulkjobId: string }
- `POST https://api.mcp.ai/api/diffbot/download/bulk/results` — Tool to download results of a bulk enhance job with filtering options via POST request. Use this to retrieve processed results from a completed or running bulk job. Supports multiple export formats (j
  - body: { from?: integer, head?: integer, size?: integer, wait?: integer, filter?: string, format?: string, bulkjobId: string, exportfile?: string, exportspec?: string, exportquery?: boolean, onlyMatches?: boolean, filterExclude?: string, exportseparator?: string }
- `POST https://api.mcp.ai/api/diffbot/enhance/entity` — Enrich a person or organization with comprehensive data from the Diffbot Knowledge Graph. Provide identifiers like name, email, employer, or URL and receive detailed entity information including emplo
  - body: { id?: string, ip?: string, url?: string[], name?: string[], size?: integer, type?: string, email?: string[], phone?: string, title?: string, filter?: string, school?: string, search?: boolean, refresh?: boolean, customId?: string, employer?: string, jsonmode?: string, location?: string, threshold?: number, description?: string, filterExclude?: string, nonCanonicalFacts?: boolean }
- `POST https://api.mcp.ai/api/diffbot/extract/job` — Tool to extract structured job posting data from job listing pages. Returns job title, company, location, salary, requirements, skills, and other job-related information. Use when you need to parse an
  - body: { url: string, proxy?: string, fields?: string, timeout?: integer, useProxy?: string, proxyAuth?: string }
- `POST https://api.mcp.ai/api/diffbot/extract/list` — Tool to extract structured data from list-style pages like news indexes, product listings, and directory pages. Returns an array of items with their titles, links, and descriptions. Use when you need 
  - body: { url: string, proxy?: string, fields?: string, timeout?: integer, useProxy?: string, proxyAuth?: string }
- `POST https://api.mcp.ai/api/diffbot/get/account` — Retrieves comprehensive Diffbot account information including subscription plan details, credit balance, usage history, and account status. Returns account holder name, email, current plan, available 
- `POST https://api.mcp.ai/api/diffbot/get/analyze` — Automatically analyzes a web page to determine its type and extract structured data. The Analyze API intelligently classifies pages into types (article, product, discussion, image, video, organization
  - body: { url: string, mode?: string, fields?: string, timeout?: integer, fallback?: string, discussion?: boolean }
- `POST https://api.mcp.ai/api/diffbot/get/article` — Tool to extract information from articles, including authors, publication dates, and images. Use when you need structured metadata from a web article URL.
  - body: { url: string, mode?: string, stats?: boolean, fields?: string[]|string, paging?: string, timeout?: integer, discussion?: boolean }
- `POST https://api.mcp.ai/api/diffbot/get/bulk/data` — Tool to download extracted results from a completed bulk job. Use after a bulk job has finished processing to retrieve the data. Supports JSON and CSV formats.
  - body: { num?: integer, name: string, type?: string, format?: string }
- `POST https://api.mcp.ai/api/diffbot/get/bulk/job/status` — Tool to poll the status of a specific Diffbot Knowledge Graph Enhance bulk job. Use when you need to check the progress, completion status, or details of a bulk enhancement job.
  - body: { bulkjobId: string }
- `POST https://api.mcp.ai/api/diffbot/get/bulk/results` — Tool to download the results of a completed Enhance Bulkjob. Returns enriched records from the bulk job. Use after a bulk enhance job has completed processing.
  - body: { from?: integer, head?: integer, size?: integer, wait?: integer, filter?: string, format?: string, bulkjobId: string, exportfile?: string, exportspec?: string, exportquery?: string, onlyMatches?: string, filterExclude?: string, exportseparator?: string }
- `POST https://api.mcp.ai/api/diffbot/get/bulk/single/result` — Tool to download the result of a single job within a Diffbot bulk enhance job. Returns enriched entity data for a specific input record by its index. Use after a bulk enhance job has completed to retr
  - body: { job_idx: integer, bulkjob_id: string }
- `POST https://api.mcp.ai/api/diffbot/get/crawl/data` — Download extracted results from a completed crawl job. Returns all structured data extracted during crawl processing (articles, products, etc.). Use after a crawl job has completed to retrieve the col
  - body: { num?: integer, name: string, format?: string }
- `POST https://api.mcp.ai/api/diffbot/get/discussion` — Extract structured discussion threads from web pages including forums, comment sections, product reviews, Reddit discussions, and blog comments. Returns posts with author info, timestamps, content, an
  - body: { url: string, fields?: string, timeout?: integer, maxPages?: integer|string, norender?: boolean, discussion?: boolean }
- `POST https://api.mcp.ai/api/diffbot/get/event` — Tool to extract event details from web pages. Use when you need structured event data such as venue, date, and description.
  - body: { url: string, fields?: string, paging?: boolean, timeout?: integer }
- `POST https://api.mcp.ai/api/diffbot/get/image` — Tool to extract detailed information about images, including dimensions and recognition data. Use after confirming the image URL is publicly accessible.
  - body: { url: string, fields?: string[]|string, paging?: boolean, timeout?: integer }
- `POST https://api.mcp.ai/api/diffbot/get/kg/coverage/report/by/id` — Download Knowledge Graph coverage report by report ID. Returns detailed CSV coverage statistics showing field presence across query results. Use this after generating a coverage report from a DQL quer
  - body: { id: string }
- `POST https://api.mcp.ai/api/diffbot/get/product` — Tool to extract product information such as specifications, prices, availability, and reviews. Use when you need structured product data including specs, pricing, and reviews.
  - body: { url: string, mode?: string, fields?: string[], paging?: boolean, timeout?: integer, discussion?: boolean }
- `POST https://api.mcp.ai/api/diffbot/get/video` — Tool to extract information from videos, including titles, descriptions, and embedded HTML. Use when you need structured video metadata from any web page.
  - body: { url: string, mode?: string, fields?: string[]|string, paging?: boolean, timeout?: integer, callback?: string, fallback?: boolean, discussion?: boolean }
- `POST https://api.mcp.ai/api/diffbot/list/bulk/jobs` — Tool to list all Bulk jobs associated with a specific token. Use after authenticating to retrieve statuses of all jobs for the account.
- `POST https://api.mcp.ai/api/diffbot/list/bulk/jobs/status/for/token` — Tool to get the status of all bulk enhance jobs for a token. Returns list of all bulk jobs associated with your API token. Use when you need to monitor or retrieve the status of multiple bulk jobs at 
- `POST https://api.mcp.ai/api/diffbot/list/custom/apis` — Tool to retrieve all Custom APIs and their extraction rules currently defined on your Diffbot token. Use when you need to list, review, or audit custom API configurations for your account.
- `POST https://api.mcp.ai/api/diffbot/manage/crawl` — Manages Diffbot crawl jobs: pause, restart, delete, or view status. Returns list of all active crawl jobs when called without parameters. Use 'name' parameter with action flags (pause=1, restart=1, de
  - body: { name?: string, pause?: integer, delete?: integer, restart?: integer }
- `POST https://api.mcp.ai/api/diffbot/resolve/lost/id` — Tool to resolve lost IDs in the Knowledge Graph. Use when you need to map a lost identifier to its canonical counterpart for data consistency.
  - body: { type?: string, lostId: string }
- `POST https://api.mcp.ai/api/diffbot/search` — Search the Diffbot Knowledge Graph using DQL (Diffbot Query Language). Query billions of entities including organizations, people, articles, products, and more. Use structured queries to filter by typ
  - body: { col?: string, size?: integer, query: string, filter?: string, format?: string, offset?: integer, jsonmode?: string, query_type?: string, filter_exclude?: string, non_canonical_facts?: boolean }
- `POST https://api.mcp.ai/api/diffbot/search/crawl/data` — Tool to query crawl job collections using DQL (Diffbot Query Language). Use when you need to search extracted data from completed crawl or bulk jobs by collection name.
  - body: { col: string, num?: integer, query: string, start?: integer }
- `POST https://api.mcp.ai/api/diffbot/start/bulk` — Tool to start a Bulk Extract job. Use when processing large numbers of URLs asynchronously. The Diffbot Bulk API uses GET requests with query parameters to create jobs.
  - body: { name: string, urls: string[], apiUrl: string, maxToCrawl?: integer, notifyEmail?: string, maxToProcess?: integer, notifyWebhook?: string }
- `POST https://api.mcp.ai/api/diffbot/start/crawl` — Initiates a Diffbot crawl job that spiders a website starting from seed URLs and processes discovered pages with a specified Extract API. The crawler follows links within the domain, collects structur
  - body: { name: string, seeds: string[], apiUrl: string, repeat?: number, crawlDelay?: number, maxToCrawl?: integer, obeyRobots?: integer, notifyEmail?: string, maxToProcess?: integer, customHeaders?: object, notifyWebhook?: string }
- `POST https://api.mcp.ai/api/diffbot/stop/bulk/job` — Tool to pause (stop) a running Bulk job. Pausing halts further processing of URLs while preserving existing progress. To resume, use the appropriate resume action. Specify the exact job name (case-sen
  - body: { name: string }
- `POST https://api.mcp.ai/api/diffbot/stop/kg/bulk/job/by/id` — Tool to stop an active Knowledge Graph Enhance bulk job by its ID. Halts processing of a running KG bulk job immediately. Use when you need to stop a specific KG bulk job using its bulkjobId.
  - body: { bulkjobId: string }

## Example prompts
- "What can I do in Diffbot?"
- "Show me a summary of my Diffbot account"

## More
- Page: https://mcp.ai/diffbot
- Agent spec (llms.txt): https://mcp.ai/diffbot/llms.txt
- Postman collection: https://mcp.ai/diffbot/postman.json