This is the documentation of the last version of the API (2017/08/07). See the modifications in the Changelog.

Overview

This is the first version of the API of Epistemonikos. It allows other sites to retrieve basic information from our database. This project is part of a wider initiative to create a platform of APIs sharing a common data structure, in order to efficiently exchange information, avoid error, decrease workload, and at some moment being able to keep a worldwide distributed workforce supporting living systematic reviews and living guidelines.

The conceptual development of the above mentioned platform is partially based in the existing CochraneTech and GRADEtech initiatives.

First steps

The beta version of our API is restricted to the clients registered in our system. Each registered client counts with a private access token, which must be set in the Authentication header of each request: 

curl "{{ api_url }}/v1/documents/search?q=cancer" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'

If you want to register your application and try our API, please contact us [dev at epistemonikos.org].

Already have an access token? You can try our API in the test page.

API Resources

Our current version provides the resources specified in the following table. As previously stated, all requests must include the Authentication header with a proper access token, otherwise you'll get an 401: Unauthorized HTTP status code. You'll find further details by clicking on the icon at the beggining of each row:

Details Method URI Params Description
GET /documents/{id}[?show={'threads','classification_status','relations_info'}] {id, [show]} PubMed ID, Epistemonikos ID or DOI, and show indicating the aditional data you want to see for the document ('threads', 'relations_info' and 'classification_status' options are available). Retrieves the details of the document with the specified ID
GET /documents/search?q={keywords}[&g={group}&p={page}&sort={'year', 'score'}&classification={'systematic-review', 'structured-summary-of-systematic-review', 'broad-synthesis', 'primary-study', 'structured-summary-of-primary-study'}&show={'classification', 'external_links'}] {keywords, [page, group, sort, classification, show]} keywords (or exact phrase, if you use quote marks) to search in the Epistemonikos database, the specific group where you want to search the Keywords, the page you want to navigate in the search results, a document valid classification for filtering the results, a sort value for ordering your results, and show which indicates aditional data you want to see for each of the search result documents (currently, the available options are 'classification' and 'external_links'). Retrieves a list of the found documents, based on the keywords provided in the URL
POST /documents/advanced_search {query,[page, page_size, min_year, max_year, show, sort, exclude_cochrane, only_reviews]} Boolean query to search in the Epistemonikos database, the page and page size you want to navigate in the search results, and the min_year and max_year to limit the results to a date range. With the show parameter you can obtain more info for your results, and with sort you can specify the order for your results. The exclude_cochrane and only_reviews parameters allows you to apply more restrictions to your results. Retrieves a list of the found documents, based on the query provided
GET /studies_threads/{id} {id} Studies thread ID Retrieves the details of the studies thread with the specified ID
GET /matrices/{id}[?show={'abstracts','threads'}] {id, [show]} Epistemonikos ID and show indicating the aditional data you want to see for the matrix (currently, only the 'abstracts' and 'threads' options are available). Retrieves the details of the matrix with the specified ID

Document information GET: {{ api_url }}/v1/documents/{id}[?show={'threads','relations_info','classification_status'}]

Parameters

id
You can use a Pubmed ID, Epistemonikos ID or DOI. The DOI must be url-encoded.
show
[Optional] A comma separated list stating which aditional document data you want to retrieve. The available options are threads, relations_info and classification_status. They indicate that you want the studies threads including the current document, information about the related references, and the status of the classification of the document.

Response

If the Epistemonikos database contains a document with the provided ID, you'll receive a JSON containing the details of such document and a 200: Ok status code. Otherwise, you'll get a 404: Not Found status code. These are the keys that you'll find in the request response:

id
The Epistemonikos ID of the document.
citation
The document citation, following the Vancouver Style.
external_links
URLs to the publisher of the document, and the document in the websites pubmed and epistemonikos.
identifiers
The known identifiers of the document (doi, pubmed and epistemonikos).
content
The content of the document. Here you'll find the title, abstract, the document's year, a list of authors and information about the document's publication.
metadata
The document's metadata, containing the classification (as defined on Epistemonikos - About Us), the study_design (study desing only applies to primary studies, and we are only returning RCT yes/no by now), and the groups where the document belongs (if any).
threads
A list containing the studies threads IDs of each thread containing the document. Only shown if the show parameter list contains threads.
relations_info
Information regarding the references related to this document. The status fields shows if the document is pending (no information about it's related references), in_process (the information is being completed), or done (the document has it's related references information completed). The total_references and reported_references fields shows the total amount of references linked to the document in the database, and the amount of included references reported by the authors of the document, respectively. The references field contains a breakdown of all the related references, sorted by classification, and containing the URL to access such references on the Epistemonikos Database. Only shown if the show parameter list contains relations_info.
classification_status
This fields shows the current status of the document's classification. It can be pending (the document hasn't been classified), machine (it's onle been classified by our automatic algorithms), or validated (it was classified by our collaborators, or the machine classification was validated by a collaborator). Only shown if the show parameter list contains classification_status.

Example 1: Simple request

Request
curl "{{ api_url }}/v1/documents/aced6ce12e1f54fb98c16d3435195ceb284240d2" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8 
{{ samples['document_info']['result'] | json }}

Example 2: Request with show=threads parameter

Request
curl "{{ api_url }}/v1/documents/55d025440a4e37c5a56a21ff72baf670b6dd3a22?show=threads" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8 
{{ samples['document_info_w_threads']['result'] | json }}

Example 3: Request with show=relations_info,classification_status parameters

Request
curl "{{ api_url }}/v1/documents/2063de052783f8c42c38bff9530e57bcee8f1353?show=relations_info,classification_status" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8 
{{ samples['document_info_w_relations_info']['result'] | json }}

Parameters

keywords
The keywords you want to search in the Epistemonikos database. You can surround them in quote marks to run an exact match query.
group
[Optional] The group where you want to search the keywords. The valid groups are: vpp (Patients Values and Preferences), health_systems (documents from the PDQ-Evidence platform), cardiology and pti (Policy Trials Inventory). If the group provided in the query doesn't match any of the specified, the server will respond with a 400: Bad Request HTTP status code
page
[Optional] The page you want to retrieve in the search results. It's value is 1 by default (first page). If the value provided isn't a integer greater than zero, the server will respond with a 400: Bad Request HTTP status code
sort
[Optional] A comma separated list that specify the order for the results of your query. The valid options for sorting are year and score. You can choose between ascending or descending order by using minus or plus as prefix for each option (e.g.: both sort=-year,score and sort=-year,+score means "sort by year, descending, and then by ascending score"). By default, they will be sorted by relevance (score, descending order).
classification
[Optional] A comma separated list of document's classifications that you want to use as filters for the search results. The valid classifications are 'systematic-review', 'structured-summary-of-systematic-review', 'broad-synthesis', 'primary-study', and 'structured-summary-of-primary-study'. For more details go to Epistemonikos' database glossary
show
[Optional] A comma separated list stating which aditional document data you want to retrieve. Currently you can specify classification and external_links values, indicating that you want to see those attributes of each document in the search results.

Response

The response will contain two main items: the search_info, with information about the search results, and the results, which will contain a list of documents matching your query. Depending on the page you're currently on, the results list will have from zero to ten results.

In the search_info key of the response you'll find the following items:

total_hits
The total amount of documents found as result of your query.
pages
Inside this item are the URIs to navigate through the pages of your query results. Specifically, self is the URI of the current results page; prev and next are the URIs of the previous and following results page, and are only available when there is a previous or next page (for example, if you're on the first page, you won't see a prev URI); and first and last are the URIs of the first and last pages of results.

The results key contains a list of the results of your query, corresponding to the page received as parameter. Each item of the list contains the following keys:

id
The Epistemonikos ID of the document.
year
The document's publication year.
classification
The document's classification. Only shown if the show list contains classification
external_links
The document's external links section. Only shown if the show list contains external_links
authors
The document's authors.
journal
The document's publication journal.
title
The document's title.
abstract
The document's abstract.
document_uri
The document location in the API.

Example 1: Request without extra parameters

Request
curl {{ api_url }}/v1/documents/search?q=\"adjuvant\ treatment\" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8 
{{ samples['document_search_wo_page']['result'] | json }}

Example 2: Request with a group, page and show='classification' parameter

Request
curl '{{ api_url }}/v1/documents/search?q=adjuvant&g=health_systems&p=2&show=classification' -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8 
{{ samples['document_search_w_page']['result'] | json }}

Parameters

query
The boolean query you want to search in the Epistemonikos database
page
[Optional] The page you want to retrieve in the search results. It's value is 1 by default (first page). If the value provided isn't a integer greater than zero, the server will respond with a 400: Bad Request HTTP status code
page_size
[Optional] The amount of results per page you want to retrieve. It must be a number between 0 and 500. It's value is 10 by default
min_year
[Optional] The lower limit of a date range for your results.
max_year
[Optional] The upper limit of a date range for your results.
sort
[Optional] A comma separated list that specify the order for the results of your query. The valid options for sorting are year and score. You can choose between ascending or descending order by using minus or plus as prefix for each option (e.g.: both sort=-year,score and sort=-year,+score means "sort by year, descending, and then by ascending score"). By default, they will be sorted by relevance (score, descending order).
show
[Optional] A comma separated list stating which aditional data you want to retrieve. Currently, only two values are available: classification, indicating that you want the classification of each document in the search results, and facets, which will show results faceting by publication year.
exclude_cochrane
[Optional] A parameter that allows you to exclude all results belonging to the Cochrane Library. It can be true or false.
only_reviews
[Optional] A parameter to restrict your search to Systematic Reviews only. It can be true or false.

Response

The response will contain two main items: the search_info, with information about the search results, and the results, which will contain a list of documents matching your query. Depending on the page you're currently on, the results list will have from zero to ten results (or the value set in the page_size parameter). If your request includes the show=facets parameter, an aditional years_facets item will be included in the response.

In the search_info key of the response you'll find the following items:

total_hits
The total amount of documents found as result of your query.
current_page
The retrieved results page number.
results_per_page
The amount of documents retrieved per page.

The results key contains a list of the results of your query, corresponding to the page received as parameter. Each item of the list contains the following keys:

id
The Epistemonikos ID of the document.
citation
The document citation.
authors
The document's authors.
year
The document's publication year.
journal
The document's publication journal.
classification
The document's classification. Only shown if the show parameter list contains classification
title
The document's title.
abstract
The document's abstract.
document_uri
The document location in the API.

Example 1: Request without extra parameters

Post parameters
{{ samples['document_adv_search_wo_params']['params'] | json }}
Request
curl -X POST -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"' -H "Content-Type: application/json" -d '{{ JSON.stringify(samples['document_adv_search_wo_params']['params']) | json }}' {{ api_url }}/v1/documents/advanced_search
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8 
{{ samples['document_adv_search_wo_params']['result'] | json }}

Example 2: Request with page, page_size, min_year, max_year, sort, show, exclude_cochrane and only_reviews parameters

Post parameters
{{ samples['document_adv_search_w_params']['params'] | json }}
Request
curl -X POST -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"' -H "Content-Type: application/json" -d '{{ JSON.stringify(samples['document_adv_search_w_params']['params']) | json }}' {{ api_url }}/v1/documents/advanced_search
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8 
{{ samples['document_adv_search_w_params']['result'] | json }}

Studies thread information GET: {{ api_url }}/v1/studies_threads/{id}

Parameters

id
The studies thread ID.

Response

If the Epistemonikos database contains a studies thread with the provided ID, you'll receive a JSON containing the details of such thread and a 200: Ok status code. Otherwise, you'll get a 404: Not Found status code. These are the keys that you'll find in the request response:

id
The Epistemonikos ID of the studies thread.
name
The studies thread name
fullname
The studies thread fullname
documents
Contains a list with all the documents contained in the studies thread

Each document contained in the documents list contains the following keys:

id
The Epistemonikos ID of the document.
title
The document's title.
document_uri
The document location in the API.
doi
The DOI of the document.
pubmed
The PubMed ID of the document.

Example

Request
curl "{{ api_url }}/v1/studies_threads/5411b5b65f844e413814e99e" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8 
{{ samples['studies_thread_info']['result'] | json }}

Matrix information GET: {{ api_url }}/v1/matrices/{id}[?show={'abstracts','threads'}]

Parameters

id
The ID of the public matrix you want to retrieve.
show
[Optional] A comma separated list stating which aditional matrix data you want to retrieve. If abstracts is submitted, it indicates that you want the abstract of each document. If threads is submitted, the result will show the studies threads that contains each document.

Response

If the Epistemonikos database contains a public matrix with the provided ID, you'll receive a JSON containing the details of such matrix and a 200: Ok status code. If the matrix does exists but it isn't public, you'll get a minimal JSON document stating that your matrix isn't public yet. If our database doesn't contain a matrix with the ID provided you'll get a 404: Not Found status code. These are the keys that you'll find in the request response:

id
The Epistemonikos ID of the matrix.
is_public
The publication state of the matrix. If it is false, none of the following keys will be displayed.
title
The title of the matrix.
authors
A list containing the Epistemonikos usernames of the matrix authors.
date
The matrix creation date, in ISODate format.
external_links
URLs to the matrix in the epistemonikos platform.
references
Contains a list with all the documents contained in the matrix, separated by classification (primary_studies and systematic_reviews).

Each document contained in either primary_studies or systematic_reviews lists has the following keys:

id
The Epistemonikos ID of the document.
title
The document's title.
abstract
The document's abstract. Only shown if the show parameter list contains abstracts.
document_uri
The document location in the API.
authors
The document authors list.
rct
true, false or null, depending on the documents being marked as RCT.
year
The document's publication year.
threads
A list containing the studies threads IDs of each thread containing the document. Only shown if the show parameter list contains threads.
doi
The DOI of the document.
pubmed
The PubMed ID of the document.

Example 1: Not published matrix

Request
curl "{{ api_url }}/v1/matrices/51cb0836659e9351fbb431cf" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8 
{{ samples['matrix_info_not_public']['result'] | json }}

Example 2: Published matrix

Request
curl "{{ api_url }}/v1/matrices/54171ed67aaac82af9fbeba0" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8 
{{ samples['matrix_info']['result'] | json }}

Example 2: Published matrix with show=abstracts,threads parameters

Request
curl "{{ api_url }}/v1/matrices/54171ed67aaac82af9fbeba0?show=abstracts,threads" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8 
{{ samples['matrix_info_w_abstract_threads']['result'] | json }}
Epistemonikos