Reader Endpoint

Overview

The reader endpoint allows you to pull a list of readers or a single reader, edit an existing reader, or create new readers.

Reader keys:


NameTypeRead-onlyRequiredComment
idstringyesnoAutomatically assigned during creation
typestringyesnoDescriptive only
usernamestring / email addressnoyesMust be a valid email address if using self-administered reader passwords
first_namestringnonoReader's first name
last_namestringnonoReader's last name
iconURLnonoURL path of image to be used as reader icon
custom1mixednonoCan be used to store any information wished about the reader
custom2mixednonoCan be used to store any information wished about the reader
custom3mixednonoCan be used to store any information wished about the reader
custom4mixednonoCan be used to store any information wished about the reader
custom5mixednonoCan be used to store any information wished about the reader
passwordstringnonoPassword set and maintained by KO admins on behalf of the reader. Ignored if using self-administered passwords
date_lastlogintimestampyesnoUpdated at time of reader login
date_createdtimestampyesnoSet at reader creation
date_modifiedtimestampyesnoSet whenever a reader is modified
statusstringnoyesEither 'active' or 'deleted'
projectsarraynoyesArray of knowledge base IDs the reader has access to
pending_projectsarraynonoArray of knowledge base IDs the reader has requested access to
reader_rolesarraynonoArray of reader group IDs this reader belongs to

Reader URLs

  • GET LIST /api/head/reader.json
  • GET /api/head/reader/{{reader ID}}.json
  • POST /api/head/reader.json
  • PUT /api/head/reader/{{reader ID}}.json

GET LIST

All readers in your account, no filter

//all readers in your in your account, includes deleted readers
curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X GET "https://app.knowledgeowl.com/api/head/reader.json"

Active readers that belong to a reader group

//non-deleted readers in your in your account that belong to a specific reader group
curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X GET "https://app.knowledgeowl.com/api/head/reader.json"
  -d '{"status": "active", "reader_roles": {"$in": ["12345abcd"]}}'
  
//JSON that is being passed above:
{
  "status": "active",
  "reader_roles": {
    "$in": ["12345abcd"]
  }
};

GET

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

POST — Create Reader

When creating a new reader via POST, you will either need to pass in a SSO ID, a temporary password, or specify that you want the reader to be emailed a new temporary password. This is only true when using self-administered reader passwords (readers manage their own passwords).

Create reader and send welcome email with temporary password

//temporary password will be automatically generated and reader will receive welcome
//email based on your account settings
curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X POST "https://app.knowledgeowl.com/api/head/reader.json"
  -d '{"username": "readeremail@example.com", "projects": ["kbID123", "kbID321"], "pw-type": "email"}'
  
//JSON that is being passed above:
{
  "username": "readeremail@example.com",
  "projects": [
    "kbID123",
    "kbID321"
  ],
  "pw-type": "email"
};

Create reader and choose a temporary password

//temporary password specified by you 
//reader will not receive any email
curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X POST "https://app.knowledgeowl.com/api/head/reader.json"
  -d '{"username": "readeremail@example.com", "projects": ["kbID123", "kbID321"], "pw-type": "temp", "temp-pass": "str0ngTempPa$$word"}'
  
//JSON that is being passed above:
{
  "username": "readeremail@example.com",
  "projects": [
    "kbID123",
    "kbID321"
  ],
  "pw-type": "temp",
  "temp-pass": "str0ngTempPa$$word"
};

PUT — Update Reader

//Update existing reader meta data
curl -u {{KnowledgeOwl API key}}:X
  -H "Content-type: application/json"
  -X PUT "https://app.knowledgeowl.com/api/head/reader/{{reader ID}}.json"
  -d '{"username": "newemail@example.com", "first_name": "Updated", "last_name": "Reader"}'
  
//JSON that is being passed above:
{
  "username": "newemail@example.com",
  "first_name": "Updated",
  "last_name": "Reader"
};