{ "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "Web Search" }, "servers": [ { "url": "https://llm.diffbot.com/api/v1/web_search" } ], "tags": [], "paths": { "/": { "get": { "summary": "Run a Web Search", "description": "Search Diffbot's Web Index", "responses": { "200": { "$ref": "#/components/responses/Results" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string", "example": "query param text size must be between 1 and 5" } } } }, "examples": { "Bad Request": { "summary": "Bad Request", "value": { "errors": [ "query param text size must be between 1 and 5" ] } } } } }, "description": "Bad Request" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "operationId": "get_", "parameters": [ { "in": "query", "name": "text", "required": true, "schema": { "$ref": "#/components/schemas/Query" } }, { "in": "query", "name": "size", "schema": { "$ref": "#/components/schemas/Size" } }, { "in": "query", "name": "maxTokens", "schema": { "$ref": "#/components/schemas/MaxTokens" } } ] }, "post": { "summary": "Run a Web Search", "operationId": "post_", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "$ref": "#/components/schemas/Query" }, "size": { "$ref": "#/components/schemas/Size" }, "maxTokens": { "$ref": "#/components/schemas/MaxTokens" } } }, "examples": { "Search": { "summary": "A single query", "value": { "text": [ "diffbot" ], "size": 10 } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Results" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Missing text parameter" } } }, "examples": { "Missing text": { "summary": "Missing text", "value": { "code": 400, "message": "Missing text parameter" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "Authorization": { "type": "http", "scheme": "bearer", "description": "Diffbot API Token" } }, "schemas": { "Query": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "example": "diffbot" }, "description": "Your search query.\n\nUse the following operators to refine your search. \n\n| Operator | Description | Example |\n| --- | --- | --- |\n| `after` | Documents published after the provided date | `after:2026-06-10` |\n| `before` | Documents published before the provided date | `before:2026-05-10` |\n| `site` | Documents matching the provided domain | `site:diffbot.com` |\n| `url` | Documents matching the exact URL | `url:diffbot.com` |" }, "Size": { "type": "number", "default": "10", "description": "Number of results to return in the search response" }, "MaxTokens": { "type": "number", "description": "Cap the search response to this value. Highlight chunks will be reduced in length equitably." } }, "responses": { "Results": { "description": "Successful response", "content": { "application/json": { "examples": { "OK": { "summary": "OK", "value": { "query": [ "Diffbot" ], "search_results": [ { "score": 0.973, "pageUrl": "https://www.diffbot.com/", "title": "Web Data for your AI", "content": "Imagine if your app could access the web like a structured database.\n\n Your browser does not support the video tag. \n- 50+ data fields, including categories, revenue, locations, and investments\n- Over 246M companies and non-profits in the Knowledge Graph\n- Extract and refresh orgs on demand\n\n- More than just text \u2014 entity matching, topic-level sentiment, and more\n- Over 1.6B news articles, blog posts, and press releases in the Knowledge Graph\n\n\n## The Web is Noisy, \nDiffbot Straightens it Out \n\nThe world's largest compendium of human knowledge is buried in the code of 1.2 billion public websites. Diffbot reads it all like a human, then transforms it into usable data." }, { "score": 0.887, "pageUrl": "https://www.diffbot.com/data/article/", "title": "Diffbot | News & Articles", "content": "..." }, { "score": 0.847, "pageUrl": "https://github.com/diffbot", "title": "Diffbot", "date": "Thu, 12 Mar 2026 00:00:00 GMT", "content": "..." } ], "timeMs": 154 } } }, "schema": { "type": "object", "properties": { "query": { "type": "array", "items": { "type": "string", "example": "Diffbot" }, "description": "The parsed query terms." }, "search_results": { "type": "array", "items": { "type": "object", "properties": { "score": { "type": "number", "example": 0.973, "default": 0, "description": "Represents the confidence of the result from 0 (lowest) to highest (1). 3 decimal places of precision." }, "pageUrl": { "type": "string", "example": "https://www.diffbot.com/", "description": "URL of the page." }, "title": { "type": "string", "example": "Web Data for your AI", "description": "Title of the page." }, "content": { "type": "string", "example": "Imagine if your app could access the web like a structured database.\n\n Your browser does not support the video tag. \n- 50+ data fields, including categories, revenue, locations, and investments\n- Over 246M companies and non-profits in the Knowledge Graph\n- Extract and refresh orgs on demand\n\n- More than just text \u2014 entity matching, topic-level sentiment, and more\n- Over 1.6B news articles, blog posts, and press releases in the Knowledge Graph\n\n\n## The Web is Noisy, \nDiffbot Straightens it Out \n\nThe world's largest compendium of human knowledge is buried in the code of 1.2 billion public websites. Diffbot reads it all like a human, then transforms it into usable data.", "description": "A spliced chunk highlight from the original full page contents." }, "date": { "type": "string", "example": "Thu, 12 Mar 2026 00:00:00 GMT", "description": "Publication date of the page, when known. RFC 1123 format. Omitted when the page has no discoverable publication date." } } }, "description": "The ranked results." }, "timeMs": { "type": "integer", "example": 154, "default": 0, "description": "Time taken for retrieval, reranking, and response generation." } } } } } }, "Unauthorized": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 401, "default": 0 }, "message": { "type": "string", "example": "Missing or invalid Authorization header. Expected: Bearer " } } }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "code": 401, "message": "Missing or invalid Authorization header. Expected: Bearer " } } } } }, "description": "Unauthorized" } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": false }, "security": [ { "Authorization": [] } ] }