HTTP POST requests
classifyArticle POST requests should send article data in the request body, as a single JSON object, or optionally an array of objects as in the following example:
[{
"html": "<title><h1>FA reveal bans for Port Vale's Mitch Clark and Tom Pope</h1></title><h2> <p>Mitch Clark and Tom Pope were sent off in the closing stages of Port Vale's 3-2 win at Forest Green</p> </h2><p>Port Vale duo Mitch Clark and Tom Pope face three and one game bans respectively.</p> <p>The bans have been confirmed on the FA’s website this morning after both were sent off in last night’s 3-2 win at Forest Green Rovers.</p> ... <p><a data-content-type=\"section-topic\" data-link-tracking=\"InArticle|Link\" href=\"https://www.stokesentinel.co.uk/all-about/port-vale-fc\">For all your latest Port Vale news and analysis, click here</a></p>",
"cmsID": "stokesentinel-3838610",
"url": "www.stokesentinel.co.uk/sport/football/port-vale-pope-clark-bans-3838610",
"author": "Michael Baggaley",
"published": "2020-02-01T11:27:15.000Z",
"lastModified": "2020-02-01T11:27:15.000Z",
"title": "FA reveal bans for Port Vale's Mitch Clark and Tom Pope"
}, {
"cmsID": "mirror-21482732",
"url": "www.mirror.co.uk/news/uk-news/inside-lonely-coronavirus-quarantine-masked-21482732",
"author": "Matthew Dresch",
"published": "2020-02-12T14:43:27.000Z",
"title": "Inside lonely coronavirus quarantine where masked Brits have meals left at the door"
}]
Request object details
| Field name | Required? | Description |
|---|---|---|
| html | One only of html or text fields are required - if not possible to pass these then URL is mandatory | HTML markup of article content (do not include other markup from published pages such as header, footer, links or teasers for other articles) |
| text | One only of html or text fields are required - if not possible to pass these then URL is mandatory | Plain text version of article content |
| url | At least one of url or cmsID are required | URL that will reference the article when it is published |
| cmsID | At least one of url or cmsID are required | Publisher defined unique id for the article (represented as a string value) |
| title | Not mandatory, but useful for reporting and analytics. | The article title. This should also be included in the html or text data to ensure it is processed by the Mantis analyser. |
| author | Not mandatory, but useful for reporting and analytics. | The article author's name. For multiple authors format as a comma separated list of names in a single string. |
| published | Not mandatory, but needed for Mantis to understand article versioning | Timestamp for when article was published |
| lastModified | Not mandatory, but needed for Mantis to understand article versioning | Timestamp for when article content was last changed |
Batch file upload formats
The data format for files uploaded to the batch processor is the same as the request object data format in HTTP endpoint detailed above, but can support much larger numbers of articles included for analysis in a single file.
For customisation, to support other file upload formats please contact us to discuss the requirements.
HTTP GET requests
classifyArticle GET requests should pass the article URL or CMS id as a query parameters in the request, e.g.
https://<publisher-mantis-url>/classifyArticle?cmsID=stokesentinel-3838610
or
https://<publisher-mantis-url>/classifyArticle?url=www.stokesentinel.co.uk/sport/football/port-vale-pope-clark-bans-3838610
Response Data
Both POST and GET requests will return results in the response body as in the following examples:
Success:
{
input: {
html: "...",
cmsID: "mirror-21482732",
url: "www.mirror.co.uk/news/uk-news/inside-lonely-coronavirus-quarantine-masked-21482732",
author: "Matthew Dresch",
published: "2020-02-12T14:43:27.000Z",
title: "Inside lonely coronavirus quarantine where masked Brits have meals left at the door"
},
ratings: [{
customer: "Default",
rating: "RED",
ruleSetVersion: 5
}, {
customer: "Custom Ruleset 1",
rating: "AMBER",
ruleSetVersion: 5
}, {
customer: "Custom Ruleset 1",
rating: "GREEN",
ruleSetVersion: 5
}]
}
Response object details
| Field name | Description |
|---|---|
| input | This reflects the data that was sent in the original Mantis API request to analyse the article ands contains all the article metadata such as:
This is in the same format as the POST endpoint request object |
| ratings | This is an array of ratings using different Mantis rulesets - which can be customised for specific publications, advertising partners etc |
| ratings[n].customer | The name of the customer/ruleset this rating is for |
| ratings[n].rating | The Brand safety rating for the article for this ruleset - values will be “RED”, “GREEN”, “AMBER”. See ratings description below for more details. |
| ratings[n].ruleSetVersion | The version number of the Mantis ruleset that was applied to the article to determine the Brand Safety rating. |
Other fields may be present with a more detailed breakdown of the rules that resulted in the brand safety rating – if this has been enabled in the Mantis API platform.
If multiple articles are submitted for processing in a single request, then the response will be an array of objects.
Failure:
The response will include an ‘error’ field in the JSON data, with a description of the error that occurred.
{
error: "Article id not found"
}