Introduction

The Lateral API

Tools

Lateral Intelligence Platform API Reference - v2

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

API Base URL

https://api-v2.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

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-v2.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.

404 Errors

When a request to a path not in the API is made, a 404 status code will be returned and you will get the following error message:

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

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
keywords(string, optional) lorem If present, return the 25 most relevant documents to the specified keywords. Please note: Performance will drop on this when you have > 500K documents.
Response200
Headers (200) 
Per-Page: 25
Total: 100000
Response (200) 
[
  {
    "id": 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": 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"
  }
]
POST/documentsCreate a Document
Code Sample

Given the text parameter, will create a new document. The id will be generated by the API.

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
Response (201) 
{
  "id": 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 or if invalid JSON was sent.

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

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/{id}Get a Document
Code Sample

Get the document found at the URL specified.

Response201
Response (201) 
{
  "id": 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/{id}Modify 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": "Lorem Ipsum" } Meta data about the document
Response200
Response (200) 
{
  "id": 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" }
DELETE/documents/{id}Delete a Document
Code Sample

Deletes a document given the ID specified in the URL.

NOTE: This will delete any preferences the document has attached to it.

Response201
Response (201) 
{
  "id": 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" }

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
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 id and similarity pairs with the most similar being first.

Parameters
Name Example Description
select_from(Array, optional) [1, 2, 3] Array of IDs to restrict what can be recommended
number(Integer, optional) 10 How many results to return
Response200
Response (200) 
[
  {
    "id": 1,
    "similarity": 0.9
  },
  {
    "id": 2,
    "similarity": 0.7
  },
  {
    "id": 3,
    "similarity": 0.5
  }
]

Similar to text/documents/similar-to-text

Given the text parameter, an object will be returned containing the IDs of similar documents.

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
text(string, required) Fat black cat The text to get similar documents for
select_from(Array, optional) [1, 2, 3] Array of IDs to restrict what can be recommended
number(Integer, optional) 10 How many results to return
Response200
Response (200) 
[
  {
    "id": 1,
    "similarity": 0.9
  },
  {
    "id": 2,
    "similarity": 0.7
  },
  {
    "id": 3,
    "similarity": 0.5
  }
]

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 API too. This will return a user ID that you can use to track 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": 1,
    "created_at": "2015-03-01T18:11:01.360Z",
    "updated_at": "2015-03-01T18:11:01.360Z"
  },
  {
    "id": 2,
    "created_at": "2015-03-03T18:39:01.360Z",
    "updated_at": "2015-03-03T18:39:01.360Z"
  },
]
POST/usersCreate a User
Code Sample

Creates a new user. No data is required, all fields will be generated by the API.

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

User/users/{id}

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

GET/users/{id}Get a User
Code Sample

Get a user by ID.

Response201
Response (201) 
{
  "id": 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/{id}Delete a User
Code Sample

Deletes the user found at the specified URL.

NOTE: This will delete any preferences the user has.

Response201
Response (201) 
{
  "id": 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" }

User Recommendations/users/{user_id}/recommendations

A list of a document recommendations for the specified user.

GET/users/{user_id}/recommendationsGet Recommendations
Code Sample

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

Parameters
Name Example Description
select_from(Array, optional) [1, 2, 3] Array of IDs to restrict what can be recommended
number(Integer, optional) 10 How many results to return
Response200
Response (200) 
[
  {
    "id": 1,
    "similarity": 0.9
  },
  {
    "id": 2,
    "similarity": 0.7
  },
  {
    "id": 3,
    "similarity": 0.5
  }
]
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/{user_id}/preferences

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

GET/users/{user_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_id}Get 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_id}Create 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_id}Delete 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/{cluster_model_id}. Once it is trained, you can get the clusters by calling GET /cluster-models/{cluster_model_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/{cluster_model_id}

A representation of a cluster model.

GET/cluster-models/{cluster_model_id}Get 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/{cluster_model_id}Delete a Cluster Model
Code Sample

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

NOTE: This will delete any clusters the model has attached to it.

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" }

Clusters Collection/cluster-models/{cluster_model_id}/clusters

A list of cluster models.

GET/cluster-models/{cluster_model_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": 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": 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": 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, documents and preferences.

Response204
Response (204) 
An empty response.