openapi: 3.2.0
info:
  version: 1.0.0
  title: Web Search API
servers:
- url: https://llm.diffbot.com/api/v1/web_search
security:
- Authorization: []
tags:
- name: Web Search
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'
      tags:
      - Web Search
    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'
      tags:
      - Web Search
components:
  responses:
    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 <token>'
          examples:
            Unauthorized:
              summary: Unauthorized
              value:
                code: 401
                message: 'Missing or invalid Authorization header. Expected: Bearer <token>'
      description: Unauthorized
    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 — 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 — 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.
  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.
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      description: Diffbot API Token
x-readme:
  explorer-enabled: true
  proxy-enabled: false