Suggest articles (API)

Overview

The /suggest endpoint allows you to perform knowledge base searches via the API. Returned results include meta data 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 — knowledge base ID
  • phrase — search term

Example curl request with 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}'

Example response

{
  "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 at the time of the call. The following examples show how search results can be refined.

Only include articles with a status of published

//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"
};

Only include articles that exist 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 and / or which page of results to return. 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.

Limit the results to 20 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
};

Sorting results

The default behavior if not specified is to return results sorted by relevancy to the search phrase. There are several other ways to sort that you can specify at the time of the call.

Search sorting options:

  • rel (relevancy)
  • pop (popularity / article view count)
  • mod-des (last modified)
  • cr-des (last created)

Sort results by popularity

//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 group ownership. The following examples show how you can alter this behavior and return only public articles, or only public articles and those that belong to certain reader groups.

Passing the reader_groups array will automatically apply waterfall reader group logic. This means that the API will not return an article that is inside of a category that is restricted to a reader group unless that reader group ID is included in the reader_groups array.

Return only public articles (articles that are not restricted to a reader group)

//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"]
};

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": ["12345abcde", "abcde12334"]}'

//JSON that is being passed above:
{
  "project_id": "{{Knowledge base ID}}",
  "phrase": "How do I", 
  "limit": 1, 
  "reader_groups": ["12345abcde", "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 specifying this, 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.

Autocomplete / partial search

//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

//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 if search weights are not included in the request is to use the search weighting specified in the application search settings. The following examples show how you can alter this behavior to weight certain search fields higher than others at the time of the call.

Weight values must be from 1 to 100 in increments of 5. Available search fields:

  • title
  • body
  • url_hash (permalink)
  • pdf_content (embedded PDFs)
  • meta_description
  • search_phrases

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
    }
  }
};