Suggest articles (API)

Overview

The /suggest endpoint allows you to perform knowledge base searches through the API. Returned results include metadata about each matching article such as their title, permalink, and the highlighted content that matches the search. Results do not include the full article content.

URL:  https://app.knowledgeowl.com/api/head/suggest.json

Required fields: 

• project_id : Your knowledge base ID. Refer to Find your knowledge base ID or project ID for instructions on finding your knowledge base ID.
• phrase: Your search term

Sample curl request with authentication

Here's an example curl request against the suggest endpoint using authentication:

curl -u {{KnowledgeOwl-API-key}}:X
  -H "Content-type: application/json"
  -X GET "https://app.knowledgeowl.com/api/head/suggest.json"
  -d '{"project_id": "{{Knowledge base ID}}", "phrase": "How do I", "limit": 1}'

Sample response

And here's a sample response from that request, returned in JSON format:

{
  "valid": true,
  "page_stats": {
    "total_records": 150,
    "total_pages": 150,
    "next_page": 2
  },
  "data": [
    {
      "id": "12345abcde",
      "type": "article",
      "score": 2555.0132,
      "highlight": {
        "body.english": [
          "<em>How<\/em> clearly <em>do<\/em> <em>I<\/em> make an example article?",
          "<em>How<\/em> well <em>do<\/em> <em>I<\/em> show highlighting?",
          "<em>How<\/em> well <em>do<\/em> <em>I<\/em> create examples?"
        ]
      },
      "url_hash": "example-permalink",
      "callout_video": null,
      "callout": "none",
      "callout_expire": 1526657828,
      "date_created": "2017\/12\/15 11:10:30",
      "date_modified": "2018\/05\/11 11:37:08",
      "name": "Example Article Title",
      "category": "1234abcde",
      "summary": "Short summary of the article content or meta_description field...",
      "tags": ["12345abcde"],
      "reader_roles": null,
      "inherited_roles": [
        "12345abcde",
        "abcde12345"
      ],
      "parents": [
        "12345abcde",
        "abcde12345"
      ],
      "content_article": null,
      "external_redirect": false,
      "redirect_options": {
        "new_tab" :true
      },
      "view_count": 100
    }
  ]
}

Filtering results

You can further refine search results by building your own custom filter when you make the call. The following examples show how search results can be refined.

Most fields available in the article endpoint can be used as filters here. Refer to our API endpoint reference documentation for more information on that endpoint.

Sample search of only published articles

Pass in one or more specified status to only include articles with a specific publishing status. Pro tip: if you're passing multiple statuses, use an $in operator here!

Here's an example of only including articles with a "Published" status:

//example curl call
//if no status filter is included, default behavior is to return
//articles that have a status of "published" or "review" as those 
//articles are visible in the live knowledge base
curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X GET "https://app.knowledgeowl.com/api/head/suggest.json"
  -d '{"project_id": "{{Knowledge base ID}}", "phrase": "How do I", "limit": 20, "status": "published"}'

//JSON that is being passed above:
{
  "project_id": "{{Knowledge base ID}}",
  "phrase": "How do I", 
  "limit": 20, 
  "status": "published"
};

Sample search of only articles within a specific category

You can also pass in a parents list using $in to only return articles within a specific category.

Here's an example to return search result suggestions only within a specific category:

//example curl call
curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X GET "https://app.knowledgeowl.com/api/head/suggest.json"
  -d '{"project_id": "{{Knowledge base ID}}", "phrase": "How do I", "limit": 20, "parents": {"$in": ["12345abcde"]}}'

//JSON that is being passed above:
{
  "project_id": "{{Knowledge base ID}}",
  "phrase": "How do I", 
  "limit": 20, 
  "parents": {
    "$in": ["12345abcde"]
  }
};

Limit results and paging

Like the other API endpoints, you can specify how many results you would like retrieve in the request (limit) and/or which page of results to return (page). The page_stats object returned as part of the API response contains how many total articles were found, how many pages of results there are using the current limit and the number for the next page of results.

For example, in this sample call, we limit the results to 20 results per page and retrieve the second page of results:

//example curl call
curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X GET "https://app.knowledgeowl.com/api/head/suggest.json"
  -d '{"project_id": "{{Knowledge base ID}}", "phrase": "How do I", "limit": 20, "page": 2}'

//JSON that is being passed above:
{
  "project_id": "{{Knowledge base ID}}",
  "phrase": "How do I", 
  "limit": 20, 
  "page": 2
};

Refer to API query operators for more information on working with limits and pages.

Sorting results

The default behavior is to return results sorted by relevancy to the search phrase. Use a sort filter to set a different sorting function.

Here are the available sorts:

• rel: Sort by relevancy to the search phrase with most relevant first
• pop: Sort by popularity/article view count with highest views first
• mod-des: Sort by date modified, with most recently modified first
• cr-des: Sort by date created, with most recently created first

Here's a sample using the popularity sort:

//example curl call
curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X GET "https://app.knowledgeowl.com/api/head/suggest.json"
  -d '{"project_id": "{{Knowledge base ID}}", "phrase": "How do I", "limit": 20, "sort": "pop"}'

//JSON that is being passed above:
{
  "project_id": "{{Knowledge base ID}}",
  "phrase": "How do I", 
  "limit": 20, 
  "sort": "pop"
};

Reader groups

The default behavior if reader groups are not specified is to return all matching articles regardless of reader group restrictions. Use the reader_groups array to factor the article's reader group restrictions into your search.

The following examples show how you can alter this behavior and return only public articles (those with no reader group restrictions) or only public articles and those that belong to certain reader groups.

Sample public article search only

Here's an example of a suggest call in which we return only public articles (those that have no reader group restrictions):

//example curl call
curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X GET "https://app.knowledgeowl.com/api/head/suggest.json"
  -d '{"project_id": "{{Knowledge base ID}}", "phrase": "How do I", "limit": 1, "reader_groups": ["public"]}'

//JSON that is being passed above:
//additional reader group IDs will be ignored if "public" is in the reader_groups array
{
  "project_id": "{{Knowledge base ID}}",
  "phrase": "How do I", 
  "limit": 1, 
  "reader_groups": ["public"]
};

Sample public article and reader group restricted search

And here's an example of a suggest call in which we return public articles and those restricted to specific reader groups:

//example curl call
curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X GET "https://app.knowledgeowl.com/api/head/suggest.json"
  -d '{"project_id": "{{Knowledge base ID}}", "phrase": "How do I", "limit": 1, "reader_groups": ["public", "abcde12334"]}'

//JSON that is being passed above:
{
  "project_id": "{{Knowledge base ID}}",
  "phrase": "How do I", 
  "limit": 1, 
  "reader_groups": ["public", "abcde12334"]
};

Autocomplete/partial searches

If you are trying to implement a "search as you type" solution using the API, you must specify that the search phrase being passed through is not a full search by setting partial_search to true.

Once you set partial_search to true, the API will return results using ngram search algorithms instead of the full search algorithms. These searches will also be excluded from the "Searches with no results" reporting inside of the application.

Sample autocomplete/partial search

Here's a sample suggest search where we set partial_search to true:

//example curl call
curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X GET "https://app.knowledgeowl.com/api/head/suggest.json"
  -d '{"project_id": "{{Knowledge base ID}}", "phrase": "How d", "limit": 10, "partial_search": "true"}'

//JSON that is being passed above:
{
  "project_id": "{{Knowledge base ID}}",
  "phrase": "How d", 
  "limit": 10, 
  "partial_search": "true"
};

Perform full search but exclude results from reporting

We can also complete a full search but exclude the results from our search terms with no results reporting:

//example curl call
curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X GET "https://app.knowledgeowl.com/api/head/suggest.json"
  -d '{"project_id": "{{Knowledge base ID}}", "phrase": "How d", "limit": 10, "ignore_misses": "true"}'

//JSON that is being passed above:
{
  "project_id": "{{Knowledge base ID}}",
  "phrase": "How d", 
  "limit": 10, 
  "ignore_misses": "true"
};

Search weight manipulation

The default behavior for the endpoint is to use the search weighting set in KB settings > Search and synonyms > Keywords. 

Use the searchSettings array to set search weights specific to your call. Here are the available search fields you can set weights for:

• title: The article's Title
• body: All the content in the article's body/the editor pane
• url_hash: The article's permalink
• pdf_content: Any embedded PDFs
• meta_description: The article's Summary
• search_phrases: The article's Search phrases

Refer to Keyword search fields and weights and Use search field weights for more information on working with search weights.

Sample bump the weight of article titles

//example curl call
//fields that are omitted from the searchSettings["weights"] object will fall back to app search settings
curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X GET "https://app.knowledgeowl.com/api/head/suggest.json"
  -d '{"project_id": "{{Knowledge base ID}}", "phrase": "How do I", "limit": 1, "searchSettings": {"weights": {"title": 50}}}'

//JSON that is being passed above:
{
  "project_id": "{{Knowledge base ID}}",
  "phrase": "How do I", 
  "limit": 1, 
  "searchSettings": {
    "weights": {
      "title": 50,
      "body": 1
    }
  }
};