https://api-v2.lateral.io/
Every request must be authenticated with your subscription key. This must be sent as an HTTP header:
Subscription-Key: YOUR_API_KEY
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.
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.
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"
}
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.
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.
Returns a list of all document objects. This is paginated, see the information about pagination at the top of this reference.
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. |
200
Per-Page: 25
Total: 100000
[
{
"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"
}
]
Given the text
parameter, will create a new document. The id
will be generated by the API.
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 |
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"
}
400
This response is returned when no text
parameter is provided or if invalid JSON was sent.
{ "message": "meta is invalid" }
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 the document found at the URL specified.
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"
}
404
This response is returned when the document with the id
specified was not found.
{ "message": "Couldn't find Document" }
400
This response is returned when validations fails.
{ "message": "id is invalid" }
Change the text
of the document given the ID specified in the URL.
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 |
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"
}
404
This response is returned when the document with the id
specified was not found.
{ "message": "Couldn't find Document" }
400
This response is returned when validations fails.
{ "message": "id is invalid" }
Deletes a document given the ID specified in the URL.
NOTE: This will delete any preferences the document has attached to it.
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"
}
404
This response is returned when the document with the id
specified was not found.
{ "message": "Couldn't find Document" }
400
This response is returned when validations fails.
{ "message": "id is invalid" }
Given a document ID that is specified in the URL, an array of preferences will be returned.
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.
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"
}
]
404
This response is returned when the user is not found.
{ "message": "Couldn't find Document" }
Given a document ID that is specified in the URL, an object will be returned containing the IDs of similar documents.
Returns an array of id
and similarity
pairs with the most similar being first.
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 |
200
[
{
"id": 1,
"similarity": 0.9
},
{
"id": 2,
"similarity": 0.7
},
{
"id": 3,
"similarity": 0.5
}
]
Given the text
parameter, an object will be returned containing the IDs of similar documents.
Returns an array of id
and similarity
pairs with the most similar being first.
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 |
200
[
{
"id": 1,
"similarity": 0.9
},
{
"id": 2,
"similarity": 0.7
},
{
"id": 3,
"similarity": 0.5
}
]
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.
A list of users.
Returns a list of all user objects. This is paginated, see the information about pagination at the top of this reference.
200
Per-Page: 25
Total: 100000
[
{
"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"
},
]
Creates a new user. No data is required, all fields will be generated by the API.
201
{
"id": 1,
"created_at": "2015-03-03T18:39:01.360Z",
"updated_at": "2015-03-03T18:39:01.360Z"
}
A representation of a user. There is no data to set for a user, therefore they cannot be edited.
Get a user by ID.
201
{
"id": 1,
"created_at": "2015-03-03T18:39:01.360Z",
"updated_at": "2015-03-03T18:39:01.360Z"
}
404
This response is returned when the user with the id
specified was not found.
{ "message": "Couldn't find User" }
400
This response is returned when validations fails.
{ "message": "id is invalid" }
Deletes the user found at the specified URL.
NOTE: This will delete any preferences the user has.
201
{
"id": 1,
"created_at": "2015-03-03T18:39:01.360Z",
"updated_at": "2015-03-03T18:39:01.360Z"
}
404
This response is returned when the user with the id
specified was not found.
{ "message": "Couldn't find User" }
400
This response is returned when validations fails.
{ "message": "id is invalid" }
A list of a document recommendations for the specified user.
Returns an array of id
and similarity
pairs with the most similar being first.
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 |
200
[
{
"id": 1,
"similarity": 0.9
},
{
"id": 2,
"similarity": 0.7
},
{
"id": 3,
"similarity": 0.5
}
]
404
This response is returned when the user with the id
specified was not found.
{ "message": "Couldn't find User" }
400
This response is returned when validations fails.
{ "message": "id is invalid" }
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.
A list of a preferences belonging to the user with the id specified in the URL.
Returns a list of all preference objects belonging to the user.
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"
}
]
404
This response is returned when the user is not found.
{ "message": "Couldn't find User" }
Preferences are the combination of a user and document.
Get a preference by ID.
201
{
"user_id": 2,
"document_id": 2,
"created_at": "2015-03-04T09:56:36.045Z",
"updated_at": "2015-03-04T09:56:36.045Z"
}
404
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
{ "message": "Couldn't find Document" }
Given a valid user_id
and document_id
specified in the URL, creates a preference.
201
{
"user_id": 2,
"document_id": 2,
"created_at": "2015-03-04T09:56:36.045Z",
"updated_at": "2015-03-04T09:56:36.045Z"
}
404
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
{ "message": "Couldn't find Document" }
Deletes the preference found at the specified URL.
200
{
"user_id": 2,
"document_id": 2,
"created_at": "2015-03-04T09:56:36.045Z",
"updated_at": "2015-03-04T09:56:36.045Z"
}
404
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
{ "message": "Couldn't find Document" }
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.
A list of cluster models.
Returns a list of all cluster model objects. This is paginated, see the information about pagination at the top of this reference.
200
Per-Page: 25
Total: 100000
[
{
"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"
},
]
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
.
Name | Example | Description |
---|---|---|
number_clusters (integer, required)
|
10
|
How many clusters to group the documents in to (between 2 and 1000) |
201
{
"id": 6,
"number_clusters": 10,
"created_at": "2015-09-17T15:08:37.940Z",
"status": "trained"
}
400
This response is returned when no text
parameter is provided or if invalid JSON was sent.
{ "message": "meta is invalid" }
A representation of a cluster model.
Get the cluster model found at the URL specified.
201
{
"id": 6,
"number_clusters": 10,
"created_at": "2015-09-17T15:08:37.940Z",
"status": "trained"
}
404
This response is returned when the cluster model with the id
specified was not found.
{ "message": "Couldn't find DocumentClusterModel" }
400
This response is returned when validations fails.
{ "message": "id is invalid" }
Deletes a cluster model given the ID specified in the URL.
NOTE: This will delete any clusters the model has attached to it.
201
{
"id": 6,
"number_clusters": 10,
"created_at": "2015-09-17T15:08:37.940Z",
"status": "trained"
}
404
This response is returned when the cluster model with the id
specified was not found.
{ "message": "Couldn't find DocumentClusterModel" }
400
This response is returned when validations fails.
{ "message": "id is invalid" }
A list of cluster models.
Given the id
of a cluster model in the URL, returns a list of cluster IDs belonging to that cluster model.
200
[ 0, 1, 2, 3, 4 ]
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.
200
[ 51, 52, 53, 54, 55 ]
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.
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
}
]
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.
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
.
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 |
200
An array of the same length will be returned with the response from each request.
{
"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
}
[...]
]
}
422
This is returned when a malformed request is made.
{ "message": "Sequential flag is currently required" }
Be careful with this! It will delete all of your data; users, documents and preferences.
204
An empty response.
Simply enter your details below and we'll email your API key to you!
We will process your data as described in our Terms of Use, Privacy Policy and Data Processing Agreement