https://api-v5.lateral.io/
Every request must be authenticated with your subscription key. This must be sent as an HTTP header:
Subscription-Key: YOUR_API_KEY
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.
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-v5.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.
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.
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.
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.
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.
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 |
|---|---|---|
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`) |
200
Contains a list of document objects. Returned when a valid request to the API was made.
Per-Page: 25
Total: 100000
[
{
"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"
}
]
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-_.
| 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
The document object that was just saved. Returned when the document has been saved.
{
"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"
}
400
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-_).
{ "message": "meta is invalid" }
409
Occurs when trying to create a document using an ID that already exists in the dataset.
{ "message": "Document with the ID 'doc-1' already exists" }
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.
200
The document object. Returned when a valid document was requested.
{
"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"
}
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": "New title" }
|
Meta data about the document |
200
The document object. Returned when the update has been saved.
{
"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"
}
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.
200
The document object that was just deleted
{
"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"
}
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" }
A list of a tags belonging to the document with the id specified in the URL.
Returns a list of all tags belonging to the document. This is paginated, see the information about pagination at the top of this reference.
200
A paginated list of tags
[
{
"id": "tag-1",
"created_at": "2015-03-04T09:56:36.045Z"
},
{
"id": "tag-4",
"created_at": "2015-03-04T09:56:36.045Z"
}
]
404
This response is returned when the document is not found.
{ "message": "Couldn't find Document" }
Uses the tag suggester to recommend tags for the current document.
Returns a list of suggested tags that are relevant to the document.
| Name | Example | Description |
|---|---|---|
number(Integer, optional)
|
20
|
How many results to return (Default: 10) |
200
{
"results": [
{
"id": "9vxw88heig",
"score": 0.733480557394401
},
{
"id": "3rmkum0qk7",
"score": 0.295686706052547
},
{
"id": "7oaj8yul0q",
"score": 0.281185408507482
},
...
]
}
404
This response is returned when the document is not found.
{ "message": "Couldn't find Document" }
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
A paginated list of preferences
[
{
"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 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.
| 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[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
|
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) |
200
If using the content-based recommender (use_hybrid is not set or is set to false):
[
{
"id": "doc-1",
"similarity": 0.9
},
{
"id": "doc-2",
"similarity": 0.7
},
{
"id": "doc-3",
"similarity": 0.5
}
]
200
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.
{
"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 }]
}
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.
Returns an array of id and similarity pairs with the most similar being first.
| 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[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 |
text(string, required)
|
Fat black cat
|
The text to get similar documents for |
200
[
{
"id": "1",
"similarity": 0.9
},
{
"id": "2",
"similarity": 0.7
},
{
"id": "3",
"similarity": 0.5
}
]
Given a list of document IDs as the ids parameter, an object will be returned containing the IDs of similar documents.
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.
| 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[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
|
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) |
200
If using the content-based recommender (use_hybrid is not set or is set to false):
[
{
"id": "doc-1",
"similarity": 0.9
},
{
"id": "doc-2",
"similarity": 0.7
},
{
"id": "doc-3",
"similarity": 0.5
}
]
200
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.
{
"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": {}
}
Returns an array of all document IDs.
Returns an array of all document IDs.
200
[
"doc-1",
"doc-2",
"doc-3"
]
Uses the hybrid recommender to decide popularity and returns a list of popular documents.
Returns an array of popular id and similarity pairs.
| 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[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 |
200
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.
{
"results": [
{
"id": "doc-1",
"score": 3.14
},
{
"id": "doc-2",
"score": 0.8
},
{
"id": "doc-3",
"score": -1.2
}
],
"document_ids": [],
"user_ids": []
}
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.
Uses the hybrid recommender to decide popularity and returns a list of popular documents.
Returns a list of all tag objects. This is paginated, see the information about pagination at the top of this reference.
200
A paginated list of tags.
Per-Page: 25
Total: 100000
[
{
"id": "tag-1",
"created_at": "2015-03-01T18:11:01.360Z"
},
{
"id": "tag-2",
"created_at": "2015-03-03T18:39:01.360Z"
},
]
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-_.
201
The tag that was just created
{
"id": "tag-1",
"created_at": "2015-03-03T18:39:01.360Z"
}
400
This response is returned the provided ID is not valid (a-Z0-9-_).
{ "message": "id is invalid" }
409
Occurs when trying to create a tag using an ID that already exists in the dataset.
{ "message": "Tag with the ID 'tag-1' already exists" }
A representation of a tag. There is no data to set for a tag, therefore they cannot be edited.
Get a tag by ID.
200
The tag that was requested
{
"id": "tag-1",
"created_at": "2015-03-03T18:39:01.360Z"
}
404
This response is returned when the tag with the id specified was not found.
{ "message": "Couldn't find Tag" }
400
This response is returned when validations fails.
{ "message": "id is invalid" }
Deletes the tag found at the specified URL.
200
The tag that was just deleted
{
"id": "tag-1",
"created_at": "2015-03-03T18:39:01.360Z"
}
404
This response is returned when the tag with the id specified was not found.
{ "message": "Couldn't find Tag" }
400
This response is returned when validations fails.
{ "message": "id is invalid" }
Returns a list of all documents that are tagged with this tag.
List all documents that are tagged with this tag.
| 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`) |
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"
},
....
]
404
This response is returned when the tag with the id specified was not found.
{ "message": "Couldn't find Tag" }
400
This response is returned when validations fails.
{ "message": "id is invalid" }
Uses the tag suggester to recommend tags for the given text.
Returns a list of suggested tags that are relevant to the input text.
| 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) |
200
{
"results": [
{
"id": "9vxw88heig",
"score": 0.733480557394401
},
{
"id": "3rmkum0qk7",
"score": 0.295686706052547
},
{
"id": "7oaj8yul0q",
"score": 0.281185408507482
},
...
]
}
Taggings are how you add tags to documents.
A tagging is the combination of a tag and document.
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.
204
The response is empty
400
This response is returned if the tag_id is not valid (a-Z0-9-_).
{ "message": "tag_id is invalid" }
404
This response is returned if the document is not found.
{ "message": "Couldn't find Document" }
Deletes the tagging found at the specified URL.
204
An empty response.
404
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
{ "message": "Couldn't find Document" }
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.
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": "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"
}
]
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-_.
201
{
"id": "user-1",
"created_at": "2015-03-03T18:39:01.360Z",
"updated_at": "2015-03-03T18:39:01.360Z"
}
400
This response is returned the provided ID is not valid (a-Z0-9-_).
{ "message": "id is invalid" }
409
Occurs when trying to create a user using an ID that already exists in the dataset.
{ "message": "User with the ID 'user-1' already exists" }
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": "user-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.
| 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 |
200
{
"id": "user-1",
"created_at": "2015-03-03T18:39:01.360Z",
"updated_at": "2015-03-03T18:39:01.360Z"
}
200
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.
{
"id": "user-1",
"created_at": "2015-03-03T18:39:01.360Z",
"updated_at": "2015-03-03T18:39:01.360Z",
"merged_into": "user-124"
}
404
This response is returned when the user with the id or merge_into 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 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.
| 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[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) |
200
If using the content-based recommender (use_hybrid is not set or is set to false):
[
{
"id": "doc-1",
"similarity": 0.9
},
{
"id": "doc-2",
"similarity": 0.7
},
{
"id": "doc-3",
"similarity": 0.5
}
]
200
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.
{
"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 }]
}
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" }
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": "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
}
[...]
]
}
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, tags, 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