Download OpenAPI specification:Download
This API acts as a create/read/update/delete interface for anything related to documents.
All the request bodies in this API are JSON encoded and their Content-Type headers should be set to application/json.
By document, we refer to a cohesive text, for example a complete news article. However, we only require a simple representation for our system to work. Consisting just of a unique ID, a text snippet and optional properties. The text snippet is ideally a short, meaningful representation of the larger document, reduced to just one paragraph.
The document_id is a unique identifier for a single document.
We don't require a specific format, it just needs to comply to the following regexp: ^[a-zA-Z0-9_:@.-]+$.
A snippet is a reduced representation of a larger text, for example if the document would be a news article, then its text would be the news article in a pure textual format. In order for our system to work correctly, it is important that the snippet is just the size of one or two paragraphs, and that the snippet's text clearly summarises the larger text. For example, let's take a news article which talks about the effects of inflation. Our snippet could then be: "Inflation worries as prices keep rising. People having budgetary difficulties as a result. Government pressured to take action.". A bad snippet would for example be just taking the very first paragraph of a document, which could sometimes work, but could also lead to: "December 20th 2020. Article written by Jane Doe. On this bright and sunny day, people might forget about their worries sometimes."
Properties are optional entries for documents, which are usually needed to properly show the document back to the user, when it returns as a personalized document.
If for example, you'd wish to integrate a type of carousel view, listing a total of 10 personalized documents in a "for you"-section, then you might choose to display each document as an image and title, with a url to link the user to when pressed.
For this, you would need three document properties: image, link and title.
You are free to add as many properties as needed.
\
Add documents to the system.
The system will create a representation of the document that will be used to match it against the preferences of a user.
Important note: Currently we allow up to a maximum of 100 documents per batch size. If you need to add more, then please split up the total amount of documents in separate calls, where each call contains at maximum 100 documents.
Important note: If a document id appears multiple times, only the last document with that id is retained.
Important note: Documents which have no publication_date are not included when using the published_after filter.
required | Array of objects (IngestedDocument) [ 1 .. 100 ] items |
{- "documents": [
- {
- "id": "document_1",
- "snippet": "lorem ipsum delores",
- "properties": {
- "is_blue": true
}, - "tags": [
- "news",
- "tech"
], - "is_candidate": false
}, - {
- "id": "document_2",
- "snippet": "more lorem less ipsum",
- "tags": [
- "exclusive"
], - "default_is_candidate": false
}, - {
- "id": "document_3",
- "snippet": "quite a lot of lines of lorem ipsum delores",
- "summarize": true
}
]
}{ }Delete all documents listed in the request body.
| documents required | Array of strings [ 1 .. 1000 ] items |
{- "documents": [
- "document_id"
]
}{- "request_id": "string",
- "kind": "string",
- "details": { }
}Set the documents considered for recommendations.
required | Array of objects (DocumentCandidate) >= 0 items |
{- "documents": [
- {
- "id": "document_id"
}
]
}{- "request_id": "string",
- "kind": "string",
- "details": { }
}Permanently deletes the document from the system.
| document_id required | string [ 1 .. 256 ] characters ^[a-zA-Z0-9_:@.\-]+$ Example: document_id Id of the document |
{- "request_id": "string",
- "kind": "string",
- "details": { }
}Gets all the properties of the document.
| document_id required | string [ 1 .. 256 ] characters ^[a-zA-Z0-9_:@.\-]+$ Example: document_id Id of the document |
{- "properties": {
- "title": "News title"
}
}Sets or replaces all the properties of the document.
| document_id required | string [ 1 .. 256 ] characters ^[a-zA-Z0-9_:@.\-]+$ Example: document_id Id of the document |
required | object Mostly arbitrary properties that can be attached to a document. A key must be a valid |
{- "properties": {
- "title": "News title",
}
}
{- "request_id": "string",
- "kind": "string",
- "details": { }
}Deletes all the properties of the document.
| document_id required | string [ 1 .. 256 ] characters ^[a-zA-Z0-9_:@.\-]+$ Example: document_id Id of the document |
{- "request_id": "string",
- "kind": "string",
- "details": { }
}