Query for relevant papers.

curl --request GET \
  --url https://api.consensus.app/v1/search \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.consensus.app/v1/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.consensus.app/v1/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.consensus.app/v1/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.consensus.app/v1/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "abstract": "<string>",
      "authors": [
        "<string>"
      ],
      "doi": "<string>",
      "journal_name": "<string>",
      "pages": "<string>",
      "publish_year": 123,
      "title": "<string>",
      "url": "<string>",
      "volume": "<string>",
      "citation_count": 123,
      "semantic_score": 123,
      "study_type": "<string>",
      "takeaway": "<string>",
      "publisher_name": "<string>",
      "full_text_chunks": [
        "<string>"
      ],
      "sjr_best_quartile": 123,
      "sample_size": 123,
      "study_count": 123,
      "population_type": "<string>",
      "is_preprint": true,
      "countries_of_study": [
        "<string>"
      ],
      "study_duration_days": 123,
      "influential_citation_count": 123,
      "institutions": [
        "<string>"
      ],
      "publish_date": "<string>"
    }
  ],
  "page": 123,
  "is_end": true,
  "page_size": 20,
  "next_page": 123
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

GET

Query for relevant papers.

curl --request GET \
  --url https://api.consensus.app/v1/search \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.consensus.app/v1/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.consensus.app/v1/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.consensus.app/v1/search"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.consensus.app/v1/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "abstract": "<string>",
      "authors": [
        "<string>"
      ],
      "doi": "<string>",
      "journal_name": "<string>",
      "pages": "<string>",
      "publish_year": 123,
      "title": "<string>",
      "url": "<string>",
      "volume": "<string>",
      "citation_count": 123,
      "semantic_score": 123,
      "study_type": "<string>",
      "takeaway": "<string>",
      "publisher_name": "<string>",
      "full_text_chunks": [
        "<string>"
      ],
      "sjr_best_quartile": 123,
      "sample_size": 123,
      "study_count": 123,
      "population_type": "<string>",
      "is_preprint": true,
      "countries_of_study": [
        "<string>"
      ],
      "study_duration_days": 123,
      "influential_citation_count": 123,
      "institutions": [
        "<string>"
      ],
      "publish_date": "<string>"
    }
  ],
  "page": 123,
  "is_end": true,
  "page_size": 20,
  "next_page": 123
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

x-api-key

string

header

required

Query Parameters

query

string

required

Query for research papers.

year_min

integer | null

Exclude papers before this year.

year_max

integer | null

Exclude papers after this year.

month_min

integer | null

Exclude papers before this month within year_min. Requires year_min.

Required range: 1 <= x <= 12

month_max

integer | null

Exclude papers after this month within year_max. Requires year_max.

Required range: 1 <= x <= 12

study_types

enum<string>[] | null

Only include these study types.

All possible study types strings saved to search index documents.

Available options:

bench experiment,

case report,

case study,

case-control study,

cohort study,

commentary or perspective,

cross-sectional study,

field study,

historical or archival analysis,

interview study,

literature review,

longitudinal / panel data study,

meta-analysis,

mixed methods study,

non-randomized experimental study,

non-rct in vitro,

other,

rct,

systematic review,

theoretical, modeling, or simulation study,

non-rct experimental,

non-rct observational study,

animal

human

boolean | null

Only include human studies.

controlled

boolean | null

Only include controlled studies.

sample_size_min

integer | null

Exclude studies with smaller sample sizes.

Required range: x >= 1

sjr_min

integer | null

Exclude journals in better quartiles, where 1 is the best quartile.

Required range: 1 <= x <= 4

sjr_max

integer | null

Exclude journals in lesser quartiles, where 1 is the best quartile.

Required range: 1 <= x <= 4

citation_min

integer | null

Exclude papers with fewer citations.

duration_min

integer | null

Minimum study duration (in days).

duration_max

integer | null

Maximum study duration (in days).

exclude_preprints

boolean | null

Exclude preprints, only include peer-reviewed papers.

open_access

boolean | null

Only include open-access papers.

publisher_name

string | null

Comma-separated publisher display names to filter by.

domain

string | null

Comma-separated academic field short codes, not email or web domains, to filter by. Valid values: med, bio, cs, chem, psych, phys, mat, eng, env, bus, econ, math, poli, agri, edu, soc, geol, geog, hist, art, philo, law, ling.

country

string | null

Comma-separated ISO 3166-1 alpha-2 country codes (e.g. us, gb) to filter to those countries of study. Unknown codes are ignored; if none resolve, the filter is not applied.

journal_name

string | null

Preferred journal name (e.g. "Nature"). Results from matching journals are surfaced higher; this does not exclude other journals.

clinical_guideline

boolean | null

Filter to papers classified as clinical guidelines.

medical_mode

boolean | null

Filter to top medical journals and guidelines, about 8M documents

include_semantic_score

boolean | null

Return the semantic score for each result when true. The score is only returned for the top 50 results.

include_full_text_chunks

boolean | null

default:false

Return query-relevant full-text excerpts. Enterprise customers only.

page

integer | null

Page number of results to return (0-indexed, max 50 pages).

Required range: 0 <= x <= 49

page_size

integer | null

Number of papers to return per page. Defaults to 20. The maximum depends on your plan; a larger value is capped to your plan's maximum (see the page_size returned in the response).

Required range: x >= 1

Response

Successful Response

results

QueryResult · object[]

required

List of query results.

Show child attributes

page

integer

required

Current zero-indexed result page.

is_end

boolean

required

True when no further page is indicated by the search backend.

page_size

integer

default:20

Number of results per page actually applied to this response.

next_page

integer | null

Next zero-indexed page to request, if one is available.

⌘I