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:
| Name | Type | Read-only | Required | Comment |
|---|---|---|---|---|
| id | string | yes | no | Automatically assigned during creation |
| type | string | yes | no | Descriptive only |
| username | string / email address | no | yes | Must be a valid email address if using self-administered reader passwords |
| first_name | string | no | no | Reader's first name |
| last_name | string | no | no | Reader's last name |
| icon | URL | no | no | URL path of image to be used as reader icon |
| custom1 | mixed | no | no | Can be used to store any information wished about the reader |
| custom2 | mixed | no | no | Can be used to store any information wished about the reader |
| custom3 | mixed | no | no | Can be used to store any information wished about the reader |
| custom4 | mixed | no | no | Can be used to store any information wished about the reader |
| custom5 | mixed | no | no | Can be used to store any information wished about the reader |
| password | string | no | no | Password set and maintained by KO admins on behalf of the reader. Ignored if using self-administered passwords |
| date_lastlogin | timestamp | yes | no | Updated at time of reader login |
| date_created | timestamp | yes | no | Set at reader creation |
| date_modified | timestamp | yes | no | Set whenever a reader is modified |
| status | string | no | yes | Either 'active' or 'deleted' |
| projects | array | no | yes | Array of knowledge base IDs the reader has access to |
| pending_projects | array | no | no | Array of knowledge base IDs the reader has requested access to |
| reader_roles | array | no | no | Array 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"
};
