API Overview

Authentication

Our API is an HTTPS only API. Any non-secure requests will return an error. Authentication is based off of API keys which can be generated per account. Each API key can be restricted to allow GET, POST, PUT, and DELETE access or a combination. 

The API key should be passed via HTTP Basic Authentication and goes in the username field. Any dummy password, such as X, can be used for the password field.

Example curl request with authentication

curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X GET "https://app.knowledgeowl.com/api/head/{{object}}.json"

To retrieve / generate a KnowledgeOwl API key, navigate to Your Account → API.
You must be an account administrator to perform this action.

Accepted input formats

KnowledgeOwl's API accepts the following input types:

  • Standard REST HTTP headers — ?field1=value&field2=value&array1[]=value1&array1[]=value2
  • Application/JSON — '{"field1": "value", "field2": "value", "array1": ["value1", "value2"]}'

Output formats

KnowledgeOwl's API can return the following output types as specified by the call endpoint:

  • JSON (default) — https://app.knowledgeowl.com/api/head/{{object}}.json
  • JSONP — https://app.knowledgeowl.com/api/head/{{object}}.jsonp?callback={{functionName}}
  • HTML — https://app.knowledgeowl.com/api/head/{{object}}.html
  • PSON — https://app.knowledgeowl.com/api/head/{{object}}.pson

Object field reference

To retrieve a list of available object fields with descriptions of usage, the parameter "_method" can be passed with a value of "EXPLAIN". For example:

curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X GET "https://app.knowledgeowl.com/api/head/{{object}}.json"
  -d '{"_method": "EXPLAIN"}'

Object filter rule syntax

String and array comparisons

//Example article object
{
  "id": "9999",
  "name": "Article 1",
  "parents": [
    "1234",
    "4321"
  ]
}
  • $in — in array
    //Using $in to find the example article based off of the "name" field which is a string
    //This filter will match any article that has a "name" of "Article 1", OR "Article 2"
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"name": {"$in": ["Article 1", "Article 2"]}}'
    //Using $in to find the example article based off of the "parents" field which is an array
    //This filter will match any article that contains the value "1234" within the "parents" array
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"parents": {"$in": ["1234"]}}'
  • $nin — not in array
    //Using $nin to exclude the example article based off of the "name" field which is a string
    //This filter will exclude any articles that have a "name" of "Article 1" OR "Article 2"
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"name": {"$nin": ["Article 1", "Article 2"]}}'
    //Using $nin to exclude the example article based off of the "parents" field which is an array
    //This filter will exclude any articles that have the value "1234" within the "parents" array
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"parents": {"$nin": ["1234"]}}'
  • $ne — not equal to
    //Using $ne to find all articles that do not have a "status" of "deleted"
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"status": {"$ne": "deleted"}}'
    
  • $regex — regular expression string comparison
    //Using $regex to find the example article based off of the "name" field which is a string
    //This filter will match any article that contains the string "article" in the "name" field
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"name": {"$regex": "article", "$option": "i"}}'
    
    //The "$option" value of "i" modifies the regular expression to be case insensitive
    //Available regex modifiers are "i", "m", "x", and "s"

Date and numeric value comparisons

Dates are returned via the API in human readable format based on the Timezone and Date Format settings in your knowledge base.

When filtering API objects based off of dates, the API expects unix timestamps to be passed in.

//Example article object
{
  "id": "1234",
  "index": 2,
  "date_created": "11/07/2015 11:06 am GMT", //Equal to 1446894360 unix timestamp
}
  • $gt — greater than
    //Using $gt to include the example article based off of the "index" field which is numeric
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"index": {"$gt": 1}}'
    //Using $gt to include the example article based off of the "date_created" field which is a timestamp
    //1446807960 is equal to 11/06/2015 11:06 am GMT
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"date_created": {"$gt": "1446807960"}}'
  • $gte — greater than or equal to
    //Using $gte to include the example article based off of the "index" field which is numeric
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"index": {"$gte": 2}}'
    //Using $gte to include the example article based off of the "date_created" field
    //1446894360 is equal to 11/07/2015 11:06 am GMT
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"date_created": {"$gte": "1446894360"}}'
  • $lt — less than
    //Using $lt to include the example article based off of the "index" field which is numeric
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"index": {"$gte": 3}}'
    //Using $lt to include the example article based off of the "date_created" field
    //1446980760 is equal to 11/08/2015 11:06 am GMT
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"date_created": {"$gte": "1446980760"}}'
  • $lte — less than or equal to
    //Using $lte to include the example article based off of the "index" field which is numeric
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"index": {"$lte": 2}}'
    //Using $lte to include the example article based off of the "date_created" field
    //1446894360 is equal to 11/07/2015 11:06 am GMT
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"date_created": {"$lte": "1446894360"}}'

Advanced logic filtering

//Example article object
{
  "id": "9999",
  "name": "Article 1",
  "index": 10,
  "status": "deleted",
}
  • $and — must match ALL specified filters
    //Using $and to include the example article based off of multiple filters
    //Article must have an "index" that is greater than 1 AND less than 20
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"$and": [{"index": {"$gt": 9}}, {"index": {"$lt": 20}}]}'
  • $or — must match ONE of the specified filters
    //Using $or to include the example article based off of multiple filters
    //Article can either have an "index" that is greater than 20 OR less than 11
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"$or": [{"index": {"$gt": 20}}, {"index": {"$lt": 11}}]}'
  • $nor —  match  NOT match ANY of the specified filters
    //Using $nor to include the example article based off of multiple filters
    //Article must NOT have an "index" that is greater than 11 NOR less than 9
    curl -u {{API Key}}:X
      -H "Content-type: application/json"
      -X GET "https://app.knowledgeowl.com/api/head/article.json"
      -d '{"$nor": [{"index": {"$gt": 11}}, {"index": {"$lt": 9}}]}'