The most interesting single API Diffbot publishes is not the Extract API that made its name. It is the DQL Search API: 4 operations that let you query the Knowledge Graph, Diffbot’s linked graph of over 10 billion entities crawled from the public web, in a query language of its own. It is also the best-described contract Diffbot has on the catalog. And our page for it sends you to the wrong server.
What the contract holds
DQL Search is small and complete. GET /kg/v3/dql and POST /kg/v3/dql run a query; GET /kg/v3/dql/report and GET /kg/v3/dql/report/{id} download a coverage report as CSV. The query parameter takes a type (query, text, queryTextFallback, crawl), and the POST body ships a worked example: type:Organization locations.city.name:"San Francisco" nbEmployees>5000, size 2, filtered to name, homepage and employee count. The errors are modelled too. A malformed query returns a 400 with line, column and an htmlMessage that marks the bad token, and 401, 404, 422 and 500 each carry their own example.
That shape is why Diffbot’s Agent Readiness reads 44.8, agent-ready, gated down from agent-native, with error semantics and OpenAPI examples both marked verified. An agent can learn DQL from this contract alone, which is rare for a query language.
Compare the page we call the Knowledge Graph API. It lists 2 operations, dqlSearch and enhance, and both return a bare 200 with no schema. Its description says, accurately, that entity shapes “are documented as reference pages rather than declared as schemas.” So the same /kg/v3/dql path appears on two pages, once well described and once barely, and the thin one carries the more obvious name.
Where the record is wrong
The defects here are ours.
| Field | DQL Search API page | What the contract says |
|---|---|---|
baseURL |
https://api.diffbot.com/v3 |
server https://kg.diffbot.com |
humanURL |
/docs/extract/ |
DQL docs at /docs/dql/ (in the provider record) |
description |
“DQL Search” | “DQL is an API to query entities in the Knowledge Graph” |
The page marks its base URL as declared, but the contract declares kg.diffbot.com. Joining the page’s base to the path gives api.diffbot.com/v3/kg/v3/dql, which is not an endpoint. The human link sends readers to Extract documentation. The Knowledge Graph page’s overview says Diffbot publishes 22 APIs, while the provider record has api_count: 11 from 11 source specs split into 22. Two older API slugs, diffbot-dql-api and diffbot-bulk-extract-api, are tombstones whose comment says “diffbot was merged into diffbot.”
None of that lowers Diffbot’s score, which is 73.8, exemplar, but it does make the best API harder to find and call from our pages.
Takeaway
Diffbot’s composite rests on developer ergonomics at 90.5 and access clarity at 84.2. Contract governance at 18.2 is the drag. Publishing entity schemas for the Knowledge Graph responses, instead of leaving them on reference pages, would lift contract quality from 58.4 and make the two Knowledge Graph pages say the same thing. On our side, the fix is to read the base URL from the contract’s own server, point the human link at the DQL docs, and fold the thin Knowledge Graph page into this one.
Start at the DQL Search API and Diffbot’s own DQL documentation.