Research API
Overview
The Research API allows users to converse with an AI research assistant grounded in a dataset of indexed articles. The API is designed to handle complex, multi-turn interactions through the following core concepts:
- Conversation Management: Mechanisms for maintaining context across synchronous requests and reconstructing past dialogue history.
- Research Modes: Configurable strategies to perform research, allowing users to choose, for example, between fast and comprehensive analysis, even within the same conversation.
- Source Deduplication: Intelligent handling of duplicate articles and text chunks to improve retrieval and citations.
- Streaming Capabilities: Support for response streaming to provide better responsiveness and progress updates.
Research modes and deduplication are configured per dataset.
The API is synchronous. For extended conversations, the response time might be quite high, especially for the non-streaming endpoint, where a response might take several minutes. In the event of a timeout, the client should resend the request.
Endpoints
| Endpoint | Description | |
|---|---|---|
| Request | 200 Response | |
| POST /v1/articles/research | Interacts with the research agent. | |
| ResearchRequest | ResearchResponse | |
| POST /v1/articles/research/stream | Interacts with the research agent, receiving a stream of responses. | |
| ResearchRequest | A stream of ResearchStreamResponse | |
POST /v1/articles/research
Interacts with the research agent.
- Request: ResearchRequest
The considered articles can be restricted using filters. - Response: ResearchResponse
Sometimes, the response time might be quite high; for a better user experience, consider using the streaming endpoint instead.
Examples
These examples show abbreviated versions of the API request and response objects in JSON. They are inspired by conversations with the research agent on a dataset of ~3.5k scientific articles in English scraped from the www.snexplores.org and www.sciencenews.org websites.
Simple query with mode
Request
{
"query": "How old is the universe?",
"mode": "lightweight"
}
Response
{
"interactionId": "3a0316b7-3632-40ab-98c2-a5fb3cb79eed",
"answer": {
"status": "answer",
"parts": [
{
"text": "The most recent and accurate measurements indicated that the universe was approximately 13.81 billion years old.",
"sourceChunkIds": [
"C_1"
],
"title": "Universe's Age: 13.81 Billion Years"
},
{
"text": "This estimate was based on data from the European Space Agency's Planck space telescope, which measured the cosmic microwave background radiation left over from the Big Bang.",
"sourceChunkIds": [
"C_1"
],
"title": "Planck Telescope Data"
},
{
"text": "Other methods, such as studying the oldest white dwarf stars and the rate of cosmic expansion, also yielded similar age estimates, generally between 13 and 14 billion years.",
"sourceChunkIds": [
"C_2"
],
"title": "Other Methods Confirmed Age"
},
{
"text": "Earlier studies had suggested the universe was about 80 million years younger, but newer findings revised the age upward to 13.81 billion years.",
"sourceChunkIds": [
"C_1"
],
"title": "Revised Age Estimate"
},
{
"text": "Observations of ancient galaxies and the timing of the first stars forming further supported these age estimates, showing galaxies existed just 600 to 700 million years after the Big Bang.",
"sourceChunkIds": [
"C_2",
"C_3"
],
"title": "Ancient Galaxies Support Estimate"
}
]
},
"chunks": [
{
"chunkId": "C_1",
"score": 0.85869217,
"text": "This map shows the energy left over from shortly after the Big Bang, as mapped by the Planck space telescope. ...",
"paraRefs": [
{
"paragraphId": "P_1",
"offset": 0,
"length": 4142
}
]
},
{
"chunkId": "C_2",
"score": 0.792276,
"text": "By setting their sights on the galaxy's faintest stars, scientists have calculated the universe's age in an entirely new way. ...",
"paraRefs": [
{
"paragraphId": "P_2",
"offset": 0,
"length": 3114
}
]
},
{
"chunkId": "C_3",
"score": 0.77157986,
"text": "How old are the objects you can see in the sky? The brightest star in the night sky, Sirius, is believed to be about 200-300 million years old. ...",
"paraRefs": [
{
"paragraphId": "P_3",
"offset": 0,
"length": 4212
}
]
}
],
"paragraphs": [
{
"articleId": "https:||www.sciencenews.org|article|faded-stars-get-new-role-hubble-takes-long-look",
"paragraphId": "P_2",
"type": "BODY",
"language": "en",
"text": "By setting their sights on the galaxy's faintest stars, scientists have calculated the universe's age in an entirely new way. ..."
},
{
"articleId": "https:||www.snexplores.org|article|galaxies-far-far-far-away",
"paragraphId": "P_3",
"type": "BODY",
"language": "en",
"text": "How old are the objects you can see in the sky? The brightest star in the night sky, Sirius, is believed to be about 200-300 million years old. ..."
},
{
"articleId": "https:||www.snexplores.org|article|new-older-age-universe",
"paragraphId": "P_1",
"type": "BODY",
"language": "en",
"text": "This map shows the energy left over from shortly after the Big Bang, as mapped by the Planck space telescope. ..."
}
]
}
Query with a conversation history
Request
{
"query": "How old is the universe?",
"returnHistory": true
}
Response
{
"interactionId": "3a0316b7-3632-40ab-98c2-a5fb3cb79eed",
"answer": {
"status": "answer",
"parts": [
{
"text": "The most recent and accurate measurements indicated that the universe was approximately 13.81 billion years old.",
"sourceChunkIds": [
"C_1"
],
"title": "Universe's Age: 13.81 Billion Years"
},
{
"text": "This estimate was based on data from the European Space Agency's Planck space telescope, which measured the cosmic microwave background radiation left over from the Big Bang.",
"sourceChunkIds": [
"C_1"
],
"title": "Planck Telescope Data"
},
{
"text": "Other methods, such as studying the oldest white dwarf stars and the rate of cosmic expansion, also yielded similar age estimates, generally between 13 and 14 billion years.",
"sourceChunkIds": [
"C_2"
],
"title": "Other Methods Confirmed Age"
},
{
"text": "Earlier studies had suggested the universe was about 80 million years younger, but newer findings revised the age upward to 13.81 billion years.",
"sourceChunkIds": [
"C_1"
],
"title": "Revised Age Estimate"
},
{
"text": "Observations of ancient galaxies and the timing of the first stars forming further supported these age estimates, showing galaxies existed just 600 to 700 million years after the Big Bang.",
"sourceChunkIds": [
"C_2",
"C_3"
],
"title": "Ancient Galaxies Support Estimate"
}
]
},
"chunks": [
{
"chunkId": "C_1",
"score": 0.85869217,
"text": "This map shows the energy left over from shortly after the Big Bang, as mapped by the Planck space telescope. ...",
"paraRefs": [
{
"paragraphId": "P_1",
"offset": 0,
"length": 4142
}
]
},
{
"chunkId": "C_2",
"score": 0.792276,
"text": "By setting their sights on the galaxy's faintest stars, scientists have calculated the universe's age in an entirely new way. ...",
"paraRefs": [
{
"paragraphId": "P_2",
"offset": 0,
"length": 3114
}
]
},
{
"chunkId": "C_3",
"score": 0.77157986,
"text": "How old are the objects you can see in the sky? The brightest star in the night sky, Sirius, is believed to be about 200-300 million years old. ...",
"paraRefs": [
{
"paragraphId": "P_3",
"offset": 0,
"length": 4212
}
]
}
],
"paragraphs": [
{
"articleId": "https:||www.sciencenews.org|article|faded-stars-get-new-role-hubble-takes-long-look",
"paragraphId": "P_2",
"type": "BODY",
"language": "en",
"text": "By setting their sights on the galaxy's faintest stars, scientists have calculated the universe's age in an entirely new way. ..."
},
{
"articleId": "https:||www.snexplores.org|article|galaxies-far-far-far-away",
"paragraphId": "P_3",
"type": "BODY",
"language": "en",
"text": "How old are the objects you can see in the sky? The brightest star in the night sky, Sirius, is believed to be about 200-300 million years old. ..."
},
{
"articleId": "https:||www.snexplores.org|article|new-older-age-universe",
"paragraphId": "P_1",
"type": "BODY",
"language": "en",
"text": "This map shows the energy left over from shortly after the Big Bang, as mapped by the Planck space telescope. ..."
}
],
"history": [
{
"question": {
"query": "How old is the universe?"
},
"answer": {
"parts": [
{
"text": "The most recent and accurate measurements indicated that the universe was approximately 13.81 billion years old.",
"title": "Universe's Age: 13.81 Billion Years"
},
{
"text": "This estimate was based on data from the European Space Agency's Planck space telescope, which measured the cosmic microwave background radiation left over from the Big Bang.",
"title": "Planck Telescope Data"
},
{
"text": "Other methods, such as studying the oldest white dwarf stars and the rate of cosmic expansion, also yielded similar age estimates, generally between 13 and 14 billion years.",
"title": "Other Methods Confirmed Age"
},
{
"text": "Earlier studies had suggested the universe was about 80 million years younger, but newer findings revised the age upward to 13.81 billion years.",
"title": "Revised Age Estimate"
},
{
"text": "Observations of ancient galaxies and the timing of the first stars forming further supported these age estimates, showing galaxies existed just 600 to 700 million years after the Big Bang.",
"title": "Ancient Galaxies Support Estimate"
}
]
}
}
]
}
Query with previousInteractionId
Request
{
"query": "Explain in detail why the universe is older than expected.",
"returnHistory": true,
"previousInteractionId": "3a0316b7-3632-40ab-98c2-a5fb3cb79eed",
"history": [
{
"question": {
"query": "How old is the universe?"
},
"answer": {
"parts": [
{
"text": "The most recent and accurate measurements indicated that the universe was approximately 13.81 billion years old."
},
{
"text": "This estimate was based on data from the European Space Agency's Planck space telescope, which measured the cosmic microwave background radiation left over from the Big Bang."
},
{
"text": "Other methods, such as studying the oldest white dwarf stars and the rate of cosmic expansion, also yielded similar age estimates, generally between 13 and 14 billion years."
},
{
"text": "Earlier studies had suggested the universe was about 80 million years younger, but newer findings revised the age upward to 13.81 billion years."
},
{
"text": "Observations of ancient galaxies and the timing of the first stars forming further supported these age estimates, showing galaxies existed just 600 to 700 million years after the Big Bang."
}
]
}
}
]
}
Response
{
"interactionId": "7fe0ab26-ab18-470f-bad7-95cadcda3a22",
"answer": {
"status": "answer",
"parts": [
{
"text": "The universe was found to be older than previously expected due to new, more precise measurements and observations from advanced telescopes like Hubble and Planck.",
"sourceChunkIds": [
"C_1",
"C_2"
],
"title": "Universe older than expected"
},
{
"text": "Scientists used two independent methods to estimate the universe's age: observing the oldest white dwarfs in globular clusters and measuring the cosmic microwave background radiation.",
"sourceChunkIds": [
"C_1",
"C_2"
],
"title": "Two independent age estimates"
},
{
"text": "The Hubble Space Telescope observed the dimmest, oldest white dwarfs in a globular cluster, determining their ages to be 12 to 13 billion years, which set a minimum age for the universe.",
"sourceChunkIds": [
"C_1"
],
"title": "White dwarf observations"
},
{
"text": "Combining the ages of the oldest stars with the time it took for the first stars to form after the Big Bang, scientists estimated the universe's age to be 13 to 14 billion years, higher than some earlier estimates.",
"sourceChunkIds": [
"C_1"
],
"title": "Revised age from star data"
},
{
"text": "The Planck space telescope provided the most accurate measurement of the cosmic microwave background, revising the universe's age to about 13.81 billion years—about 80 million years older than previous estimates.",
"sourceChunkIds": [
"C_2"
],
"title": "Planck telescope findings"
},
{
"text": "The agreement between the white dwarf method and the cosmic expansion method increased confidence in the revised, older age of the universe.",
"sourceChunkIds": [
"C_1"
],
"title": "Agreement between methods"
},
{
"text": "New Hubble images revealed ancient galaxies that formed just 600 to 700 million years after the Big Bang, indicating that galaxy formation began earlier than previously thought and suggesting a more mature early universe.",
"sourceChunkIds": [
"C_3"
],
"title": "Early galaxy formation"
},
{
"text": "The discovery of mature galaxies so soon after the Big Bang challenged previous assumptions about the timeline of galaxy and structure formation, contributing to the perception that the universe was 'older than expected.'",
"sourceChunkIds": [
"C_3"
],
"title": "Challenged previous assumptions"
}
]
},
"chunks": [
{
"chunkId": "C_1",
"score": 0.75029355,
"text": "By setting their sights on the galaxy's faintest stars, scientists have calculated the universe's age in an entirely new way.\n\nAssuming that the age of the dimmest, oldest stars would give a minimum age for the universe, astronomers including Harvey Richer of the University of British Columbia and his colleagues set out to find some of these old-timers ( SN: 9/2/95, p. 151; 2/10/01, p. 85 ).\n\nRicher's team has now pushed the Hubble Space Telescope's vision to the limit by looking at some of the Milky Way's least-luminous white dwarfs�embers of stars that depleted their hydrogen fuel long ago.\n\nThe scientists found ancient white dwarfs inside a globular star cluster 7,000 light-years away. Globular clusters are among the oldest groups of stars in the universe, and some of the stars are only one-billionth as bright as the faintest ones visible to the naked eye. It took 8 days of exposure for Hubble cameras to detect the dim white dwarfs.\n\nWhite dwarfs start out hot but cool in a highly predictable manner. The coolest, dimmest dwarfs observed by Hubble are the oldest. Richer and his team calculated that these stars are 12 to 13 billion years old. Previous observations suggest that the very first stars formed less than a billion years after the Big Bang. So, the combined data yield 13 to 14 billion years as the age of the universe. The findings were announced at a NASA press briefing in Washington, D.C., on April 24 and are slated for publication in Astrophysical Journal Letters .\n\nOver the years, estimates of the universe's age have varied between 8 billion and 20 billion years. One of the most recent and best guesses also used data collected by Hubble to arrive at an age of 13 to 14 billion years, Richer says. That estimate required measuring the universe's rate of expansion. This was determined by Wendy Freedman of the Carnegie Observatories in Pasadena, Calif., and her colleagues. With a complex calculation that incorporates the effects of gravity, dark energy, and other exotica, these researchers modeled cosmic expansion in reverse, so that it runs from the present back to the moment of the Big Bang ( SN: 5/29/99, p. 340 ).\n\n\"Some scientists think it's pretty audacious that astronomers can claim to measure the age of the universe,\" says Bruce Margon of the Space Telescope Science Institute in Baltimore, who was not a member of either research team. \"To suddenly find some totally independent way of estimating this same vital quantity and to get the same answer is really a fantastic advance,\" he adds.\n\nAstrophysicist Brian Chaboyer of Dartmouth College in Hanover, N.H., cautions that the newly estimated age could be low since the white dwarfs observed by Richer's team were probably not among the universe's very first stars. Even so, he adds, the fact that the independently produced figures fall in the same range as prior estimates \"gives us a lot of confidence that we really are getting the right answer.\"\n\nRicher and his colleagues now plan to search for other dim stars with Hubble's new Advanced Camera for Surveys (see \"Sharper Images\" in this week's issue).",
"paraRefs": [
{
"paragraphId": "P_1",
"offset": 0,
"length": 3114
}
]
},
{
"chunkId": "C_2",
"score": 0.79636276,
"text": "This map shows the energy left over from shortly after the Big Bang, as mapped by the Planck space telescope. The average background temperature is about 2.7 degrees above the coldest possible temperature (known as absolute zero). Red spots are slightly warmer, while blue spots are slightly cooler. Astronomers hope this map can help them learn more about the history of the universe. European Science Agency, Planck Collaboration\n\nA new study of the age of the universe shows that it's about 80 million years older than scientists had previously thought. For a place we now believe to be 13.81 billion years old, that few extra tens of millions of years isn't much of a change. It's roughly like finding out a friend is actually 13, and not just 12 years and 11 months old.\n\nScientists measure the age of the universe by studying what is called the cosmic microwave background radiation. That radiation is energy. And it is left over from just after the Big Bang, the violent expansion of space and energy that marked the birth of the universe. In the billions of years since then, the energy has spread almost evenly throughout the universe. (Some spots are slightly warmer; others slightly cooler.)\n\nNow, a new study has used the European Space Agency's Planck space telescope to make the most accurate measurement to date of that leftover energy. Planck orbits the sun and stares deep into space - and back in time. The ancient glow that reaches its instruments is the oldest light in the cosmos.\n\nThe new map of the universe created from the Planck data accomplishes two things. First, it lines up with previous maps of the universe. That is a good thing, since it doesn't clash with older theories about the history of the universe. Second, the Planck map reveals a few unexpected quirks scattered here and there. That's also a good thing: Studying those quirks may lead to new discoveries about the universe.\n\n\"The clarity and precision of Planck's map is stunning,\" Richard Easther told Science News . \"It's as good as anyone could have hoped for.\" Easther, who did not work on the new Planck study, is an astrophysicist at the University of Auckland in New Zealand.\n\nThe Planck telescope acts like a sensitive thermometer. It's not the first instrument to take the universe's temperature, but it is the most precise. The satellite can detect even tiny changes in that background temperature. These changes, over billions of years, led to the formation of stars and galaxies.\n\nAstrophysicist George Efstathiou from the University of Cambridge in England presented the new map at a recent meeting in Paris. He said the map may look like a \"dirty rugby ball,\" but is very important. He joked that in the past, some scientists \"would have given up their children to get a copy.\"\n\nThe Planck data line up with many theories about the early universe. One of these is called inflation. According to this theory, the universe expanded faster than the speed of light in a short burst right after the Big Bang. Inflation can help explain how the universe got so big, so fast.\n\nThe new data also give new evidence for a longstanding cosmic puzzle. There are more small changes in temperature if you look one direction in the universe than in the other. And scientists don't know why that should be.\n\nSome physicists hope to find that this lopsidedness will give evidence that our universe collided long ago with another universe. That's what physicist Matthew Kleban, from New York University, will be looking for in the Planck data. For now, he told Science News , it's too early to know for sure. However, he added, \"it looks like there is some very interesting work to be done.\"\n\nPower Words\n\nastronomy The branch of science that deals with celestial objects, space and the physical universe as a whole.\n\ncosmology The science of the origin and development of the cosmos , or universe.\n\nradiation Energy emitted by a source that travels through space in waves. Examples include visible light, infrared energy and microwaves.\n\nBig Bang The rapid expansion of dense matter that, according to current theory, marked the origin of the universe.",
"paraRefs": [
{
"paragraphId": "P_2",
"offset": 0,
"length": 4142
}
]
},
{
"chunkId": "C_3",
"score": 0.74372715,
"text": "How old are the objects you can see in the sky? The brightest star in the night sky, Sirius, is believed to be about 200-300 million years old. The Sun and Moon are much older-about 4.5 billion years old.\n\nThese new images of distant galaxies come from the newly installed Wide Field Camera 3 on the Hubble Space Telescope. Clockwise from top left: NGC 6302, a butterfly-shaped nebula surrounding a dying star; a group of galaxies called Stephan's Quintet; a star-forming region in the Carina Nebula; a group of 100,000 stars residing in the crowded core of Omega Centauri, a giant globular cluster. NASA, ESA, and the Hubble SM4 ERO Team\n\nNew pictures taken by a telescope in space show ancient galaxies that blow those numbers away. Some show galaxies that are about 13 billion years old. The universe itself is only about 13.7 billion years old. So these galaxies formed when the universe was very young.\n\nGarth Illingworth is an astronomer at the University of California, Santa Cruz. He is part of one team that studied the ancient galaxies in the pictures. \"We are looking back 13 billion years and seeing galaxies just 600 to 700 million years after the Big Bang, when the Universe was like a 4-year-old,\" he says.\n\nThe pictures came from the Hubble Space Telescope. It floats through space around the Earth, 353 miles up. For 19 years, this orbiting telescope has been beaming back pictures of deep space to astronomers, who study the images to learn more about the universe and our place in it.\n\nThree teams of scientists studied the pictures. All three found that the most distant reaches of space have fewer bright galaxies than closer regions. This dropoff in the number of galaxies was not surprising, based on what astronomers already knew about the universe. To look deep into space is to look back in time. That's because light from faraway galaxies takes a long time to reach Earth. When astronomers look at a picture of a distant star or galaxy, they are seeing light that took billions of years to travel to Earth. So when scientists look at these new pictures of distant galaxies, they see the star or galaxy as it looked millions or billions of years ago. This may be at a time when the first galaxies were just forming.\n\nTo take these pictures, the telescope used a new tool called the Wide Field Camera 3, or WFC3. Astronauts installed this camera on the telescope in May of this year during a repair mission. Like an ordinary camera, this one takes pictures using visible light. But in addition, it also records snapshots at wavelengths the eye can not see, including ultraviolet light and infrared light\n\nResearchers are excited about the WFC3, which is more sophisticated than earlier cameras on board the Hubble. \"This is a golden moment,\" says Richard Ellis of Caltech in Pasadena, who also studied the pictures.\n\nAll of the galaxies in these pictures showed up in a tiny area of the sky. This slice of sky is so small that 150 pieces the same size would fit into the apparent size of a full moon. Because this slice of the sky is so small and the WFC3 just started taking pictures this summer, the scientists say they're not sure that they'll find similar galaxies in every direction.\n\nBut they do believe the WFC3 will give scientists some very interesting information about the early universe. \"This is a very exciting time,\" says Ellis.\n\nPOWER WORDS (adapted from the Yahoo! Kids Dictionary)\n\nbillion : 1,000,000,000, or 1,000 million\n\ngalaxy : A collection of stars, gas and dust that make up the universe. A galaxy contains an average of 100 billion solar masses (or 100 billion times the weight of the sun) and ranges in diameter from 1,500 to 300,000 light-years.\n\ninfrared radiation : The range of invisible radiation wavelengths from about 750 nanometers to 1 millimeter, on the border of the microwave region.\n\nultraviolet radiation : The range of invisible radiation wavelengths from about 4 nanometers, on the border of the x-ray region, to about 380 nanometers, just beyond the violet in the visible spectrum.\n\ntelescope : An arrangement of lenses or mirrors or both that gathers visible light, permitting direct observation or photographic recording of distant objects.",
"paraRefs": [
{
"paragraphId": "P_3",
"offset": 0,
"length": 4212
}
]
}
],
"paragraphs": [
{
"articleId": "https:||www.sciencenews.org|article|faded-stars-get-new-role-hubble-takes-long-look",
"paragraphId": "P_1",
"type": "BODY",
"language": "en",
"text": "By setting their sights on the galaxy's faintest stars, scientists have calculated the universe's age in an entirely new way. ..."
},
{
"articleId": "https:||www.snexplores.org|article|galaxies-far-far-far-away",
"paragraphId": "P_3",
"type": "BODY",
"language": "en",
"text": "How old are the objects you can see in the sky? The brightest star in the night sky, Sirius, is believed to be about 200-300 million years old. The Sun and Moon are ..."
},
{
"articleId": "https:||www.snexplores.org|article|new-older-age-universe",
"paragraphId": "P_2",
"type": "BODY",
"language": "en",
"text": "This map shows the energy left over from shortly after the Big Bang, as mapped by the Planck space telescope. The average background temperature ..."
}
],
"history": [
{
"question": {
"query": "How old is the universe?"
},
"answer": {
"parts": [
{
"text": "The most recent and accurate measurements indicated that the universe was approximately 13.81 billion years old."
},
{
"text": "This estimate was based on data from the European Space Agency's Planck space telescope, which measured the cosmic microwave background radiation left over from the Big Bang."
},
{
"text": "Other methods, such as studying the oldest white dwarf stars and the rate of cosmic expansion, also yielded similar age estimates, generally between 13 and 14 billion years."
},
{
"text": "Earlier studies had suggested the universe was about 80 million years younger, but newer findings revised the age upward to 13.81 billion years."
},
{
"text": "Observations of ancient galaxies and the timing of the first stars forming further supported these age estimates, showing galaxies existed just 600 to 700 million years after the Big Bang."
}
]
}
},
{
"question": {
"query": "Explain in detail why is the universe older than expected?"
},
"answer": {
"parts": [
{
"text": "The universe was found to be older than previously expected due to new, more precise measurements and observations from advanced telescopes like Hubble and Planck."
},
{
"text": "Scientists used two independent methods to estimate the universe's age: observing the oldest white dwarfs in globular clusters and measuring the cosmic microwave background radiation."
},
{
"text": "The Hubble Space Telescope observed the dimmest, oldest white dwarfs in a globular cluster, determining their ages to be 12 to 13 billion years, which set a minimum age for the universe."
},
{
"text": "Combining the ages of the oldest stars with the time it took for the first stars to form after the Big Bang, scientists estimated the universe's age to be 13 to 14 billion years, higher than some earlier estimates."
},
{
"text": "The Planck space telescope provided the most accurate measurement of the cosmic microwave background, revising the universe's age to about 13.81 billion years—about 80 million years older than previous estimates."
},
{
"text": "The agreement between the white dwarf method and the cosmic expansion method increased confidence in the revised, older age of the universe."
},
{
"text": "New Hubble images revealed ancient galaxies that formed just 600 to 700 million years after the Big Bang, indicating that galaxy formation began earlier than previously thought and suggesting a more mature early universe."
},
{
"text": "The discovery of mature galaxies so soon after the Big Bang challenged previous assumptions about the timeline of galaxy and structure formation, contributing to the perception that the universe was 'older than expected.'"
}
]
}
}
]
}
Response with duplicates
Request
{
"query": "How old is the universe?",
"returnDuplicates": true
}
Response
{
"interactionId": "f3a3bf9c-4458-4476-b94f-304996d31e83",
"answer": {
"status": "answer",
"parts": [
{
"text": "The most recent and accurate measurements indicated that the universe was approximately 13.81 billion years old.",
"sourceChunkIds": [
"C_1"
]
}
]
},
"chunks": [
{
"chunkId": "C_1",
"score": 0.85869217,
"text": "This map shows the energy left over from shortly after the Big Bang, as mapped by the Planck space telescope. ...",
"paraRefs": [
{
"paragraphId": "P_1",
"offset": 0,
"length": 4142
}
]
}
],
"paragraphs": [
{
"articleId": "https:||www.snexplores.org|article|new-older-age-universe",
"paragraphId": "P_1",
"type": "BODY",
"language": "en",
"text": "This map shows the energy left over from shortly after the Big Bang, as mapped by the Planck space telescope. ..."
}
],
"chunkDuplicates": [
{
"leaderId": "C_1",
"duplicateId": "C_2",
"text": "This map shows the energy left over from shortly after the Big Bang, as mapped by the Planck space telescope. ...",
"paraRefs": [
{
"paragraphId": "P_2",
"offset": 0,
"length": 4142
}
]
}
],
"paragraphDuplicates": [
{
"articleId": "https:||www.snexplores.org|article|universe-age",
"paragraphId": "P_2",
"type": "BODY",
"language": "en",
"text": "This map shows the energy left over from shortly after the Big Bang, as mapped by the Planck space telescope. ..."
}
]
}
No supporting facts found
Request
{
"query": "Why is the Earth flat?"
}
Response
Please note that there are neither sourceChunkIds nor title fields in the answer part of this API response.
{
"interactionId": "1c2bd1b0-c720-4a45-9587-d794161a3cb8",
"answer": {
"status": "error:insufficient-info",
"parts": [
{
"text": "I am sorry, but there is not enough relevant information in the archive to answer your request.",
"sourceChunkIds": []
}
]
},
"chunks": [],
"paragraphs": []
}
POST /v1/articles/research/stream
A variant of the research endpoint that streams the response in smaller pieces instead of waiting for the full response to be generated. It also allows sending intermediate messages during processing, making the user experience more responsive.
-
Request:
ResearchRequest - identical to the/v1/articles/researchrequest object
Required header:Accept: application/x-ndjson
The considered articles can be restricted using filters. -
Response:
A stream of ResearchStreamResponse objects in NDJSON format (newline-delimited JSON)
Response header:Content-Type: application/x-ndjson
The streaming API is unidirectional:
- The server streams the response gradually.
- The client cannot send asynchronous messages back while the stream is open.
- A new request can only be initiated after the server finishes streaming the previous response.
- If the user sends another request while a stream is active, it is processed independently and does not affect the ongoing stream.
Example
Request - Simple query
{
"query": "How old is the universe?"
}
The server sends the response as a stream of JSON objects, one per line, delimited by \n (NDJSON).
Progress messages
{"type": "message", "content": {"message": "Assessing the query..."}}
{"type": "message", "content": {"message": "Searching for relevant articles..."}}
{"type": "message", "content": {"message": "Found 151 potentially relevant articles."}}
{"type": "message", "content": {"message": "Narrowing down the found articles..."}}
{"type": "message", "content": {"message": "Narrowed down to 32 relevant articles."}}
{"type": "message", "content": {"message": "Extracting and summarizing relevant information..."}}
Intermediate answer parts
Note that the following is formatted for readability:
the code is soft-wrapped; the actual new-lines are marked by an empty line;
in reality these would be three lines, each with one answer-part json object.
{
"type": "answer-part",
"content": {
"text": "The most recent and accurate measurements indicated that the universe was approximately 13.81 billion years old.",
"sourceChunkIds": [],
"title": "Universe's Age: 13.81 Billion Years"
}
}
{
"type": "answer-part",
"content": {
"text": "This estimate was based on data from the European Space Agency's Planck space telescope, which measured the cosmic microwave background radiation left over from the Big Bang.",
"sourceChunkIds": [],
"title": "Other Methods Confirmed Age"
}
}
{
"type": "answer-part",
"content": {
"text": "Earlier studies had suggested the universe was about 80 million years younger, but newer findings revised the age upward to 13.81 billion years.",
"sourceChunkIds": [],
"title": "Ancient Galaxies Support Estimate"
}
}
The full-response object always appears exactly once and is always the final streamed item.
Final full response
Note that the following is formatted for readability: the code is soft-wrapped; in reality the whole final item is a single line.
{
"type": "full-response",
"content": {
"interactionId": "3a0316b7-3632-40ab-98c2-a5fb3cb79eed",
"answer": {
"status": "answer",
"parts": [
{
"text": "The most recent and accurate measurements indicated that the universe was approximately 13.81 billion years old.",
"sourceChunkIds": [
"C_1"
],
"title": "Universe's Age: 13.81 Billion Years"
},
{
"text": "This estimate was based on data from the European Space Agency's Planck space telescope, which measured the cosmic microwave background radiation left over from the Big Bang.",
"sourceChunkIds": [
"C_1"
],
"title": "Planck Telescope Data"
},
{
"text": "Other methods, such as studying the oldest white dwarf stars and the rate of cosmic expansion, also yielded similar age estimates, generally between 13 and 14 billion years.",
"sourceChunkIds": [
"C_2"
],
"title": "Other Methods Confirmed Age"
},
{
"text": "Earlier studies had suggested the universe was about 80 million years younger, but newer findings revised the age upward to 13.81 billion years.",
"sourceChunkIds": [
"C_1"
],
"title": "Revised Age Estimate"
},
{
"text": "Observations of ancient galaxies and the timing of the first stars forming further supported these age estimates, showing galaxies existed just 600 to 700 million years after the Big Bang.",
"sourceChunkIds": [
"C_2",
"C_3"
],
"title": "Ancient Galaxies Support Estimate"
}
]
},
"chunks": [
{
"chunkId": "C_1",
"score": 0.85869217,
"text": "This map shows the energy left over from shortly after the Big Bang, as mapped by the Planck space telescope. ...",
"paraRefs": [
{
"paragraphId": "P_1",
"offset": 0,
"length": 4142
}
]
},
{
"chunkId": "C_2",
"score": 0.792276,
"text": "By setting their sights on the galaxy's faintest stars, scientists have calculated the universe's age in an entirely new way. ...",
"paraRefs": [
{
"paragraphId": "P_2",
"offset": 0,
"length": 3114
}
]
},
{
"chunkId": "C_3",
"score": 0.77157986,
"text": "How old are the objects you can see in the sky? The brightest star in the night sky, Sirius, is believed to be about 200-300 million years old. ...",
"paraRefs": [
{
"paragraphId": "P_3",
"offset": 0,
"length": 4212
}
]
}
],
"paragraphs": [
{
"articleId": "https:||www.sciencenews.org|article|faded-stars-get-new-role-hubble-takes-long-look",
"paragraphId": "P_2",
"type": "BODY",
"language": "en",
"text": "By setting their sights on the galaxy's faintest stars, scientists have calculated the universe's age in an entirely new way. ..."
},
{
"articleId": "https:||www.snexplores.org|article|galaxies-far-far-far-away",
"paragraphId": "P_3",
"type": "BODY",
"language": "en",
"text": "How old are the objects you can see in the sky? The brightest star in the night sky, Sirius, is believed to be about 200-300 million years old. ..."
},
{
"articleId": "https:||www.snexplores.org|article|new-older-age-universe",
"paragraphId": "P_1",
"type": "BODY",
"language": "en",
"text": "This map shows the energy left over from shortly after the Big Bang, as mapped by the Planck space telescope. ..."
}
]
}
}
Notes for UI Implementation
The main purpose of this streaming variant is to make the user interface feel more responsive. Depending on the query and dataset size, generating a full answer may take a long time (sometimes several minutes). Streaming allows progress updates and partial answers to be displayed sooner.
Recommended UI workflow:
- The user submits their query.
- The client sends a new request to /v1/articles/research.
- The server begins streaming response parts.
- The UI displays all received message parts as progress indicators.
- When the UI receives answer-part items, it should begin rendering the answer incrementally.
- When the final full-response item arrives, the UI should re-render the full answer, replacing any partial output.
- The response stream ends.
- The user may now submit the next query.
Research Response Objects
The chunk and paragraph id fields are only valid within a single API response. They are not global unique identifiers and carry no other meaning. They should only be used to locate chunk and paragraph objects within that response.
Metadata fields
The Article and ParaSpec objects can contain additional information referred to as metadata. Metadata can be used to attach information that is not processed on our side, but is returned in API responses, for example, your internal paragraph IDs. The metadata field is always optional in all request/response objects in all our API endpoints.
The list of metadata fields that are indexed must be set up before indexing the articles and can be configured separately for each API key.
Conversation Context
- Each API request is synchronous, but the conversation context can be carried over to the next call.
- The
interactionIduniquely identifies each question-answer pair (API request and response) within a single conversation. - Follow-up questions must refer to the
interactionIdfrom the previous interaction via thepreviousInteractionIdfield.
Conversation History
- The API response can include the conversation history if requested.
- The history contains a sequence of question-answer pairs, ordered from the oldest to the most recent.
- Conversation history and other context are stored server-side. For now, they will be persisted indefinitely, but in the future they may have an expiration time.
- The
historyfield in the API request allows the conversation to be reconstructed when necessary, for example, when the original server-side conversation data has already expired.
Relevant objects: HistoryInteraction, HistoryQuestion, HistoryAnswer, HistoryAnswerPart, ResearchStreamResponse.
Research Mode
- Depending on the configuration for a particular dataset, the API may support several modes of operation, e.g., “lightweight” or “deep”.
- The mode can be selected via the
modefield. The supported values are dataset-specific. If no mode is set, the default mode is used. - The mode can be specified in each API request, so it is possible to switch modes within a single conversation.