If you've never used an API before, see our API Primer to get started.
Banlists are lists that exclude certain articles or publications from your response. If you ban a domain, you will not see any articles from that domain. Banning a specific article means you won't see the article anymore in any GET calls to the Stories endpoint.
There are three HTTP Actions (GET, POST, DELETE) and two sub-endpoints (articles and domains). You can make all types of calls to both sub-endpoints. They're all relatively straightforward, but they do require that you add information to the request body instead of sending everything in the URL.
GET requests will return the list of articles or the list of domains on your banlist, depending on whether you hit the
/banlist/articles or the
Both sub-endpoints take the same parameters, and they can be sent via the URL (instead of the request body).
The parameters include:
page(offset) - which page to start on
per_page(limit) - how many assets are returned per page
offset- the number of results to offset on a page
Perhaps the most intuitive is
per_page, which limits the number of results returned. The limit is 500 at a time.
page offset is designed to move through the dataset by large chunks. If
per_page = 500 and
page = 5, the response will return the 2501-3000th items.
offset is similar but with more precision. If
offset = 3,
page = 0, and
per_page = 50, you will see items 4-53 instead of 1-50.
The responses are different depending on the endpoint you reach. For the
domains sub-endpoint, there is only one important piece of information: the domain itself. There is also a subdomain list that is automatically populated with
m. to ensure the mobile version doesn't pass through the filter.
articles sub-endpoint, there is more information returned in the response. The most important is the
uuid or the Universally Unique Identifier. Every single article in our database has its own uuid, even if the story is a duplicate from another publication.
articles responses include story-specific information such as you would retrieve from the regular Stories endpoint. You can see the title, description, publisher, time of publication, analytics, and more. Of course, this is in a JSON dictionary you can easily move through (assuming you've parsed it).
These are rather straightforward and only take one parameter. You should add the domain or the article uuid to ban domains and articles, respectively, and that's it.
However, you cannot add these parameters in the URL string. You must put them into the request body. The technique for doing this varies by language.
In cURL format, this means
curl -X POST -d 'host=[domain to ban]'
for domains and
curl -X POST -d 'uuid=[uuid of article]'
Once you have POST'ed a domain or uuid, you will get a
201 response code if the item was successfully added to the list. You can check with the GET banlist method outlined above.
The counterpart to POSTs, DELETEs remove the specified uuid or domain from the appropriate list. DELETE calls also require you to add the information in the request body.
You will receive a
204 response code if the domain or article was successfully removed from the banlist.