Introduction

The Lateral API

Tools

Lateral Intelligence Platform API Reference - v4

Warning: This API is deprecated, this documentation only serves as a reference. Please use v5.

Note: The Clustering and Keyword suggestion subsystems are currently disabled. If you would like to use them, please get in touch.

API Base URL

https://api-v4.lateral.io/

Authentication

Every request must be authenticated with your subscription key. This must be sent as an HTTP header:

Subscription-Key: YOUR_API_KEY

Item IDs

It is possible to set your own IDs for Documents, Users and Tags. This is so that you can use the IDs from your own database in our system without having to save our IDs or create a look-up table. If you don’t care about this, then don’t specify an ID and we’ll generate one for you. Otherwise, when creating a user, for example, you must specify the ID in the URL to set it. So, if you have a user with the ID 94842 then you would send a POST request to /users/94842 to create the user in our system.

Pagination

Requests that return a lot of data, such as GET /users or GET /documents are paginated. To get to the next page use the ?page parameter. To change the number of items per page, use the ?per_page parameter. Pages can have up to 100 items. Example:

https://api-v4.lateral.io/documents/?page=2&per_page=100

We use the proposed RFC-5988 standard for Web linking. GitHub use a very similar method of pagination and their documentation is very in depth about using it so check it out here.

Item Counts

If you’re curious about the count of users or documents you have in the system, you can look at the headers for GET /users or GET /documents. There is a HTTP Header called Total which contains the total number of respective items that are in the API.

Content-based Recommender

The content-based recommender is used by default. It only looks at the content of the documents in order to recommend by document, user or text.

Hybrid Recommender

When recommending by document or user it’s possible to set the use_hybrid flag which will enable recommendations that take into account user preferences (behavioural data) as well as the contents of the documents.

Please Note: The current version of LIP does not train hybrid models automatically. This is due to the fact that in order to create the best recommendations possible we need to set the training parameters based on the dataset. If you want a hybrid model trained, please get in touch with us.

Data Integrity

Due to the design of the API, it is possible that (for a very short time) documents or users may be recommended even though it has already beed deleted through the API. To ensure data integrity, your code should also check that all returned IDs are present in your database. This also applies to tags and the tag suggester. It is important to note that the Lateral API is not designed to be the source of truth for your data.

404 Errors

You will get the following error message:

{
  "message": "API path not found"
}

When a request to a path not in the API is made, a 404 status code will be returned.

API Specification

  • Go
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • Shell

Documents

A document is the item that is recommended. Typically, you will have an existing collection of documents that you must add to the API in order to start recommending the content. At first all documents will need to be sent to the API. Then after that anything new that’s added to your system or any modifications will need to be updated in the API too to keep everything in sync.

Documents Collection/documents

A list of documents. All the fields apart from text will be set by the API. The updated_at field will be updated whenever the document is modified.

GET/documentsGet Documents
Code Sample

Returns a list of all document objects. This is paginated, see the information about pagination at the top of this reference.

Parameters
Name Example Description
fields(Comma-separated list, optional) meta,text Specify which document fields to include in the response. Currently supported values are `text` and `meta`. (Default: `meta,text`)
keywords(string, optional) lorem If present, return the 25 most relevant documents to the specified keywords.
keywords_fields(Comma-separated list, optional) text,meta.title Specifies which fields to search within when using the `keywords` parameter. Can include meta fields using dot notation to denote sub fields. (Default: `text,meta.title`)
Response200

Contains a list of document objects. Returned when a valid request to the API was made.

Headers (200) 
Per-Page: 25
Total: 100000
Response (200) 
[
  {
    "id": "doc-1",
    "text": "lorem ipsum dolor",
    "meta": {
      "title": "Duis aute irure dolor"
    },
    "created_at": "2015-03-01T15:29:26.404Z",
    "updated_at": "2015-03-01T15:29:26.404Z"
  },
  {
    "id": "doc-2",
    "text": "dolor porta dictum",
    "meta": {
      "title": "Ut enim ad minim veniam"
    },
    "created_at": "2015-03-02T15:29:26.412Z",
    "updated_at": "2015-03-02T15:29:26.412Z"
  }
]

Document creation/documents[/:id]

Given the text parameter, will create a new document. To specify your own id, specify it in the URL. Otherwise it will be assigned automatically. The ID can contain alpha-numeric characters, dashes and underscores - a-Z0-9-_.

POST/documents[/:id]Create a Document
Code Sample
Parameters
Name Example Description
text(string, required) Fat black cat The full text of the document
meta(JSON, optional) { "title": "Lorem Ipsum" } Meta data about the document
Response201

The document object that was just saved. Returned when the document has been saved.

Response (201) 
{
  "id": "doc-1",
  "text": "maximus feugiat tincidunt",
  "meta": {
    "title": "Excepteur sint occaecat"
  },
  "created_at": "2015-03-03T13:49:51.640Z",
  "updated_at": "2015-03-03T13:49:51.640Z"
}
Response400

This response is returned when no text parameter is provided, if invalid JSON was sent or if a provided ID is not valid (a-Z0-9-_).

Response (400) 
{ "message": "meta is invalid" }
Response409

Occurs when trying to create a document using an ID that already exists in the dataset.

Response (409) 
{ "message": "Document with the ID 'doc-1' already exists" }

Document/documents/:id

A representation of a document. All the fields apart from text are set by the API. The updated_at field is updated whenever the document is modified.

GET/documents/:idGet a Document
Code Sample

Get the document found at the URL specified.

Response200

The document object. Returned when a valid document was requested.

Response (200) 
  {
    "id": "doc-1",
    "text": "maximus feugiat tincidunt",
    "meta": {
      "title": "Excepteur sint occaecat"
    },
    "created_at": "2015-03-03T13:49:51.640Z",
    "updated_at": "2015-03-03T13:49:51.640Z"
  }
Response404

This response is returned when the document with the id specified was not found.

Response (404) 
{ "message": "Couldn't find Document" }
Response400

This response is returned when validations fails.

Response (400) 
{ "message": "id is invalid" }
PUT/documents/:idModify a Document
Code Sample

Change the text of the document given the ID specified in the URL.

Parameters
Name Example Description
text(string, optional) Fat black cat The updated text of the document
meta(JSON, optional) { "title": "New title" } Meta data about the document
Response200

The document object. Returned when the update has been saved.

Response (200) 
  {
    "id": "doc-1",
    "text": "maximus feugiat tincidunt",
    "meta": {
      "title": "New title"
    },
    "created_at": "2015-03-03T13:49:51.640Z",
    "updated_at": "2015-03-03T13:49:51.640Z"
  }
Response404

This response is returned when the document with the id specified was not found.

Response (404) 
{ "message": "Couldn't find Document" }
Response400

This response is returned when validations fails.

Response (400) 
{ "message": "id is invalid" }
DELETE/documents/:idDelete a Document
Code Sample

Deletes a document given the ID specified in the URL.

Please Note: This will delete any preferences the document has attached to it.
Response200

The document object that was just deleted

Response (200) 
  {
    "id": "doc-1",
    "text": "maximus feugiat tincidunt",
    "meta": {
      "title": "New title"
    },
    "created_at": "2015-03-03T13:49:51.640Z",
    "updated_at": "2015-03-03T13:49:51.640Z"
  }
Response404

This response is returned when the document with the id specified was not found.

Response (404) 
{ "message": "Couldn't find Document" }
Response400

This response is returned when validations fails.

Response (400) 
{ "message": "id is invalid" }

Document Tags Collection/documents/:id/tags

A list of a tags belonging to the document with the id specified in the URL.

GET/documents/:id/tagsGet a Documents Tags
Code Sample

Returns a list of all tags belonging to the document. This is paginated, see the information about pagination at the top of this reference.

Response200

A paginated list of tags

Response (200) 
  [
    {
      "id": "tag-1",
      "created_at": "2015-03-04T09:56:36.045Z"
    },
    {
      "id": "tag-4",
      "created_at": "2015-03-04T09:56:36.045Z"
    }
  ]
Response404

This response is returned when the document is not found.

Response (404) 
{ "message": "Couldn't find Document" }

Suggested Document Tags/documents/:id/tags/suggested

Uses the tag suggester to recommend tags for the current document.

GET/documents/:id/tags/suggestedGet Suggested Tags
Code Sample

Returns a list of suggested tags that are relevant to the document.

Parameters
Name Example Description
number(Integer, optional) 20 How many results to return (Default: 10)
Response200
Response (200) 
  {
    "results": [
      {
        "id": "9vxw88heig",
        "score": 0.733480557394401
      },
      {
        "id": "3rmkum0qk7",
        "score": 0.295686706052547
      },
      {
        "id": "7oaj8yul0q",
        "score": 0.281185408507482
      },
      ...
    ]
  }
Response404

This response is returned when the document is not found.

Response (404) 
{ "message": "Couldn't find Document" }

Document preferences/documents/:id/preferences

Given a document ID that is specified in the URL, an array of preferences will be returned.

GET/documents/:id/preferencesGet Document Preferences
Code Sample

Returns a list of all preference objects belonging to the document. This is paginated, see the information about pagination at the top of this reference.

Response200

A paginated list of preferences

Response (200) 
  [
    {
      "user_id": 5,
      "document_id": 4,
      "created_at": "2015-03-04T09:56:36.045Z",
      "updated_at": "2015-03-04T09:56:36.045Z"
    },
    {
      "user_id": 11,
      "document_id": 4,
      "created_at": "2015-03-04T09:56:36.045Z",
      "updated_at": "2015-03-04T09:56:36.045Z"
    }
  ]
Response404

This response is returned when the user is not found.

Response (404) 
{ "message": "Couldn't find Document" }

Similar to document/documents/:id/similar

Given a document ID that is specified in the URL, an object will be returned containing the IDs of similar documents.

GET/documents/:id/similarGet Similar Documents
Code Sample

Returns an array of recommendation objects with the most similar being first. If using the hybrid recommender there will be a score value which can be used to sort. Otherwise if using the content-based recommender, there will be a similarity value which is between 1 and 0 with 1 being the closest.

Parameters
Name Example Description
fields(Comma-separated list, optional) meta,text Specify which document fields to include in the response. Currently supported values are `text` and `meta`. (Default: ``)
number(Integer, optional) 10 How many results to return
select_from(Array, optional) [1, 2, 3] Array of IDs to restrict what can be recommended
exclude(Array, optional) [1, 2, 3] Array of IDs to exclude from recommendations
unseen_only(Boolean, optional) true Given the user ID, whether to recommend documents the user has already seen (Hybrid only) (Default: true)
use_hybrid(Boolean, optional) false Whether to use the hybrid recommender, defaults to content-based (Default: false)
user_id(String, optional) user-id Recommend similar documents personalised for this user ID (Hybrid only)
Response200

If using the content-based recommender (use_hybrid is not set or is set to false):

Response (200) 
[
  {
    "id": "doc-1",
    "similarity": 0.9
  },
  {
    "id": "doc-2",
    "similarity": 0.7
  },
  {
    "id": "doc-3",
    "similarity": 0.5
  }
]
Response200

If using the hybrid recommender (use_hybrid is set to true), returns a JSON object with keys results, document_ids and user_ids. results is a list of objects with keys id and score. document_ids and user_ids contain a list of objects that represent the document_id and user_id entities that were sent to the recommender. Each object contains id which is the id of the entity and recognised which is true if the recommender is aware of this entity and false if it is not.

Response (200) 
{
  "results": [
    {
      "id": "doc-1",
      "score": 3.14
    },
    {
      "id": "doc-2",
      "score": 0.8
    },
    {
      "id": "doc-3",
      "score": -1.2
    }
  ],
  "document_ids": [{ "id": "doc-1", "recognised": true }],
  "user_ids": [{ "id": "max", "recognised": true }]
}

Extract keywords/documents/:id/keywords

Returns a list of words whose meanings are similar to that of the input document, in descending order of relevance.

GET/documents/:id/keywordsGet Document Keywords
Code Sample

Returns a list of keywords contained within the text along with a score for each indicating the relevance of that keyword. An optional parameter in_text can be specified. It defaults to true but when set to false, the returned list will contain words that are not mentioned in the provided text.

Parameters
Name Example Description
in_text(Boolean, optional) true Ensure keywords are contained in the document text (Default: true)
Response200
Response (200) 
[
  {
    "keyword": "repudiandae",
    "score": 0.0101976318437826
  },
  {
    "keyword": "minima",
    "score": 0.402608834211888
  },
  {
    "keyword": "inventore",
    "score": 0.166240163701894
  },
  {
    "keyword": "rerum",
    "score": 0.824500861679984
  },
  {
    "keyword": "rem",
    "score": 0.548424580906462
  },
  {
    "keyword": "velit",
    "score": 0.459010494414975
  },
  {
    "keyword": "exercitationem",
    "score": 0.687841631465403
  },
  {
    "keyword": "excepturi",
    "score": 0.0181803611178766
  },
  {
    "keyword": "qui",
    "score": 0.111991008244364
  },
  {
    "keyword": "ut",
    "score": 0.576019166497384
  }
]

Similar to text/documents/similar-to-text

Given the text parameter, an object will be returned containing the IDs of similar documents. It is not possible to use this call with the hybrid recommender.

POST/documents/similar-to-textGet Similar to text
Code Sample

Returns an array of id and similarity pairs with the most similar being first.

Parameters
Name Example Description
fields(Comma-separated list, optional) meta,text Specify which document fields to include in the response. Currently supported values are `text` and `meta`. (Default: ``)
number(Integer, optional) 10 How many results to return
select_from(Array, optional) [1, 2, 3] Array of IDs to restrict what can be recommended
exclude(Array, optional) [1, 2, 3] Array of IDs to exclude from recommendations
text(string, required) Fat black cat The text to get similar documents for
Response200
Response (200) 
[
  {
    "id": "1",
    "similarity": 0.9
  },
  {
    "id": "2",
    "similarity": 0.7
  },
  {
    "id": "3",
    "similarity": 0.5
  }
]

Similar to IDs/documents/similar-to-ids

Given a list of document IDs as the ids parameter, an object will be returned containing the IDs of similar documents.

POST/documents/similar-to-idsGet Similar to IDs
Code Sample

Returns an array of recommendation objects with the most similar being first. If using the hybrid recommender there will be a score value which can be used to sort. Otherwise if using the content-based recommender, there will be a similarity value which is between 1 and 0 with 1 being the closest.

Parameters
Name Example Description
fields(Comma-separated list, optional) meta,text Specify which document fields to include in the response. Currently supported values are `text` and `meta`. (Default: ``)
ids(Array, required) ['doc-1', 'doc-2', 'doc-3'] Array of document IDs to get similar documents to
number(Integer, optional) 10 How many results to return
select_from(Array, optional) [1, 2, 3] Array of IDs to restrict what can be recommended
exclude(Array, optional) [1, 2, 3] Array of IDs to exclude from recommendations
unseen_only(Boolean, optional) true Given the user ID, whether to recommend documents the user has already seen (Hybrid only) (Default: true)
use_hybrid(Boolean, optional) false Whether to use the hybrid recommender, defaults to content-based (Default: false)
user_id(String, optional) user-id Recommend similar documents personalised for this user ID (Hybrid only)
Response200

If using the content-based recommender (use_hybrid is not set or is set to false):

Response (200) 
[
  {
    "id": "doc-1",
    "similarity": 0.9
  },
  {
    "id": "doc-2",
    "similarity": 0.7
  },
  {
    "id": "doc-3",
    "similarity": 0.5
  }
]
Response200

If using the hybrid recommender (use_hybrid is set to true), returns a JSON object with keys results, recognised and unrecognised. results is a list of objects with keys id and score. recognised and unrecognised may have keys document_id and user_id indicating whether the provided user and document ids exist for that dataset.

Response (200) 
{
  "results": [
    {
      "id": "doc-1",
      "score": 3.14
    },
    {
      "id": "doc-2",
      "score": 0.8
    },
    {
      "id": "doc-3",
      "score": -1.2
    }
  ],
  "recognised": {
    "user_id": "henry",
    "document_id": ['doc-1', 'doc-2', 'doc-3']
  },
  "unrecognised": {}
}

Document IDs Collection/documents/ids

Returns an array of all document IDs.

GET/documents/idsGet IDs
Code Sample

Returns an array of all document IDs.

Response200
Response (200) 
[
  "doc-1",
  "doc-2",
  "doc-3"
]

Uses the hybrid recommender to decide popularity and returns a list of popular documents.

GET/documents/popularGet Popular
Code Sample

Returns an array of popular id and similarity pairs.

Parameters
Name Example Description
fields(Comma-separated list, optional) meta,text Specify which document fields to include in the response. Currently supported values are `text` and `meta`. (Default: ``)
number(Integer, optional) 10 How many results to return
select_from(Array, optional) [1, 2, 3] Array of IDs to restrict what can be recommended
exclude(Array, optional) [1, 2, 3] Array of IDs to exclude from recommendations
Response200

A list of popular documents in the hybrid recommender format. A JSON object with keys results, recognised and unrecognised. results is a list of objects with keys document id and score.

Response (200) 
  {
    "results": [
      {
        "id": "doc-1",
        "score": 3.14
      },
      {
        "id": "doc-2",
        "score": 0.8
      },
      {
        "id": "doc-3",
        "score": -1.2
      }
    ],
    "document_ids": [],
    "user_ids": []
  }

Keywords

The keyword extractor returns a list of words whose meanings are similar to that of the input document, in descending order of relevance. The system does not need to train on labelled examples, since it uses the word vectoriser to find keywords.

Simliar keywords/keywords/

Uses the hybrid recommender to decide popularity and returns a list of popular documents.

POST/keywords/Simliar keywords to text
Code Sample

Given the sent text, returns a list of keywords contained within the text along with a score for each indicating the relevance of that keyword. An optional parameter in_text can be specified. It defaults to true but when set to false, the returned list will contain words that are not mentioned in the provided text.

Parameters
Name Example Description
text(string, required) Fat black cat The text to get keywords from
in_text(Boolean, optional) true Ensure keywords are contained in the document text (Default: true)
Response200
Response (200) 
[
  {
    "keyword": "repudiandae",
    "score": 0.0101976318437826
  },
  {
    "keyword": "minima",
    "score": 0.402608834211888
  },
  {
    "keyword": "inventore",
    "score": 0.166240163701894
  },
  {
    "keyword": "rerum",
    "score": 0.824500861679984
  },
  {
    "keyword": "rem",
    "score": 0.548424580906462
  },
  {
    "keyword": "velit",
    "score": 0.459010494414975
  },
  {
    "keyword": "exercitationem",
    "score": 0.687841631465403
  },
  {
    "keyword": "excepturi",
    "score": 0.0181803611178766
  },
  {
    "keyword": "qui",
    "score": 0.111991008244364
  },
  {
    "keyword": "ut",
    "score": 0.576019166497384
  }
]

Tags

A tag represents a tag in your system. Tags are assigned to documents and we use them to teach our system the relationships between documents.

Tags/tags

Uses the hybrid recommender to decide popularity and returns a list of popular documents.

GET/tagsGet Tags
Code Sample

Returns a list of all tag objects. This is paginated, see the information about pagination at the top of this reference.

Response200

A paginated list of tags.

Headers (200) 
Per-Page: 25
Total: 100000
Response (200) 
[
  {
    "id": "tag-1",
    "created_at": "2015-03-01T18:11:01.360Z"
  },
  {
    "id": "tag-2",
    "created_at": "2015-03-03T18:39:01.360Z"
  },
]

Tag creation/tags[/:id]

Creates a new tag. To specify your own id, specify it in the URL. Otherwise it will be assigned automatically. The ID can contain alpha-numeric characters, dashes and underscores - a-Z0-9-_.

POST/tags[/:id]Create a Tag
Code Sample
Response201

The tag that was just created

Response (201) 
{
  "id": "tag-1",
  "created_at": "2015-03-03T18:39:01.360Z"
}
Response400

This response is returned the provided ID is not valid (a-Z0-9-_).

Response (400) 
{ "message": "id is invalid" }
Response409

Occurs when trying to create a tag using an ID that already exists in the dataset.

Response (409) 
{ "message": "Tag with the ID 'tag-1' already exists" }

Tag/tags/:id

A representation of a tag. There is no data to set for a tag, therefore they cannot be edited.

GET/tags/:idGet a Tag
Code Sample

Get a tag by ID.

Response200

The tag that was requested

Response (200) 
{
  "id": "tag-1",
  "created_at": "2015-03-03T18:39:01.360Z"
}
Response404

This response is returned when the tag with the id specified was not found.

Response (404) 
{ "message": "Couldn't find Tag" }
Response400

This response is returned when validations fails.

Response (400) 
{ "message": "id is invalid" }
DELETE/tags/:idDelete a Tag
Code Sample

Deletes the tag found at the specified URL.

Response200

The tag that was just deleted

Response (200) 
{
  "id": "tag-1",
  "created_at": "2015-03-03T18:39:01.360Z"
}
Response404

This response is returned when the tag with the id specified was not found.

Response (404) 
{ "message": "Couldn't find Tag" }
Response400

This response is returned when validations fails.

Response (400) 
{ "message": "id is invalid" }

Tag/tags/:id/documents

Returns a list of all documents that are tagged with this tag.

GET/tags/:id/documentsList documents
Code Sample

List all documents that are tagged with this tag.

Parameters
Name Example Description
fields(Comma-separated list, optional) meta,text Specify which document fields to include in the response. Currently supported values are `text` and `meta`. (Default: `text,meta`)
Response200
Response (200) 
[
  {
    "id": "066b883b-bbea-4b4c-9081-91d0c0933625",
    "text": "Lorem ipsum",
    "meta": {
      "title": "Ut aut ex delectus voluptatem sit.",
      "date": {},
      "author": "Dr. Donnell Kling"
    },
    "created_at": "2016-08-02T14:33:01.779Z",
    "updated_at": "2016-08-02T14:33:01.779Z"
  },
  {
    "id": "27e68201-181e-40f6-a615-d7db1e803b03",
    "text": "Lorem ipsum",
    "meta": {
      "title": "Ratione laborum eum.",
      "date": {},
      "author": "Arvel Boyer"
    },
    "created_at": "2016-08-02T14:33:01.779Z",
    "updated_at": "2016-08-02T14:33:01.779Z"
  },
  {
    "id": "29550c19-cb43-42ed-9dc4-48eaa883f22c",
    "text": "Lorem ipsum",
    "meta": {
      "title": "Et id tempore expedita quos dolor.",
      "date": {},
      "author": "Geo Lowe"
    },
    "created_at": "2016-08-02T14:33:01.779Z",
    "updated_at": "2016-08-02T14:33:01.779Z"
  },
  ....
]
Response404

This response is returned when the tag with the id specified was not found.

Response (404) 
{ "message": "Couldn't find Tag" }
Response400

This response is returned when validations fails.

Response (400) 
{ "message": "id is invalid" }

Suggested Document Tags/tags/recommend-by-text

Uses the tag suggester to recommend tags for the given text.

POST/tags/recommend-by-textGet Suggested Tags
Code Sample

Returns a list of suggested tags that are relevant to the input text.

Parameters
Name Example Description
text(string, required) Fat black cat The text to get tag recommendations for
number(Integer, optional) 20 How many results to return (Default: 10)
Response200
Response (200) 
  {
    "results": [
      {
        "id": "9vxw88heig",
        "score": 0.733480557394401
      },
      {
        "id": "3rmkum0qk7",
        "score": 0.295686706052547
      },
      {
        "id": "7oaj8yul0q",
        "score": 0.281185408507482
      },
      ...
    ]
  }

Taggings

Taggings are how you add tags to documents.

Tagging/documents/:document_id/tags/:tag_id

A tagging is the combination of a tag and document.

POST/documents/:document_id/tags/:tag_idCreate a Tagging
Code Sample

Given a valid document_id specified in the URL, creates a tagging. If the tag with the ID tag_id doesn’t exist then it will be created automatically.

Response204

The response is empty

Response400

This response is returned if the tag_id is not valid (a-Z0-9-_).

Response (400) 
{ "message": "tag_id is invalid" }
Response404

This response is returned if the document is not found.

Response (404) 
{ "message": "Couldn't find Document" }
DELETE/documents/:document_id/tags/:tag_idDelete a Tagging
Code Sample

Deletes the tagging found at the specified URL.

Response204
Response (204) 
An empty response.
Response404

This response is returned when the tag, document or tagging is not found. The possible message values are:

  • Couldn't find User

  • Couldn't find Document

  • Tagging doesn't exist

Response (404) 
{ "message": "Couldn't find Document" }

Users

A user is a very simple representation of a user. It’s used to store behavioural data and more importantly to get user-tailored recommendations. No user data is stored apart from the ID and some timestamps. When you create users in your system, you’ll need to send a request to create a user in the Lateral API too. This will then allow you to store the users preferences.

Users Collection/users

A list of users.

GET/usersGet Users
Code Sample

Returns a list of all user objects. This is paginated, see the information about pagination at the top of this reference.

Response200
Headers (200) 
Per-Page: 25
Total: 100000
Response (200) 
[
  {
    "id": "user-1",
    "created_at": "2015-03-01T18:11:01.360Z",
    "updated_at": "2015-03-01T18:11:01.360Z"
  },
  {
    "id": "user-2",
    "created_at": "2015-03-03T18:39:01.360Z",
    "updated_at": "2015-03-03T18:39:01.360Z"
  }
]

User creation/users[/:id]

Creates a new user. To specify your own id, specify it in the URL. Otherwise it will be assigned automatically. The ID can contain alpha-numeric characters, dashes and underscores - a-Z0-9-_.

POST/users[/:id]Create a User
Code Sample
Response201
Response (201) 
{
  "id": "user-1",
  "created_at": "2015-03-03T18:39:01.360Z",
  "updated_at": "2015-03-03T18:39:01.360Z"
}
Response400

This response is returned the provided ID is not valid (a-Z0-9-_).

Response (400) 
{ "message": "id is invalid" }
Response409

Occurs when trying to create a user using an ID that already exists in the dataset.

Response (409) 
{ "message": "User with the ID 'user-1' already exists" }

User/users/:id

A representation of a user. There is no data to set for a user, therefore they cannot be edited.

GET/users/:idGet a User
Code Sample

Get a user by ID.

Response201
Response (201) 
{
  "id": "user-1",
  "created_at": "2015-03-03T18:39:01.360Z",
  "updated_at": "2015-03-03T18:39:01.360Z"
}
Response404

This response is returned when the user with the id specified was not found.

Response (404) 
{ "message": "Couldn't find User" }
Response400

This response is returned when validations fails.

Response (400) 
{ "message": "id is invalid" }
DELETE/users/:idDelete a User
Code Sample

Deletes the user found at the specified URL.

Please Note: This will delete any preferences the user has unless the `merge_into` parameter is set.
Parameters
Name Example Description
merge_into(string, optional) user-124 If specified, the preferences of the user being deleted will be merged into the user with this ID
Response200
Response (200) 
{
  "id": "user-1",
  "created_at": "2015-03-03T18:39:01.360Z",
  "updated_at": "2015-03-03T18:39:01.360Z"
}
Response200

If merge_into is specified then the response will contain merged_into which references the ID of the user that just had preferences merged into it.

Response (200) 
{
  "id": "user-1",
  "created_at": "2015-03-03T18:39:01.360Z",
  "updated_at": "2015-03-03T18:39:01.360Z",
  "merged_into": "user-124"
}
Response404

This response is returned when the user with the id or merge_into ID specified was not found.

Response (404) 
{ "message": "Couldn't find User" }
Response400

This response is returned when validations fails.

Response (400) 
{ "message": "id is invalid" }

User Recommendations/users/:id/recommendations

A list of a document recommendations for the specified user.

GET/users/:id/recommendationsGet Recommendations
Code Sample

Returns an array of recommendation objects with the most similar being first. If using the hybrid recommender there will be a score value which can be used to sort. Otherwise if using the content-based recommender, there will be a similarity value which is between 1 and 0 with 1 being the closest.

Parameters
Name Example Description
fields(Comma-separated list, optional) meta,text Specify which document fields to include in the response. Currently supported values are `text` and `meta`. (Default: ``)
number(Integer, optional) 10 How many results to return
select_from(Array, optional) [1, 2, 3] Array of IDs to restrict what can be recommended
exclude(Array, optional) [1, 2, 3] Array of IDs to exclude from recommendations
unseen_only(Boolean, optional) true Whether to recommend documents the user has already seen (Hybrid only) (Default: true)
use_hybrid(Boolean, optional) false Whether to use the hybrid recommender or not (Default: false)
Response200

If using the content-based recommender (use_hybrid is not set or is set to false):

Response (200) 
[
  {
    "id": "doc-1",
    "similarity": 0.9
  },
  {
    "id": "doc-2",
    "similarity": 0.7
  },
  {
    "id": "doc-3",
    "similarity": 0.5
  }
]
Response200

If using the hybrid recommender (use_hybrid is set to true), returns a JSON object with keys results, document_ids and user_ids. results is a list of objects with keys id and score. document_ids and user_ids contain a list of objects that represent the document_id and user_id entities that were sent to the recommender. Each object contains id which is the id of the entity and recognised which is true if the recommender is aware of this entity and false if it is not.

Response (200) 
{
  "results": [
    {
      "id": "doc-1",
      "score": 3.14
    },
    {
      "id": "doc-2",
      "score": 0.8
    },
    {
      "id": "doc-3",
      "score": -1.2
    }
  ],
  "document_ids": [{ "id": "doc-1", "recognised": true }, { "id": "doc-2", "recognised": true }],
  "user_ids": [{ "id": "max", "recognised": true }]
}
Response404

This response is returned when the user with the id specified was not found.

Response (404) 
{ "message": "Couldn't find User" }
Response400

This response is returned when validations fails.

Response (400) 
{ "message": "id is invalid" }

Preferences

Preferences are users behavioural data. A preference is a combination of a user and a document, meaning it’s a way of registering a users interest.

Preferences Collection/users/:id/preferences

A list of a preferences belonging to the user with the id specified in the URL.

GET/users/:id/preferencesGet Preferences
Code Sample

Returns a list of all preference objects belonging to the user.

Response200
Response (200) 
[
  {
    "user_id": 2,
    "document_id": 2,
    "created_at": "2015-03-04T09:56:36.045Z",
    "updated_at": "2015-03-04T09:56:36.045Z"
  },
  {
    "user_id": 2,
    "document_id": 4,
    "created_at": "2015-03-04T09:56:36.045Z",
    "updated_at": "2015-03-04T09:56:36.045Z"
  }
]
Response404

This response is returned when the user is not found.

Response (404) 
{ "message": "Couldn't find User" }

Preference/users/:user_id/preferences/:document_id

Preferences are the combination of a user and document.

GET/users/:user_id/preferences/:document_idGet a Preference
Code Sample

Get a preference by ID.

Response201
Response (201) 
{
  "user_id": 2,
  "document_id": 2,
  "created_at": "2015-03-04T09:56:36.045Z",
  "updated_at": "2015-03-04T09:56:36.045Z"
}
Response404

This response is returned when the user, document or preference is not found. The possible message values are:

  • Couldn't find User

  • Couldn't find Document

  • Couldn't find all Preferences

Response (404) 
{ "message": "Couldn't find Document" }
POST/users/:user_id/preferences/:document_idCreate a Preference
Code Sample

Given a valid user_id and document_id specified in the URL, creates a preference.

Response201
Response (201) 
{
  "user_id": 2,
  "document_id": 2,
  "created_at": "2015-03-04T09:56:36.045Z",
  "updated_at": "2015-03-04T09:56:36.045Z"
}
Response404

This response is returned when the user or document is not found. The possible message values are:

  • Couldn't find User

  • Couldn't find Document

Response (404) 
{ "message": "Couldn't find Document" }
DELETE/users/:user_id/preferences/:document_idDelete a Preference
Code Sample

Deletes the preference found at the specified URL.

Response200
Response (200) 
{
  "user_id": 2,
  "document_id": 2,
  "created_at": "2015-03-04T09:56:36.045Z",
  "updated_at": "2015-03-04T09:56:36.045Z"
}
Response404

This response is returned when the user, document or preference is not found. The possible message values are:

  • Couldn't find User

  • Couldn't find Document

  • Couldn't find all Preferences

Response (404) 
{ "message": "Couldn't find Document" }

Clustering

A cluster model is a group of clusters. Clustering is performed asynchronously so when you POST to /cluster-models you are creating a cluster model which is then queued to be processed. A cluster model contains an attribute called status which will be either trained or training. If the model is still training you will need to wait until you can access its clusters. Read more in depth cluster documentation here.

Cluster Models Collection/cluster-models

A list of cluster models.

GET/cluster-modelsGet Cluster Models
Code Sample

Returns a list of all cluster model objects. This is paginated, see the information about pagination at the top of this reference.

Response200
Headers (200) 
Per-Page: 25
Total: 100000
Response (200) 
[
  {
    "id": 6,
    "number_clusters": 10,
    "created_at": "2015-07-11T11:02:34.910Z",
    "status": "trained"
  },
  {
    "id": 22,
    "number_clusters": 20,
    "created_at": "2015-09-17T15:08:37.940Z",
    "status": "trained"
  }
]
POST/cluster-modelsCreate a Cluster Model
Code Sample

Given the number_clusters a cluster model will be created and the training queued. The status of the training is displayed as either training or trained. When the training is complete the status attribute will say trained. You can check the status of a cluster model by calling GET /cluster-models/:id. Once it is trained, you can get the clusters by calling GET /cluster-models/:id/clusters.

Parameters
Name Example Description
number_clusters(integer, required) 10 How many clusters to group the documents in to (between 2 and 1000)
Response201
Response (201) 
{
  "id": 6,
  "number_clusters": 10,
  "created_at": "2015-09-17T15:08:37.940Z",
  "status": "trained"
}
Response400

This response is returned when no text parameter is provided or if invalid JSON was sent.

Response (400) 
{ "message": "meta is invalid" }

Cluster Model/cluster-models/:id

A representation of a cluster model.

GET/cluster-models/:idGet a Cluster Model
Code Sample

Get the cluster model found at the URL specified.

Response201
Response (201) 
{
  "id": 6,
  "number_clusters": 10,
  "created_at": "2015-09-17T15:08:37.940Z",
  "status": "trained"
}
Response404

This response is returned when the cluster model with the id specified was not found.

Response (404) 
{ "message": "Couldn't find DocumentClusterModel" }
Response400

This response is returned when validations fails.

Response (400) 
{ "message": "id is invalid" }
DELETE/cluster-models/:idDelete a Cluster Model
Code Sample

Deletes a cluster model given the ID specified in the URL.

Please Note: This will delete any clusters the model has attached to it.
Response200
Response (200) 
{
  "id": 6,
  "number_clusters": 10,
  "created_at": "2015-09-17T15:08:37.940Z",
  "status": "trained"
}
Response404

This response is returned when the cluster model with the id specified was not found.

Response (404) 
{ "message": "Couldn't find DocumentClusterModel" }
Response400

This response is returned when validations fails.

Response (400) 
{ "message": "id is invalid" }

Clusters Collection/cluster-models/:id/clusters

A list of cluster models.

GET/cluster-models/:id/clustersGet Clusters
Code Sample

Given the id of a cluster model in the URL, returns a list of cluster IDs belonging to that cluster model.

Response200
Response (200) 
[ 0, 1, 2, 3, 4 ]

Clusters Documents Collection/cluster-models/:cluster_model_id/clusters/:cluster_id/documents

GET/cluster-models/:cluster_model_id/clusters/:cluster_id/documentsGet Clusters Documents
Code Sample

Given the id of a cluster model and the cluster_id of a cluster in the URL, returns a list of document IDs belonging to that cluster.

Response200
Response (200) 
[ 51, 52, 53, 54, 55 ]

Clusters Words Collection/cluster-models/:cluster_model_id/clusters/:cluster_id/words

GET/cluster-models/:cluster_model_id/clusters/:cluster_id/wordsGet Clusters Words
Code Sample

Given the id of a cluster model and the cluster_id of a cluster in the URL, returns a list of word objects belonging to that cluster.

Response200
Response (200) 
[
  {
    "word": "aut",
    "importance": 0.400776
  },
  {
    "word": "ut",
    "importance": 0.77988
  },
  {
    "word": "deserunt",
    "importance": 0.845748
  },
  {
    "word": "ullam",
    "importance": 0.583229
  },
  {
    "word": "nesciunt",
    "importance": 0.942877
  }
]

Clusters Word Cloud/cluster-models/:cluster_model_id/clusters/:cluster_id/word-cloud

GET/cluster-models/:cluster_model_id/clusters/:cluster_id/word-cloudGet Clusters Word Cloud
Code Sample

Given the id of a cluster model and the cluster_id of a cluster in the URL, returns an image of a word cloud that represents the cluster.

Request batching

Request batching/batch

POST/batchBatch requests
Code Sample

The API supports request batching of any request. You can use this by creating a JSON object representing each request you want to make. Each object requires a method, url, params and headers. The way the API works at the moment means that you need to send your subscription key with every request. A batch may contain up to 100 request objects. So if you want to for example add multiple documents then you would create an array of objects like this:

[
  { method: 'POST',
    url: '/documents',
    params: { text: 'fat black cat'},
    headers: { "Subscription-Key": YOUR_API_KEY } },
  { method: 'POST',
    url: '/documents',
    params: { text: 'sat on the mat'},
    headers: { "Subscription-Key": YOUR_API_KEY } },
  { method: 'POST',
    url: '/documents',
    params: { text: 'wearing a hat'},
    headers: { "Subscription-Key": YOUR_API_KEY } },
    [...]
]

This array of objects then needs to be sent to the API with the parameter name ops.

Parameters
Name Example Description
ops(boolean, required) [{}] Array of objects as defined above, max length of 100
sequential(boolean, required) true This doesn't do anything right now but will be used to define if requests are run in parallel or not
Response200

An array of the same length will be returned with the response from each request.

Response (200) 
{
  "results": [{
    "body": {
      "id": "doc-77",
      "text": "fat black cat",
      "meta": {},
      "created_at": "2015-07-06T17:07:07.399Z",
      "updated_at": "2015-07-06T17:07:07.399Z"
    },
    "headers": {
      "Content-Type": "application/json",
      "Content-Length": "126"
    },
    "status": 201
  },
  {
    "body": {
      "id": "doc-78",
      "text": "sat on the mat",
      "meta": {},
      "created_at": "2015-07-06T17:07:07.408Z",
      "updated_at": "2015-07-06T17:07:07.408Z"
    },
    "headers": {
      "Content-Type": "application/json",
      "Content-Length": "126"
    },
    "status": 201
  },
  {
    "body": {
      "id": "doc-79",
      "text": "wearing a hat"
      "meta": {},
      "created_at": "2015-07-06T17:07:07.412Z",
      "updated_at": "2015-07-06T17:07:07.412Z"
    },
    "headers": {
      "Content-Type": "application/json",
      "Content-Length": "126"
    },
    "status": 201
  }
  [...]
  ]
}
Response422

This is returned when a malformed request is made.

Response (422) 
{ "message": "Sequential flag is currently required" }

Delete all data

Delete all data/delete-all-data

DELETE/delete-all-dataDelete all data
Code Sample

Be careful with this! It will delete all of your data; users, tags, clusters, documents and preferences.

Response204
Response (204) 
An empty response.