> ## Documentation Index
> Fetch the complete documentation index at: https://docs.consensus.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with Consensus API

> Search over 400 million peer-reviewed research papers with the Consensus REST API.

The Consensus API lets you search 400+ million peer-reviewed papers over a single REST endpoint. Send a query and get back ranked papers with titles, authors, journals, publication years, citation counts, and direct links.

Here's a real request and response, with full-text excerpts turned on:

```bash theme={null}
curl -G "https://api.consensus.app/v1/search" -H "x-api-key: $CONSENSUS_API_KEY" \
  --data-urlencode "query=what dose of creatine improves working memory" \
  --data-urlencode "include_full_text_chunks=true"
```

```json wrap theme={null}
{
  "results": [
    {
      "title": "Creatine and improvement in cognitive function: Evaluation of a health claim pursuant to article 13(5) of regulation (EC) No 1924/2006",
      "authors": ["Dominique Turck", "T. Bohn", "Montaña Cámara", "…"],
      "journal_name": "EFSA Journal",
      "publisher_name": "Wiley",
      "publish_year": 2024,
      "sjr_best_quartile": 1,
      "citation_count": 5,
      "doi": "10.2903/j.efsa.2024.9100",
      "url": "https://consensus.app/papers/creatine-and-improvement-in-cognitive-function-turck-bohn/7e703e828b815257b31687a25eceac9d/",
      "takeaway": "Creatine supplementation has not been established as a cause-and-effect relationship for improving cognitive function in one or more domains.",
      "full_text_chunks": [
        "Section: Human intervention studies in healthy individuals conducted under normal conditions | Two studies had an initial loading phase of 20 g/day of creatine for 5 days, followed by 5 g/day … A significant improvement in working memory, as measured by the Backwards Digit Span test, was observed only in the study of shorter duration …",
        "Section: Weighing of the evidence | … the acute effect of creatine on working memory reported in some studies at doses of 20 g/day given for 5-7 days … was not observed at lower creatine doses, ranging from 2.2 to 14 g/day …"
      ]
    }
  ]
}
```

Trimmed to one result with shortened excerpts. The `takeaway` gives you the paper's conclusion; the `full_text_chunks` give you the doses and study designs behind it, each labeled with the section of the paper it came from.

## What people build with the API

<Card title="What you can build with the Consensus API" icon="compass" href="/use-cases">
  Teams use the API to power internal research tools, field-monitoring agents, and scientific agents. Phylo calls it directly from its agents to screen about 20,000 drug targets across hundreds of diseases. Browse the use cases.
</Card>

* **Internal tools:** paper search for scientific agents, field-monitoring agents, and literature tables that fill themselves.
* **Research systems:** literature review pipelines, citation-grounded writing, and recurring evidence reports.

## Full text in the API

Every search reaches inside the paper. Queries are matched against full text where available, and on paid plans `include_full_text_chunks=true` returns the passages from each open-access paper that answer your query.

<Card title="Full text in the API" icon="file-text" href="/api-full-text">
  What comes back, which papers have excerpts, plan availability, and how to use them.
</Card>

**Base URL**

```
https://api.consensus.app
```

## Authentication

Every request must include your API key in the `x-api-key` header.

```http theme={null}
x-api-key: YOUR_API_KEY
```

<Note>
  Don't have a key yet? Create an API key from your API & MCP Dashboard at [consensus.app/api-mcp](https://consensus.app/api-mcp/). See [plans and access](/api-plans-and-access) for what each plan includes.
</Note>

## Make your first request

Pass a `query` — the only required parameter. Store your key in an environment variable named `CONSENSUS_API_KEY` first.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.consensus.app/v1/search?query=creatine%20and%20cognitive%20function" \
    -H "x-api-key: $CONSENSUS_API_KEY"
  ```

  ```python Python theme={null}
  import os
  import requests

  resp = requests.get(
      "https://api.consensus.app/v1/search",
      headers={"x-api-key": os.environ["CONSENSUS_API_KEY"]},
      params={"query": "creatine and cognitive function"},
  )
  resp.raise_for_status()

  for paper in resp.json()["results"]:
      print(paper["title"], "—", paper["journal_name"], paper["publish_year"])
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ query: "creatine and cognitive function" });

  const resp = await fetch(`https://api.consensus.app/v1/search?${params}`, {
    headers: { "x-api-key": process.env.CONSENSUS_API_KEY },
  });
  const { results } = await resp.json();

  for (const paper of results) {
    console.log(paper.title, "—", paper.journal_name, paper.publish_year);
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"encoding/json"
  	"fmt"
  	"net/http"
  	"net/url"
  	"os"
  )

  func main() {
  	req, _ := http.NewRequest("GET", "https://api.consensus.app/v1/search", nil)
  	req.Header.Set("x-api-key", os.Getenv("CONSENSUS_API_KEY"))
  	req.URL.RawQuery = url.Values{"query": {"creatine and cognitive function"}}.Encode()

  	resp, err := http.DefaultClient.Do(req)
  	if err != nil {
  		panic(err)
  	}
  	defer resp.Body.Close()

  	var body struct {
  		Results []struct {
  			Title       string `json:"title"`
  			JournalName string `json:"journal_name"`
  			PublishYear int    `json:"publish_year"`
  		} `json:"results"`
  	}
  	json.NewDecoder(resp.Body).Decode(&body)

  	for _, paper := range body.Results {
  		fmt.Printf("%s — %s %d\n", paper.Title, paper.JournalName, paper.PublishYear)
  	}
  }
  ```

  ```php PHP theme={null}
  <?php

  $query = urlencode("creatine and cognitive function");
  $ch = curl_init("https://api.consensus.app/v1/search?query={$query}");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: " . getenv("CONSENSUS_API_KEY")]);

  $data = json_decode(curl_exec($ch), true);
  curl_close($ch);

  foreach ($data["results"] as $paper) {
      echo "{$paper['title']} — {$paper['journal_name']} {$paper['publish_year']}\n";
  }
  ```

  ```ruby Ruby theme={null}
  require "net/http"
  require "json"
  require "uri"

  uri = URI("https://api.consensus.app/v1/search")
  uri.query = URI.encode_www_form(query: "creatine and cognitive function")

  req = Net::HTTP::Get.new(uri)
  req["x-api-key"] = ENV["CONSENSUS_API_KEY"]

  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

  JSON.parse(res.body)["results"].each do |paper|
    puts "#{paper['title']} — #{paper['journal_name']} #{paper['publish_year']}"
  end
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class Search {
      public static void main(String[] args) throws Exception {
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create("https://api.consensus.app/v1/search?query=creatine%20and%20cognitive%20function"))
              .header("x-api-key", System.getenv("CONSENSUS_API_KEY"))
              .build();

          HttpResponse<String> response = HttpClient.newHttpClient()
              .send(request, HttpResponse.BodyHandlers.ofString());

          // Parse response.body() with your preferred JSON library (Jackson, Gson, ...)
          System.out.println(response.body());
      }
  }
  ```
</CodeGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Search endpoint reference" icon="code" href="/api-reference/query-for-relevant-papers">
    Full parameter list, response schema, and interactive playground.
  </Card>

  <Card title="API on GitHub" icon="github" href="https://github.com/Consensus-NLP/consensus-api">
    Client code, examples, and issues for the Consensus API.
  </Card>

  <Card title="MCP server" icon="plug" href="/consensus-mcp">
    Prefer a no-code path? Connect Consensus to Claude, ChatGPT, and other MCP clients.
  </Card>

  <Card title="Consensus website" icon="globe" href="https://consensus.app">
    Explore the Consensus research platform.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.