Introduction

The Lateral API

Tools

Lateral Intelligence Platform API Reference - v6

Warning: This API is no longer online, this documentation only serves as a reference. Get in touch for more information.

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.

Reserved words

Due to the structure of the API there are several reserved words that cannot be used as IDs for documents or tags.

  • /documents/ids

  • /documents/by-keyword

  • /documents/filtered

  • /documents/popular

  • /documents/similar-to-ids

  • /documents/similar-to-text

  • /tags/recommend-by-text

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

Please note: in v6 keyword search has been moved to the /documents/by-keyword endpoint.

Parameters
Name Example Description
fields(Comma-separated list, optional) meta,text,published_at,tags Specify which document fields to include in the response. (Default: `meta,text`)
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",
    "published_at": "2012-03-02T15: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",
    "published_at": "2015-03-03T13:49:51.640Z"
  }
]

Filtered documents/documents/filtered

POST/documents/filteredGet filtered documents
Code Sample

This endpoint allows you to query the Nearest Neighbours API directly so that you can specify a filter parameter in order to query your documents. See filtering for more information.

Parameters
Name Example Description
fields(string, optional) text,meta,published_at,tags Which fields to return back in the results
filter(string, optional) tagged with 'tag_0' The filter string
sort_by(string, optional) published_at The field to sort by, currently only published at is supported
sort_order(string, optional) desc The order to sort date by, `desc` or `asc`
offset(integer, optional) 0
limit(integer, optional) 25
Response200
Response (200) 
[
  {
    "id": "1",
    "published_at": "2017-01-01T00:00:00Z",
    "meta": {
      "author": "Max"
    }
  },
  {
    "id": "2",
    "published_at": "2017-01-01T00:00:00Z",
    "meta": {
      "author": "Steve"
    }
  },
  {
    "id": "3",
    "published_at": "2017-01-01T00:00:00Z",
    "meta": {
      "author": "Felix"
    }
  }
]

Query Elasticsearch/documents/by-keyword

POST/documents/by-keywordQuery Elasticsearch
Code Sample

We send all your documents to Elasticsearch so that they can be searched. In order to query Elasticsearch you need to use the /documents/by-keyword endpoint. We take the es_query parameter which is a JSON object and send a slightly modified version the /_search endpoint of the elastic search index. The format of the es_query JSON object is described here: Request Body Search. We modify the JSON object because we only expose certain features of the Request Body Search. These are:

We also expand the documents in a similar manner to the /documents endpoint so the fields parameter can be used. We combine the results with the score. We return the aggregations and hits keys from the Elasticsearch response. We also modify the hits.hits array to include the original documents from LIP. These documents respond to the fields parameter in the same way that /documents does. We also combine the _score object with the document.

Parameters
Name Example Description
fields(String, optional) text,meta,tags Which fields to return back in the results
es_query(JSON, required) { "query": { "simple_query_string": { "query": "YOUR QUERY" } } } The ES Query to send, see above
Response200
Response (200) 
{
  "hits": {
    "total": 35045,
    "max_score": 19.637716,
    "hits": [
      {
        "id": "2748672",
        "meta": {
          "url": "http://lateral.io",
          "image": "http://assets.lateral.io/logo.png",
        },
        "published_at": "2015-04-20T12:23:06+00:00",
        "_score": 19.637716,
        "tags": [
          "authors_2624",
          "feed_sources_69"
        ]
      },
      {
        "id": "5446128",
        "meta": {
          "url": "",
          "image": ""
        },
        "published_at": "2016-05-25T12:00:02+00:00",
        "_score": 15.6987,
        "tags": [
          "feed_sources_69"
        ]
      },
      ...
    ]
  },
  "aggregations": {
    "tags": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 36133,
      "buckets": [
        {
          "key": "feed_sources_69",
          "doc_count": 8696
        },
        {
          "key": "feed_sources_61",
          "doc_count": 4332
        },
        ...
      ]
    }
  }
}

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
published_at(string (strict RFC3339 date), optional) 2017-07-25T00:00:00Z When the document was published, used for filtering
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",
  "published_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",
    "published_at": "2011-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
published_at(string (strict RFC3339 date), optional) 2017-07-25T00:00:00Z When the document was published, used for filtering
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",
    "published_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",
    "published_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",
      "type": "category",
      "meta": {
        "url": "http://lateral.io/"
      },
      "created_at": "2015-03-04T09:56:36.045Z"
    },
    {
      "id": "tag-4",
      "type": "category",
      "meta": {
        "url": "http://lateral.io/"
      },
      "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. See here for more information about the filter parameter.

Parameters
Name Example Description
fields(Comma-separated list, optional) meta,text,published_at,tags Specify which document fields to include in the response.
filter(string, optional) tagged with 'tag_0' Note: This can only be used if use_hybrid=false. The filter string
number(Integer, optional) 10 How many results to return
select_from(Array[String], optional) ["id-1", "id-2", "id-3"] Note: This can only be used if use_hybrid=true. Array of IDs to only recommendation from
exclude(Array[String], optional) ["id-1", "id-2", "id-3"] Note: This can only be used if use_hybrid=true. 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 }]
}

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. See here for more information about the filter parameter.

Parameters
Name Example Description
fields(Comma-separated list, optional) meta,text,published_at,tags Specify which document fields to include in the response.
filter(string, optional) tagged with 'tag_0' The filter string
number(Integer, optional) 10 How many results to return
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. See here for more information about the filter parameter.

Parameters
Name Example Description
fields(Comma-separated list, optional) meta,text,published_at,tags Specify which document fields to include in the response.
filter(string, optional) tagged with 'tag_0' Note: This can only be used if use_hybrid=false. The filter string
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[String], optional) ["id-1", "id-2", "id-3"] Note: This can only be used if use_hybrid=true. Array of IDs to restrict what can be recommended
exclude(Array[String], optional) ["id-1", "id-2", "id-3"] Note: This can only be used if use_hybrid=true. 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,published_at,tags Specify which document fields to include in the response.
number(Integer, optional) 10 How many results to return
select_from(Array[String], optional) ["id-1", "id-2", "id-3"] Array of IDs to restrict what can be recommended
exclude(Array[String], optional) ["id-1", "id-2", "id-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": []
  }

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.

Parameters
Name Example Description
type(string, optional) author If specified will only return tags of this `type`
Response200

A paginated list of tags.

Headers (200) 
Per-Page: 25
Total: 100000
Response (200) 
[
  {
    "id": "tag-1",
    "type": "author",
    "meta": {
      "url": "http://lateral.io/"
    },
    "created_at": "2015-03-01T18:11:01.360Z"
  },
  {
    "id": "tag-2",
    "type": "author",
    "meta": {
      "url": "http://lateral.io/"
    },
    "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
Parameters
Name Example Description
meta(JSON, optional) { "title": "Lorem Ipsum" } Meta data about the tag
type(string, optional) author A type to logically separate tags for filtering in `/tags`
Response201

The tag that was just created

Response (201) 
{
  "id": "tag-1",
  "type": "category",
  "meta": {
    "url": "http://lateral.io/"
  },
  "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" }
PUT/tags[/:id]Modify a Tag
Code Sample

Change the meta or type of the tag given the ID specified in the URL.

Parameters
Name Example Description
meta(JSON, optional) { "title": "Lorem Ipsum" } Meta data about the tag
type(string, optional) author A type to logically separate tags for filtering in `/tags`
Response200

The tag that was just updated

Response (200) 
{
  "id": "tag-1",
  "type": "category",
  "meta": {
    "url": "http://lateral.io/"
  },
  "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": "meta is invalid" }

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",
  "type": "author",
  "meta": {
    "name": "Max"
  },
  "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",
  "type": "category",
  "meta": {
    "url": "http://lateral.io/"
  },
  "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,published_at,tags Specify which document fields to include in the response.
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",
    "published_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",
    "published_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",
    "published_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,published_at,tags Specify which document fields to include in the response.
number(Integer, optional) 10 How many results to return
select_from(Array[String], optional) ["id-1", "id-2", "id-3"] Array of IDs to restrict what can be recommended
exclude(Array[String], optional) ["id-1", "id-2", "id-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" }

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 } },
    [...]
]

Please note: it is not possible to use URL parameters in the url section of the ops. You must provide the parameters in the params object.

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",
      "published_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",
      "published_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",
      "published_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, documents and preferences.

Response204
Response (204) 
An empty response.