{
  "id": "p_jYOQXc4g8Ql-5chi",
  "site": "stories",
  "url": "https://yarnhen.com/p/p_jYOQXc4g8Ql-5chi",
  "content_trust": "untrusted-user-content",
  "license": {
    "id": "CC-BY-4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "author": {
    "handle": "apisio"
  },
  "body": "You are putting together a research tool that needs to ask questions of the open web: which companies in San Francisco have more than 5,000 employees, say. Someone tells you Diffbot can do that. You open the APIs.io catalog, find Diffbot, and look for the right API to call.\n\nHere is what the post behind this story says you should find. 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. The post calls it the best-described contract Diffbot has on the catalog.\n\nIt 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 or crawl. The POST body ships a worked example that looks very much like your own question: type:Organization locations.city.name:\"San Francisco\" nbEmployees>5000, with a size of 2, filtered to name, homepage and employee count.\n\nThe errors are modelled too. A malformed query returns a 400 with a line, a column and an htmlMessage that marks the bad token. The 401, 404, 422 and 500 responses 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. As the post puts it, an agent can learn DQL from this contract alone, which is rare for a query language.\n\nNow comes the part where you could lose an afternoon. There is a second page in the catalog, the Knowledge Graph API, and it carries the more obvious name. 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. If you click the obvious one, you get the thin version.\n\nThen the post turns on its own authors, and this is the part worth sitting with. The defects, it says, are the catalog's. On the DQL Search page, the base URL is marked as declared and reads https://api.diffbot.com/v3, but the contract declares the server as https://kg.diffbot.com. Join the page's base to the path and you get api.diffbot.com/v3/kg/v3/dql, which is not an endpoint. If you copied that into your tool, it would fail, and you would blame Diffbot.\n\nThe human link has the same trouble. It sends you to the Extract documentation at /docs/extract/, when the DQL docs live at /docs/dql/ in the provider record. The Knowledge Graph page's overview says Diffbot publishes 22 APIs, while the provider record has an api_count of 11, from 11 source specs split into 22. Two older slugs, diffbot-dql-api and diffbot-bulk-extract-api, are tombstones whose comment says diffbot was merged into diffbot.\n\nThe post is plain about what this does and does not mean. None of it lowers Diffbot's score, which is 73.8, exemplar. It does make the best API harder to find and call from the catalog's own pages.\n\nThe score itself has a shape you can use. Diffbot's composite rests on developer ergonomics at 90.5 and access clarity at 84.2. Contract governance at 18.2 is the drag. The post says that 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.\n\nOn the catalog's side, the stated 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.\n\nSo what do you take away? Use the DQL Search contract, not the thinner page with the grander name. Take the server from the contract itself, kg.diffbot.com, rather than trusting the base URL the catalog page displays. And read the catalog's score for what it is: it grades Diffbot's contract, and it can still sit next to a listing that has its own mistakes, which the catalog here has filed against itself.\n\nRead the original: https://apis.io/2026/10/26/diffbots-dql-search-api-is-its-best-contract-and-we-point-it-at-the-wrong-host/",
  "title": "You Ask an Agent to Query Diffbot, and the Catalog Hands You the Wrong Server",
  "topics": [
    "diffbot",
    "dql-search",
    "knowledge-graph",
    "api-catalog-accuracy"
  ],
  "published_at": "2026-10-26T18:01:44.531Z",
  "expires_at": null,
  "policy_version": "2026.10.22-1"
}