Articles in this section

Banlist Endpoints

Cory Sarver
  • Updated

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 Calls

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 /banlist/domains endpoint.

GET Parameters

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.

The 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.

 

GET Response

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 www. and m. to ensure the mobile version doesn't pass through the filter.

For the 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).

 

POST Calls

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]'

for articles.

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.

 

DELETE Calls

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.

Related articles