API Reference

REST Methods

The IKANOW API includes the following RESTful methods to access IKANOW capabilities.

Knowledge management: querying the document, entity and event databases

The most important API call performs searches, and ranks and aggregates documents and sub-objects like entities, associations, and metadata. The link below comprises a number of pages discussing the configuration and output.

It is also possible to get individual documents (just metadata or metadata and content):

We call any element of the document data model that exists independently to the document a "feature" (including entities, geotags, entity associations). There are a number of methods to retrieve these features:

Authentication methods

With a few minor exceptions, it is necessary to log-in before invoking any other methods. Some methods require system-wide admin privileges, indicated below with "(admin)". Other methods need to be approved by the community owner before they take effect, these are indicated below with "(community-approval)". Others can only be performed by the community owner, the content owner, or an admin, these are indicated below with "(owner/moderator/admin)". It is assumed that any call that takes a community ID requires membership of that community, apart from requesting to join public communities.

  • auth/login: returns a cookie to make subsequent api calls after authenticating a user
  • auth/login/admin (admin): returns an admin cookie to make subsequent admin api calls after authenticating an administrator
  • auth/keepalive: updates a cookie to last for 30 more minutes
  • auth/logout: removes a users cookie not allowing them to make api calls anymore
  • auth/forgotpassword: starts process to receive password via email
  • auth/deactivate (admin): turns off a users account so they can no longer log in

Logging out is optional - users can only be logged-in from one place and the older session is automatically terminated when the newer one begins.

If an API key is specifed (via REST or the GUI) then any API command can be authenticated with the URL parameter "infinite_api_key" instead of logging in. API keys can be used in cookies also, in the format "infinitecookie=api:API_KEY;".

Source management

These methods can be used to get information about the sources that IKANOW harvests to populate its database (see this overview). This might be needed in order to specify the inputs over which a query is run, or to check the harvest status of a source (either regularly or based on unexpected results).

  • config/source/get: returns a source object given its "_id" field.
  • config/source/good: returns a list of all active sources.
  • config/source/user: returns a list of all sources owned or (optionally) visible to that user (or for admins - optionally all sources regardless of community).

These methods are more administrative:

  • config/source/bad: lists unapproved sources (also sources that have been turned off by the IKANOW harvester due to issues in harvesting the source)
  • config/source/pending: lists proposed sources that a community administrator has not yet approved.

The process of configuring source objects, which is basically simple but allows for sophisticated functionality in return for more complexity, is described here.

A key activity, either for Open Source Analysis or for mining an organizations internal data-stores, is creating source configuration objects. The link below comprises a number of pages describing the different possible configurations.

  • config/source/save: (community-approval) for new sources, (owner/moderator/admin) for existing sources. Adds a new source to the harvest list
  • config/source/add: (deprecated) (community-approval)
  • config/source/test: tests a new source in the harvester to compare results and tweak source setup
  • config/source/suspend: stops a source from harvesting or resumes a suspending source back again

After a source has been added, a request is sent to the community administrator, who has the option to accept or decline it. Only accepted sources are processed by the IKANOW harvester. "config/source/save" can be used by users with appropriate permissions to edit a source's status.

Admins and owners can remove documents from sources (or the sources themselves, which automatically removes the documents as well):

Community methods

The Community API calls are used to manage communities (add, update, remove, and get). The APIs can be broken out into the following basic areas of functionality:

Basic community administration: APIs used to add a new community, remove an existing community, or update an existing community.

A user can retrieve their list of communities (together with other user metadata) with the "person/get" API call:

A user can also retrieve a list of all other users they are in communities with:

Community membership: APIs used to join (request membership in) a community, leave a community, invite a user to join a community, update a user's status within a community (active/pending), update user type (owner, moderator, user), and manage responses to invitation.

Get: APIs used to retrieve data for one or more communities:

(Note that wherever community approval or ownership is required, a system admin can also perform that task. In addition, community "moderators" can also add, remove, and update users.)

Share methods

The Share methods are used to allow the saving and sharing of queries, datasets, sources, documents, feeds, and other objects that can be encoded using standard JSON notation (or are arbitrary binary objects).

People

The People methods are admin functions used by the 3rd party user management systems (eg Wordpress web-site for the IKANOW SaaS version) to register and update users.  These calls must come from an authenticated IKANOW server or admins and will not work for other users.

Custom

These custom methods are related to running and viewing custom jobs.

GUI integration

The uisetup methods are GUI specific methods for searching, storing, and getting modules (widgets).  Most API users will not need to use these methods