Getting Started

The AYLIEN News API is the most powerful way of sourcing, searching, and syndicating enriched news content. Here you’ll find everything you need to know about using the News API.

Using the Search UI with News API

You can learn how to use the News API in conjunction with the Search UI here.

Testing the News API with Postman

You can learn how to use the News API in conjunction with Postman here.

Calling the API


In addition to using the SDKs, you can call the API directly by sending HTTP POST or GET requests to, followed by the endpoint name. All endpoints support the GET method, while only the /coverages and /related_stories endpoints support both GET and POST methods. If you're dealing with long text, please consider using POST.


Requests to the API are authorized by adding an App ID and App Key to the headers of the call. You receive these credentials when you sign up.

  • X-AYLIEN-NewsAPI-Application-ID must be set to your Application ID.
  • X-AYLIEN-NewsAPI-Application-Key must be set to your Application Key.

Error Codes & Responses

Code Text Description
200 OK Success!
400 Bad Request The server cannot or will not process the request due to an apparent client error.
401 Unauthorized Authentication credentials were missing or incorrect.
403 Forbidden Your plan does not have access to the feature you requested, which means your request can't be fulfilled. More details about the missing feature are provided in the response message.
404 Not Found The URI requested is invalid or the resource requested, such as a story, does not exist.
405 Method Not Allowed A request method is not supported for the requested resource.
414 URI Too Long The URI provided was too long for the server to process. The maximum request URI size is 2 kB.
422 Unprocessable Entity The request was invalid or cannot be otherwise served.
429 Too Many Requests Usage limits are exceeded.
500 Internal Server Error An unexpected error has occurred and our engineers have been informed. If you continue to have problems, contact
503 Service Unavailable The server is currently unavailable (because it is overloaded or down for maintenance).
504 Gateway Timeout The server could not get a response in time, probably because the web page is blocked or behind a paywall.

Rate Limits

Rate limiting of the API is primarily considered on a per-application basis — or, more accurately, per application ID you control.


Each endpoint is subject to a rate limit of 60 hits per minute and 3 hits per second.

Story Volumes

When an application exceeds the rate limit for a given API endpoint, the AYLIEN News API will return an HTTP 429 "Too Many Requests" response code.

Checking your remaining story volume

There are three response headers you can use to check your quota allowance, the number of hits remaining on your quota, and the time and date your quota will be reset:

  • X-RateLimit-Limit : The number of allowed requests in the current period
  • X-RateLimit-Remaining : The number of remaining requests in the current period
  • X-RateLimit-Reset : The remaining window before the rate limit resets in UTC epoch seconds

Licensed content

Customers with access to our licensed content will be able to retrieve stories from our licensed sources. The license_type field (a field in the stories endpoint response) indicates whether an article has come from a licensed source or if it is a web-sourced article.

Sample license_type flag output

"license_type": 0 # indicates the story is from the group of web-based sources
"license_type": 1 # indicates the story is from the group of licensed sources

URL Encoding

Remember to URL-encode your query. The following examples show how queries can be properly encoded.

Query URL-Encoded Query
published_at.start=NOW-30DAYS&[]=IAB1-5&entities.body.links.dbpedia[]= published_at.start=NOW-30DAYS&
title=Trump OR Sanders&entities.title.text[]=election title=Trump+OR+Sanders&entities.title.text%5B%5D=election
title=Ireland&published_at.end=NOW-2MONTHS/DAY title=Ireland&published_at.end=NOW-2MONTHS%2FDAY

Language Support

Our API supports multiple (human) languages, that can be selected using the language[] parameter.

English (en) German (de) French (fr) Italian (it)
Spanish (es) Portuguese (pt) Russian (ru) Dutch (nl)
Arabic (ar) Turkish (tr) Chinese (traditional) (zh-tw) Chinese (simplified) (zh-cn)
Swedish (sv) Danish (da) Finnish (fi) Farsi (fa)

Some of our features are added to the story objects after the text is analyzed in the original language, while other features are added after the text has been translated to English. The table below lists the langauge used for analysis for each feature.

Feature Original Text Analyzed Translated Text Analyzed
Clusters en All Other Languages
Topic Categories en All Other Languages
Entities en All Other Languages
Sentiment (body) en, es, de All Other Languages
Extracted Keywords en, es, de, it, fr, pt All Other Languages
Hashtags en, es, de, it, fr, pt All Other Languages
Word, Character, and Paragraph Counts en, es, de, it, fr, pt All Other Languages