DISCO API Documentation
All you need to know about DISCO API
In this guide, you will get to know everything about DISCO API; end points, filters, … etc. We also explain how you can retrieve your (alerts and saved searches) results within your API.
We should be answering all your questions here. In case we miss anything, please contact us; clicking on the contact us button at the bottom of this page or using the live chat.
Getting Started
This overview will give you some idea of what data is available, how to find what you need and what you will see when you make an API request.
First of all and to get an API key, you have to have an account on DISCO. If you do not have one already, sign up now to get an instant access.
Steps to get your API key:
- Log in to your account.
- Click on the cog icon next to your logo.
- Click on the first option (Welcome, User Name) and you will be redirected to your dashboard.
- Click on Content API tab.
- Copy your API key.

Endpoints
We provide several endpoints to retrieve different items:
A. All/ Filtered Content
B. Single Item (One Piece of Content)
C. Alerts
D. Saved Searches
Notes:
- For end point (A), results can be filtered using the following parameters:
- API key
- id
- content_format_id_i
- title_id_i
- date_tdt
- headline_s
- publisher_s
- topic_category_ss
- detailed_content_format_id_i
- language_code_s
- meta_body_s
- title_name_s
- country_category_ss
- industryterm_category_ss
- End point (A) response contains all the results but the content is infull (truncated body). End point (B) retrieves single item in full.
- Results of end point (A) are returned as paginated list of containing, by default, 20 entries per page.
A(1). All Content
The (all content) endpoint (/getUserLatestArticles
) returns all pieces of content in your API (your account). For example, let’s suppose that the API key in the link below is yours.
Here the (API key) parameter retrieves all the results in your API (all the results available in your DISCO account).
A(2). Filtered Content
Now, you might want to filter down the results to something more meaningful, specifically looking for English language content that includes the word “economic” and finally you want to sort the results retrieved descendingly by date,. The example below shows how you can do that.
We will go through all the parameters you can use to filter down your results in the (search) section of this documentation. Here, we will explain only how you can use the query operators.
Query operators
The search_free_text parameter supports AND, OR and NOT operators. Below we explain how you can use the mentioned as conjunctions to combine or exclude keywords in your search, resulting in more focused and productive API results.
Exact Phrase
To search for an exact phrase, write the exact phrase as is, without adding any operators or quotation marks.
Ex: Information Technology would retrieve content containing this exact phrase within the headline or body of the article.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=information technology&api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56
And
The AND operator matches articles where both terms exist anywhere in the text of a single article
Ex: Omaba and Trump returns only content that contains both words; “obama” and “trump”.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=obama and trump&api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56
Or
The OR operator will return results which include either, or both, of the terms.
Ex: Obama or Trump returns content that contains the word “obama”, the word “trump” or both words.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=obama or trump&api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56
Not
The NOT operator excludes articles that contain the term(s) after NOT.
Ex: Obama not Trump returns content that contains the word “obama” but not the word “trump”.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=obama not trump&api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56
Not Statement
A not statement helps you eliminate content that matches the query after Not.
Ex: (Obama or Trump) not (Bush or Clinton) returns content with “Obama” or “Trump” in the headline or body, but excludes content which include “Bush” or “Clinton”.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=(Obama or Trump) not (Bush or Clinton) &api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56
Parenthesis with operators
You can use parentheses to group clauses to form sub-queries.
Ex: (Obama or Trump) and United States returns content which include the term “United States”, and “Trump”, “Obama”, or both.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=(Obama or Trump) and United States &api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56
Preserved Words
If you wish to treat a search operator (and, or, not) as a search term, you must enclose the entire phrase in quotation marks.
Ex: “Obama and Trump” returns content which include the phrase “Obama and Trump” exactly as it is written, rather than results containing the term “Obama”, as well as the term “Trump”, anywhere in the article.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=”Obama and Trump” &api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56
Proximity searches
A proximity search looks for terms that are within a specific distance from one another. To perform a proximity search, add the tilde character ~ and a numeric value to the end of a search phrase.
Ex: obama trump~10 returns results which include the terms “Obama” and “Trump” within 10 words of each other.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=obamatrump~10 &api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56
Note: The distance referred to here is the number of term movements needed to match the specified phrase. In the example above, if “Trump” and “Obama” were 10 spaces apart in a field, but “Trump” appeared before “Obama”, more than 10 term movements would be required to move the terms together and position “Trump” to the right of “Obama” with a space in between.
B. Single Item:
The (single item) endpoint (/viewarticle
) returns all the data we have for a given single item (piece of content) id. The parameters you should use are just your API key and the item (piece of conetnt) id as in the example below.
https://marketplace.disco.info/api/viewarticle?id=152580568&api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56
C. Alerts
When you create an alert on DISCO, we will send you emails when we find new results that match your search query and/or filters.
These results can be retrieved in your API as well and we will explain this further in the Alerts section of this documentation.
D. Saved Searches
Instead of writing the same query and/or entering the same filters multiple times; wasting your time and effort. You can save the searches you are using often and retrieve the results of each in a matter of a few clicks.
You can also see the results of your saved searches within your API. More details on this in the Saved Searches section of this documentation.
Example response

Field | Description | Type |
---|---|---|
content_format | Content formats | String |
detailed_content_format | Detailed content formats | String |
languages | Languages of the content services you have | String |
titles | Content services you are subscribed to | String |
countries | Countries of the content services you have | String |
industries | Industries of the content services you have | String |
topics | Topics of the content services you have | String |
id | Item ID | Integer |
title_id_i | Content service ID | Integer |
language_code_s | Content service language | String |
image_ss | The ID, URL and captions of the image/s | String |
video_ss | The ID, URL and captions of the video/s | String |
audio_ss | The ID and the URL of the audio/s | String |
date_tdt | Item (piece of content) date | Date |
meta_body_s | Item (piece of content) summary | String |
headline_s | Item (piece of content) headline | String |
publisher_s | Item (piece of content) publisher | String |
title_content_format_s | Item (piece of content) content format | String |
title_detailed_content_format_s | Item (piece of content) detailed content format | String |
title_name_s | Content service name | String |
country_category_ss | Item (piece of content) countries | String |
topic_category_ss | Item (piece of content) topics | String |
industryterm_category_ss | Item (piece of content) industries | String |
page_limit | The number of items returned in this call | Integer |
current_page | The number of the page you are browsing | Integer |
next_link | The API link you can use to browse the next page | String |
NumFound | The number of results available for your search overall | Integer |
previous_link | The API link you can use to browse the previous page | String |
Parameters
Authentication parameters
Name | Description | Type | Accepted values |
---|---|---|---|
api-key | Your API key which is used for the query | String | API Key |
Query term
Name | Description | Type | Accepted values |
---|---|---|---|
getUserLatestArticles | Returns all pieces of content in your API | String | API Key |
Example response

Field | Description | Type |
---|---|---|
content_format | Content formats | String |
detailed_content_format | Detailed content formats | String |
languages | Languages of the content services you have | String |
titles | Content services you are subscribed to | String |
countries | Countries of the content services you have | String |
industries | Industries of the content services you have | String |
topics | Topics of the content services you have | String |
id | Item ID | Integer |
title_id_i | Content service ID | Integer |
language_code_s | Content service language | String |
image_ss | The ID, URL and captions of the image/s | String |
video_ss | The ID, URL and captions of the video/s | String |
audio_ss | The ID and the URL of the audio/s | String |
date_tdt | Item (piece of content) date | Date |
meta_body_s | Item (piece of content) summary | String |
headline_s | Item (piece of content) headline | String |
publisher_s | Item (piece of content) publisher | String |
title_content_format_s | Item (piece of content) content format | String |
title_detailed_content_format_s | Item (piece of content) detailed content format | String |
title_name_s | Content service name | String |
country_category_ss | Item (piece of content) countries | String |
topic_category_ss | Item (piece of content) topics | String |
industryterm_category_ss | Item (piece of content) industries | String |
page_limit | The number of items returned in this call | Integer |
current_page | The number of the page you are browsing | Integer |
next_link | The API link you can use to browse the next page | String |
NumFound | The number of results available for your search overall | Integer |
previous_link | The API link you can use to browse the previous page | String |
Filters
Name | Description | Type | Accepted Values |
---|---|---|---|
search_free_text | Returns items which match your query | String | e.g: search_free_text=obama and trump |
content_format | Returns items with the content formats you enetered | Integer | e.g: content_format= 1; 4; 5 |
sort | Sorting your results descendingly or accendingly by date | String | sort=DESC, ACCE |
date | Retreiving results for a specific date range | date | eg: &date_from=December+15%2C+2020&date_to=January+12%2C+2021 |
languages | Returns items with the languages you enetered | String | e.g: language= EN; FR; AR |
titles | Returns content for the content services you entered | Integer | e.g: titles=4012; 4013 |
detailed_content_format | Returns content for the detailed content formats you entered | Integer | detailed_content_format=1; 9 |
country_location | Returns items which are related to the countries you entered | String | e.g: country_location=UK; UAE |
industries | Returns items which are related to the industries you entered | Integer | e.g: industries[]=104&industries[]=105 |
categories_list | Returns items which are related to the topics you entered | Integer | e.g: categories_list[]=25&categories_list[]=29 |
companies | Returns items which are related to the company or organisation | String | e.g: &companies[]=google&&companies[]=dell |
Note: All the values accepted for each of the filters can be found in the trees section of the API.
Parameters
Authentication parameters
Name | Description | Type | Accepted values |
---|---|---|---|
api-key | Your API key which is used for the query | String | API Key |
Query term
Name | Description | Type | Accepted values |
---|---|---|---|
getUserLatestArticles | Returns all pieces of content in your API | String | API Key |
How you can create an Alert on DISCO:
1. Log in to your DISCO account.
2. Perform your search which you want to create an alert for.
3. Click on the Alerts button.

4. The (Add Alerts) pop up opens. Click on (Add New Alert).

5. Fill out the fields and click on (save).

How you can retrieve your alert results in your API:
1. Click on the (Alerts) button.
2. Next to any of your pre-created alerts, you can click on the (API) button. Immediately, the API link -that matches the chosen alert’s search- will autogenerate and open in a new tab in your browser.

How you can create a saved search on DISCO:
1. Log in to your DISCO account.
2. Perform your search which you want to save.
3. Click on the (save this search) button.

4. The (Saved Searches) pop up will open. Enter the saved search name and click on save.

How you can retrieve your saved searches results in your API:
1. Click on the (saved searches) button.

2. Next to any of your saved searches, you can click on the (API) button. Immediately, the API link -that matches the saved search- will autogenerate and open in a new tab in your browser.
