📚 API Documentation
The DeepXiv API gives agents a substrate to reason over: a full-text arXiv corpus, progressive paper access, and an agentic search loop that returns cited answers instead of ten blue links.
🤖 New in 1.0 — Agentic Search.
POST /arxiv/agent/search and POST /web/agent/search take a
question, pick their own tools, read sources as needed, and stream back an answer with
real citations. See Agentic Search below. Requires a
registered key.
🎁 Free Testing
Papers 2409.05591 and 2504.21776 are available without authentication for testing purposes.
⚡ Key Features
🌐 Base URL
https://data.rag.ac.cn
Paper access and retrieval live under /arxiv/ and /pmc/;
agentic search under /arxiv/agent/ and /web/agent/.
🔑 Authentication
Most endpoints require a valid API token. You can provide the token in two ways:
Method 1: Authorization Header
Authorization: Bearer YOUR_TOKEN_HERE
Method 2: Query Parameter
?token=YOUR_TOKEN_HERE
🎁 Free Papers (No Token Required)
Papers 2409.05591 and 2504.21776 can be accessed without a token.
📝 Getting a Token
Visit /signup to create an account and get your API token. Each token includes 10,000 free daily requests. Need more? Contact us with your use case.
🔌 API Endpoints
All endpoints use the same base URL with different type parameters to specify the data format.
🤖 Agentic Search NEW IN 1.0
A question goes in; the service picks its own tools, reads sources when it needs to, and returns an answer with citations. Two backends share one request shape and one quota.
| Backend | Endpoint | Answers with | Best for |
|---|---|---|---|
| arXiv | /arxiv/agent/search |
Real IDs — [arXiv:2512.15176] |
Methods, reported numbers, experimental results |
| Web | /web/agent/search |
Markdown links to real URLs | Current events, products, pricing, anything non-academic |
Neither is a wrapper around a search box. The arXiv side runs Qdrant hybrid retrieval and reads actual paper sections; the web side reads cached page bodies and never fetches live.
⚠️ Registered keys only. Agentic search rejects the token the SDK
auto-registers on first use with 403. Get a registered key at
/signup — every account
currently gets 30 agentic calls per day, free.
Quota
Agentic quota is completely independent of your general
daily_limit: agentic calls don't consume general requests, and vice versa.
Each call costs 1, and arXiv and web share the same pool.
| Tier | Agentic calls / day | How to get it |
|---|---|---|
free | 300 | Any registered account |
premium | 10,000 | Email tommy[at]chien.io with your use case |
Effort levels
Rounds are a ceiling, not a floor — the service converges early once it has enough evidence.
| effort | Gather rounds | First token (arXiv) | First token (web) | Reach for it when |
|---|---|---|---|---|
default | 1–2 | 3–4s | 5–9s | You want an answer now |
high | 3 | 7–8s | ≈13s | Comparing across papers |
xhigh | 4–5 | 9–13s | longer | Survey-shaped questions |
Writing queries that work
This is worth more than any parameter.
- Be specific. The service assumes your query is already refined. "what compression ratio does KV cache eviction report on LongBench" beats "kv cache" by a wide margin.
- Ask for numbers if you want numbers. "What speedup" or "which benchmark" pushes it to read source text instead of skimming abstracts.
- Chinese works directly. arXiv queries are rewritten to English technical terms for retrieval; web switches to a Chinese locale. The answer comes back in the query's language.
- Put arXiv scope limits in the query text — year, venue, category, author, institution, minimum citations. They become retrieval filters.
- If results miss, rephrase. Raising
effortonly adds reading rounds; it can't redirect first-round recall.
🔬 Ask arXiv
Answers from a local full-text arXiv corpus. JSON request body, JSON response. For the streaming variant see Streaming (NDJSON) below.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Required | 1–2000 characters |
| effort | string | Optional | default / high / xhigh (default: default) |
| verbose | bool | Optional | Include the tool-call trace (default: false) |
| top_k | integer | Optional | Speculative prefetch size, 1–30 (default: 10) |
| stream_answer | bool | Optional | Streaming endpoint only. false emits one answer event instead of token deltas (default: true) |
| max_rounds | integer | Optional | 0–8. Overrides the effort preset. 0 answers straight off the prefetch — first token ≈1.3s |
| force_answer_after | float | Optional | 0.5–30s. Hard cutover into the answer phase. Overrides the effort preset |
| max_answer_tokens | integer | Optional | 256–16384 (default: 4096). Doesn't affect first-token latency. Hitting it sets answer_truncated |
| language | string | Optional | Answer language. Defaults to the query's language |
Example Request
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"query": "what speedup does DEER report on HumanEval"}'
Response
"answer": "DEER reports a 5.54× speedup on HumanEval ... [arXiv:2512.15176]",
"sources": [
{ "arxiv_id": "2512.15176", "title": "...", "url": "https://arxiv.org/abs/2512.15176" }
],
"stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false },
"trace": [ ... ], // only when verbose=true
"quota": { "tier": "free", "used": 3, "limit": 30 }
}
⚠️ Three things to know about the results
Citations are real. The service never invents an arXiv ID or URL, and says
"no relevant papers" rather than fabricating one. [arXiv:2512.15176] maps
directly to https://arxiv.org/abs/2512.15176.
sources is the retrieval set, not the citation list. A
10-paper retrieval often supports a single citation. Filter to IDs that actually appear
in answer, or your agent will present unrelated papers as evidence.
answer_truncated means incomplete. Say so explicitly downstream,
otherwise an agent will summarise a cut-off answer as if it were whole.
🌐 Ask Web
Same request shape as /arxiv/agent/search, answered from Google results plus
cached page bodies. Shares the same agentic quota.
Additional Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| search_type | string | Optional | search (default) / scholar / news / images |
| gl | string | Optional | Google country code (default: us). Chinese queries auto-switch to cn |
| hl | string | Optional | Search language (default: en). Chinese queries auto-switch to zh-cn |
top_k is arXiv-only. query, effort, verbose,
stream_answer, max_rounds, force_answer_after,
max_answer_tokens and language behave as above.
Web evidence has two strengths. The service reads only cached page
bodies and never fetches live, so an uncached page contributes just its search snippet.
Each source carries read: true|false — surface that distinction so your agent
can qualify weaker claims. Chinese sites and news pages are cached less often.
Web is slower than arXiv because Google cache misses cost 1.7–4.3s and aren't under our control. First-token target is 10s, not 5s.
📡 Streaming (NDJSON)
Returns application/x-ndjson — one JSON event per line. Same request body as the
blocking endpoints. Both stream endpoints use an identical event protocol.
Events
| Event | When | Payload |
|---|---|---|
billing | First line | Tier, calls used, daily limit |
start | Run begins | Resolved effort, rounds, budget |
answer_start | Answer phase opens | — |
answer_delta | Repeatedly | Answer text chunk |
sources | After the answer | Retrieval set (superset of what's cited) |
done | Last line | Stats, including answer_truncated |
error | On failure | Message |
Only when verbose: true | ||
tool_call | Agent invokes a tool | Tool name + arguments |
tool_result | Tool returns | Result summary |
thinking | Reasoning emitted | Text |
warning | Degraded path taken | Message |
Example
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"query": "what methods reduce KV cache memory for long-context LLM inference", "verbose": true}'
Answer text starts within ~5s on arXiv: a speculative prefetch removes the first evidence
round, and the run is forced into the answer phase at force_answer_after.
📋 Get Paper Metadata
Returns structured metadata including title, abstract, authors, sections, and statistics.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| arxiv_id | string | Required | arXiv paper ID (e.g., 2409.05591, 2504.21776) |
| type | string | Required | Must be "head" |
| token | string | Optional | API token (not required for free papers) |
Response Fields
- title: Paper title
- abstract: Paper abstract
- authors: List of authors
- sections: Section names and metadata
- token_count: Total tokens in the paper
- categories: arXiv categories
- publish_at: Publication date
📌 Get Brief Information
Returns concise paper information including title, TLDR, keywords, publication date, and citation count. Perfect for quick summaries and list views.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| arxiv_id | string | Required | arXiv paper ID (e.g., 2409.05591, 2504.21776) |
| type | string | Required | Must be "brief" |
| token | string | Optional | API token (not required for free papers) |
Response Fields
- arxiv_id: arXiv paper ID
- src_url: Direct link to PDF
- title: Paper title
- tldr: AI-generated summary (if available)
- keywords: List of keywords (if available)
- publish_at: Publication date
- citations: Citation count
Example Response
"arxiv_id": "2409.05591",
"src_url": "https://arxiv.org/pdf/2409.05591",
"title": "Paper Title",
"tldr": "Brief summary...",
"keywords": ["AI", "Machine Learning"],
"publish_at": "2024-09-05",
"citations": 42
}
👀 Preview Paper Content
Returns a configurable number of characters from the paper for quick preview. Default is 10,000 characters, but you can adjust it from 100 to 100,000. Useful for mobile devices or when you want to quickly scan the introduction.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| arxiv_id | string | Required | arXiv paper ID |
| type | string | Required | Must be "preview" |
| characters | integer | Optional | Number of characters to return (default: 10000, range: 100-100000) |
Response Fields
- preview: First N characters (configurable)
- is_truncated: Whether content was truncated
- total_characters: Total characters in full document
- preview_characters: Actual characters in preview
📄 Get Full Content
Returns the complete paper content in Markdown format.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| arxiv_id | string | Required | arXiv paper ID |
| type | string | Required | Must be "raw" |
📑 Get Specific Section
Returns content from a specific section of the paper (e.g., "Introduction", "Conclusion").
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| arxiv_id | string | Required | arXiv paper ID |
| type | string | Required | Must be "section" |
| section | string | Required | Section name (e.g., "Introduction", "Methods") |
📊 Get Complete JSON
Returns the complete structured JSON file with all sections and metadata.
🌐 Get HTML View
Returns a beautifully rendered HTML page for viewing in a browser.
Quick Access
🔍 Search & Retrieve
Unified semantic retrieval over arXiv, bioRxiv and medRxiv. Backed by Qdrant hybrid retrieval (dense + sparse over metadata, section and RoC indexes, with optional fine reranking), plus token authentication, daily quota and Redis caching. For a cited answer rather than a result list, use Agentic Search.
Sources
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | string | Required | Must be retrieve |
| query | string | Required | Search query (max 500 chars) |
| source | string | Optional | arxiv (default) / biorxiv / medrxiv |
| top_k | integer | Optional | Number of results, 1–100 (default: 10) |
| offset | integer | Optional | Pagination offset, 0–10000 (default: 0) |
| authors | array[string] | Optional | Author list (filters & affects ranking). Repeat the param for each value. |
| orgs | array[string] | Optional | Organization list (filters & affects ranking). Repeat the param for each value. |
| date_search_type | string | Optional | between / exact / after / before. Must be paired with date_str. |
| date_str | string | array[string] | Optional | Format YYYY / YYYY-MM / YYYY-MM-DD. For between, repeat the param twice (start, end). |
| min_citation | integer | Optional | Minimum citation count (filter, no rerank impact) |
| categories | array[string] | Optional | Category filter, e.g. cs.AI, cs.CL (no rerank impact) |
| venue / venues | array[string] | Optional | Venue / conference / journal filter, e.g. NeurIPS, ICLR, CVPR. Aliases resolve automatically (NeurIPS ↔ NIPS). venue is an alias of venues; repeat the param for each value. |
| venue_year | integer | Optional | Venue year parsed from the venue string, 1900–2100, e.g. 2025 |
| search_funcs | array[string] | Optional | Index types to use. Default ["metadata","section","roc"] |
| use_fine_rerank | bool | Optional | Apply fine reranking after recall (default: true) |
| return_contents | bool | Optional | Return retrieved section contents (default: false) |
| return_roc | bool | Optional | Return retrieved RoC list (default: false) |
Response Format
The ID field name follows the requested source:
arxiv_id / biorxiv_id / medrxiv_id.
"status": "success",
"total_count": 3,
"result": [
{
"arxiv_id": "2506.18871",
"score": 0.9475,
"title": "Paper Title",
"tldr": "...",
"abstract": "...",
"authors": [{ "name": "...", "orgs": ["..."] }],
"url": "https://arxiv.org/abs/2506.18871",
"date": "2025-06-23T17:38:54Z",
"citation_count": 217,
"categories": ["cs.CV"],
"contents": [{ "section_name": "...", "section_contents": ["..."] }], // when return_contents=true
"roc": ["..."] // when return_roc=true
}
]
}
🎁 Free Queries
These queries don't require a token (case-insensitive, exact match):
- transformer
- attention mechanism
- large language model
Filters combine with AND. Stacking a narrow date window on a high
citation floor can legitimately return 0 results — loosen one.
authors and orgs are filters and ranking signals;
categories, venue and min_citation are pure filters.
⚠️ Migration note: Legacy parameters
size, search_mode, bm25_weight, vector_weight,
date_from, date_to are no longer supported. Use
top_k, date_search_type, date_str instead.
📈 Get Trending Signal
Get social media engagement metrics for a paper, including tweets, likes, views, and replies. Track how papers are trending in the research community.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| arxiv_id | string | Required | arXiv paper ID (e.g., 2409.05591) |
| token | string | Required | API token (required for all requests) |
Response Fields
- arxiv_id: arXiv paper ID
- total_tweets: Total number of tweets mentioning the paper
- total_likes: Total likes across all tweets
- total_views: Total views across all tweets
- total_replies: Total replies to tweets about the paper
- first_seen_date: When the paper was first mentioned
- last_seen_date: Most recent mention
Example Response
"arxiv_id": "2409.05591",
"total_tweets": 150,
"total_likes": 3200,
"total_views": 25000,
"total_replies": 45,
"first_seen_date": "2024-09-05T10:30:00",
"last_seen_date": "2024-09-10T14:20:00"
}
Use Cases
- 📊 Track paper virality and impact
- 🔥 Identify trending papers in your field
- 📅 Monitor engagement timeline
- 🎯 Discover influential research
💡 Note: If a paper has no social media engagement, you'll receive a 404 error. This is normal for papers that haven't been discussed on Twitter yet.
🏥 PMC Endpoints
Access PubMed Central (PMC) research articles. PMC is a free full-text archive of biomedical and life sciences journal literature.
🎁 Free Testing
Papers PMC544940 and PMC514704 are available without authentication for testing purposes.
🌐 Base URL
https://data.rag.ac.cn/pmc/
📋 Get PMC Paper Metadata
Returns structured metadata including title, DOI, abstract, authors, categories, and publication date.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| pmc_id | string | Required | PMC paper ID (e.g., PMC544940, PMC514704) |
| type | string | Optional | Must be "head" (default) |
| token | string | Optional | API token (not required for free papers) |
Response Fields
- pmc_id: PMC paper ID
- title: Paper title
- doi: Digital Object Identifier
- abstract: Paper abstract
- authors: List of authors
- categories: Medical subject categories
- publish_at: Publication date
📊 Get PMC Complete JSON
Returns the complete structured JSON file with full paper content and metadata.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| pmc_id | string | Required | PMC paper ID (e.g., PMC544940, PMC514704) |
| type | string | Required | Must be "json" |
| token | string | Optional | API token (not required for free papers) |
Quick Access
⚠️ Error Handling
HTTP Status Codes
| Code | Meaning | Description |
|---|---|---|
| 200 | Success | Request successful |
| 400 | Bad Request | Invalid parameters |
| 401 | Unauthorized | Invalid or missing token |
| 403 | Forbidden | Valid SDK token, but agentic search requires a registered key |
| 404 | Not Found | Paper not found |
| 422 | Unprocessable Entity | Request body failed validation (agentic endpoints) |
| 429 | Too Many Requests | Daily limit exceeded. On agentic endpoints the detail carries your tier and calls used |
| 503 | Service Unavailable | Retrieval service error |
📊 Rate Limits
There are two independent pools. Agentic calls do not consume general
requests, and general requests do not consume agentic calls. Exceeding either returns
429 Too Many Requests.
| Key | General requests / day | Agentic calls / day | How to get it |
|---|---|---|---|
| Auto-registered (SDK) | 1,000 | — not eligible (403) |
Automatic on first SDK/CLI use |
| Registered | 10,000 | 30, free | /signup — Google or phone |
| Lite / Premium | Custom | 500 / 10,000 | Email tommy[at]chien.io with your use case |
Lost your key? Recover it at sign in.
Checking Usage
View your usage statistics for the past N days (1-30).