> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Publications
> Search the PubMed biomedical literature with free text, newest or most relevant first, with citation details and how many papers matched in all.
Searches PubMed, the US National Library of Medicine's index of biomedical papers, newest or most relevant first: title, journal, dates, first three authors, DOI, PubMed Central id, publication types and link. Only citation fields are returned, never an abstract or full text. The answer lists what a public index holds: it is for research and is not medical advice.
## Authentication
Requires x402 payment in the `payment-signature` header.
## Request Body
**query** `string` *required*
PubMed search text, for example semaglutide AND kidney; field tags such as \[Title] or \[MeSH Terms] and AND/OR/NOT are allowed. 2 to 300 characters.
**from\_year** `integer`
Only papers published in this year or later, no later than the current year. At least 1800.
**to\_year** `integer`
Only papers published in this year or earlier, no later than the current year. At least 1800.
**sort** `string`
newest (by publication date) or relevance. One of `newest`, `relevance`. Defaults to `"newest"`.
**limit** `integer`
The most papers to return. From 1 to 20. Defaults to `10`.
## Response (200 OK)
Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.
**data.request\_id** `string`
Durable job ID for audit and lookup
**data.status** `string`
Job status: `completed`
**data.tool** `string`
Always `record_publications_find`
**data.result** `object`
The answer, described under Result below
**data.evidence** `object`
Where the answer came from and when
**data.evidence.source** `string`
The public body the data comes from. Always `US National Library of Medicine (PubMed)`.
**data.evidence.source\_kind** `string`
`public` when the data comes from a public body, `commercial` otherwise
**data.evidence.retrieved\_at** `string`
When the lookup was made, as an ISO 8601 UTC time
**data.evidence.as\_of** `string | null`
The newest `published` date among the papers returned; null when nothing matched.
## Result
Nested under `data.result`.
**data.result.total** `integer`
How many papers matched, including any beyond `limit`.
**data.result.query\_translation** `string`
The search as the source expanded and ran it, for example with MeSH terms and the year range.
**data.result.publications** `object[]`
The papers returned, in the order asked for.
**data.result.publications\[].pmid** `string`
The PubMed id.
**data.result.publications\[].title** `string | null`
The title. `null` when the source gives no value.
**data.result.publications\[].journal** `string | null`
The journal's abbreviated name; null for a book chapter.
**data.result.publications\[].journal\_full** `string | null`
The journal's full name. `null` when the source gives no value.
**data.result.publications\[].published** `string | null`
The publication date the source sorts by, as YYYY-MM-DD. `null` when the source gives no value.
**data.result.publications\[].published\_text** `string | null`
The publication date as the source prints it, for example "2026 Dec 1" or "2026 Dec". `null` when the source gives no value.
**data.result.publications\[].authors** `string[]`
The first three author names, as the source abbreviates them; book editors listed on a chapter are not authors and are left out.
**data.result.publications\[].author\_count** `integer`
How many authors the paper has.
**data.result.publications\[].doi** `string | null`
The DOI; null when the source lists none.
**data.result.publications\[].pmcid** `string | null`
The PubMed Central id; null when the paper is not in PubMed Central.
**data.result.publications\[].publication\_types** `string[]`
The publication types, for example "Journal Article" or "Meta-Analysis".
**data.result.publications\[].url** `string`
The paper's page on PubMed.
```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/find/record-publications \
-H "Content-Type: application/json" \
-H "payment-signature: " \
-d '{
"query": "semaglutide AND kidney",
"from_year": 2024,
"to_year": 2026,
"sort": "relevance",
"limit": 3
}'
```
```javascript JavaScript theme={null}
const response = await fetch("https://win.oneshotagent.com/v1/tools/find/record-publications", {
method: "POST",
headers: {
"Content-Type": "application/json",
"payment-signature": paymentProof,
},
body: JSON.stringify({
"query": "semaglutide AND kidney",
"from_year": 2024,
"to_year": 2026,
"sort": "relevance",
"limit": 3
}),
});
```
```typescript SDK theme={null}
const result = await agent.tool('find/record-publications', {
query: 'semaglutide AND kidney',
from_year: 2024,
to_year: 2026,
sort: 'relevance',
limit: 3
});
console.log(result.result);
console.log(result.evidence);
```
```json Response (200) theme={null}
{
"success": true,
"data": {
"request_id": "uuid",
"receipt_id": "rcpt_...",
"status": "completed",
"tool": "record_publications_find",
"result": {
"total": 443,
"query_translation": "(\"semaglutide\"[Supplementary Concept] OR \"semaglutide\"[All Fields] OR \"semaglutide\"[MeSH Terms]) AND (\"kidney\"[MeSH Terms] OR \"kidney\"[All Fields] OR \"kidneys\"[All Fields] OR \"kidney s\"[All Fields]) AND 2024/01/01:2026/12/31[Date - Publication]",
"publications": [
{
"pmid": "38785209",
"title": "Effects of Semaglutide on Chronic Kidney Disease in Patients with Type 2 Diabetes.",
"journal": "N Engl J Med",
"journal_full": "The New England journal of medicine",
"published": "2024-07-11",
"published_text": "2024 Jul 11",
"authors": [
"Perkovic V",
"Tuttle KR",
"Rossing P"
],
"author_count": 12,
"doi": "10.1056/NEJMoa2403347",
"pmcid": null,
"publication_types": [
"Journal Article",
"Randomized Controlled Trial",
"Multicenter Study",
"Research Support, N.I.H., Extramural"
],
"url": "https://pubmed.ncbi.nlm.nih.gov/38785209/"
},
{
"pmid": "40892610",
"title": "Cardiovascular Effects and Tolerability of GLP-1 Receptor Agonists: A Systematic Review and Meta-Analysis of 99,599 Patients.",
"journal": "J Am Coll Cardiol",
"journal_full": "Journal of the American College of Cardiology",
"published": "2025-11-18",
"published_text": "2025 Nov 18",
"authors": [
"Galli M",
"Benenati S",
"Laudani C"
],
"author_count": 17,
"doi": "10.1016/j.jacc.2025.08.027",
"pmcid": null,
"publication_types": [
"Journal Article",
"Systematic Review",
"Meta-Analysis"
],
"url": "https://pubmed.ncbi.nlm.nih.gov/40892610/"
},
{
"pmid": "40961952",
"title": "Once-weekly semaglutide 7·2 mg in adults with obesity (STEP UP): a randomised, controlled, phase 3b trial.",
"journal": "Lancet Diabetes Endocrinol",
"journal_full": "The lancet. Diabetes & endocrinology",
"published": "2025-11-01",
"published_text": "2025 Nov",
"authors": [
"Wharton S",
"Freitas P",
"Hjelmesæth J"
],
"author_count": 10,
"doi": "10.1016/S2213-8587(25)00226-8",
"pmcid": null,
"publication_types": [
"Journal Article",
"Randomized Controlled Trial",
"Clinical Trial, Phase III",
"Multicenter Study",
"Research Support, N.I.H., Extramural"
],
"url": "https://pubmed.ncbi.nlm.nih.gov/40961952/"
}
]
},
"evidence": {
"source": "US National Library of Medicine (PubMed)",
"source_kind": "public",
"retrieved_at": "2026-10-25T12:00:00.000Z",
"calls": [
{
"retrieved_at": "2026-10-25T12:00:00.000Z"
},
{
"retrieved_at": "2026-10-25T12:00:00.000Z"
}
],
"as_of": "2025-11-18"
}
}
}
```
> [!NOTE]
>
> See [Pricing](https://docs.oneshotagent.com/pricing.md) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.
## Notes
* `total` is how many papers matched in all, including any beyond `limit`, and is 0 when none did. `query_translation` shows how the source expanded the search (MeSH terms, plurals, the year range).
* Field tags such as `[Title]` or `[MeSH Terms]` and `AND`, `OR` and `NOT` are passed to the source as written.
* Give `from_year`, `to_year` or both to keep papers published in those years; one alone is open on the other side.
* `sort` is `newest` (by publication date, the default) or `relevance`. Each paper also gives its author count.
* Registered studies are in `record_clinical_trials_find`; the papers NCBI links to one gene are in `gene_publications`.
* Results return inline. The finished job stays available at `/v1/requests/{request_id}`
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.