API Guides

    Search results with sources you can check

    By Desearch Editorial Team5 min read
    Desearch card titled Search results with sources you can check: an answer card linked to a source page card with its matching passage outlined and a date line.

    An answer is only as useful as your ability to check it. When an AI app tells a user that something is true, the user should be able to see where that came from: which page, which passage, and when it was published.

    So, can a search API return relevant web sources? Yes, if the response is built for it. The Desearch Search API (POST /search) returns ranked pages, each with its URL, title and the passage that best matches the query, and it can add a short answer whose numbered citations point back to those pages. This post shows how to request those sources, how to check each one, and how to limit which sites can appear.

    What makes a source checkable

    A link alone is not enough. To check a claim quickly, a reader or an agent needs four things for each source:

    • The URL, to open the page.
    • The title, to see what the page is.
    • The passage that matched, to see the exact text behind the claim.
    • The date, to judge whether the information is current.

    POST /search returns all four for each result: url, title, highlights and published_date. The date is given as YYYY-MM-DD when it is known and can be null, so treat a missing date as unknown, not as recent.

    Request sources with POST /search

    POST /search searches the web from the Desearch index. Only query is required. Add summary: true to also get a short answer written from the results.

    BASH
    curl --request POST 'https://api.desearch.ai/search' \
      --header "Authorization: $DESEARCH_API_KEY" \
      --header 'Content-Type: application/json' \
      --data '{
        "query": "Who won the 2024 Nobel Prize in Physics?",
        "count": 10,
        "summary": true
      }'

    The sources and the cited answer in the response, from the Search API guide (the meta and billing fields are left out here):

    JSON
    {
      "results": [
        {
          "url": "https://www.nobelprize.org/prizes/physics/2024/summary/",
          "title": "The Nobel Prize in Physics 2024",
          "published_date": "2024-10-08",
          "highlights": [
            "The Nobel Prize in Physics 2024 was awarded jointly to John J. Hopfield and Geoffrey Hinton."
          ]
        }
      ],
      "summary": {
        "text": "John J. Hopfield and Geoffrey Hinton won the 2024 Nobel Prize in Physics [1].",
        "citations": [
          {
            "index": 1,
            "url": "https://www.nobelprize.org/prizes/physics/2024/summary/",
            "title": "The Nobel Prize in Physics 2024"
          }
        ]
      }
    }

    How to check a cited answer

    The summary marks each cited sentence with [n]. That number is the index of an entry in summary.citations, which gives the url and title of the cited page. Every cited page is also in results, so you can find its passage and date there.

    A simple check for each sentence in the answer:

    1. Find the marker. Read the [n] at the end of the sentence.
    2. Match the citation. Look up the entry in summary.citations with that index.
    3. Find the result. Find the item in results with the same url.
    4. Compare the text. Read its highlights. In the example above, the passage says the prize "was awarded jointly to John J. Hopfield and Geoffrey Hinton", which is what the sentence states.
    5. Check the date. Use published_date to decide whether the page is recent enough for the question.
    6. Open the page when the passage is not enough, or when the claim matters.

    Steps 1 to 3 can run in code before anything reaches the user. A sentence with no marker, or with a marker that has no matching citation, is a sentence to drop or to show without a source.

    The summary is only returned when you set summary: true. If it could not be written, summary is null, meta.notices contains "Summary unavailable.", and the results are still returned. Your app can then show the sources on their own.

    Choose which sources can appear

    Relevance starts with the sites you allow. POST /search lets you set this in the request:

    • include_domains: only return pages on these domains or their subdomains (at most 100).
    • exclude_domains: never return pages on these domains (at most 1,200).
    • start_date and end_date: only pages published in this range (YYYY-MM-DD).
    • mode: balanced (the default) favors relevance, fast returns results sooner.

    For example, a support assistant can limit results to a product's public documentation site and a few trusted references, so every source a user sees comes from that list.

    Read the full page before you rely on it

    A passage shows why a page matched. It does not show the context around it. When you need that context, you have two options:

    • Set page_text: true on POST /search to include the full page text with each result.
    • Send a source URL to the Extract API, which returns the page as text, markdown or HTML:
    GET https://api.desearch.ai/web/extract?url=https://example.com&format=text

    Reading the source page is how an agent catches a passage taken out of context, or a page that says more than the snippet shows.

    Sources from X and the web together

    When the question needs posts from X as well as web pages, use the AI Search API (POST /desearch/ai/search) with tools set to web, twitter or both. It returns the sources it found, each with a link, and by default a written summary of them. Our post AI Search API with source links on every answer walks through that request and its response.

    What a citation does and does not prove

    A citation tells you where a sentence came from. It does not prove the sentence is true, and it does not prove the page is right. Checking that a cited link is one of the returned sources is a check on the citation, not on the claim.

    That is why the passage, the date and the page itself matter. Show them to the user, keep the source URL next to the generated answer, and let the reader decide when the stakes are high.

    Try it

    Create an API key in Desearch Console, store it as DESEARCH_API_KEY on your server, and run the POST /search request above with summary: true. Then follow one [n] marker back to its page. The full parameter lists and response schemas are in the API reference.

    Put your next idea to work.

    Try a query in the playground, then use the docs to bring Desearch into your application.

    Browse more articles