📚 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

🤖 Agentic search with citations

🎯 Progressive reading (brief → section → raw)

🔍 Hybrid retrieval, 3.1M full-text papers

🚀 Redis cached, T+0 daily sync

🌐 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 (1stAuthor ask uses 1stAuthor's own daily ask allowance instead).

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 effort only adds reading rounds; it can't redirect first-round recall.

🔬 Ask arXiv

POST /arxiv/agent/search

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

curl -X POST "https://data.rag.ac.cn/arxiv/agent/search" \

  -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

POST /web/agent/search

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)

POST /arxiv/agent/search/stream

POST /web/agent/search/stream

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

curl -sN -X POST "https://data.rag.ac.cn/arxiv/agent/search/stream" \

  -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.

🧭 1stAuthor Domains NEW

Your DeepXiv key also reaches the 1stAuthor vertical corpora: researcher profiles (talent), statutes (law), court judgments (cases), clinical trials, drugs, grants, SEC filings, standards, CVEs, the Federal Register and more. Every domain has the same three verbs — search · read · ask — and describes itself: GET /fa/v1/{domain} lists its filters, views and prices.

Paths and bodies are identical to the 1stAuthor API, so the firstauthor Python SDK works unchanged with base_url="https://data.rag.ac.cn/fa" and your DeepXiv key.

Endpoint	What it does	Cost (SDK tokens)
`GET /fa/v1/domains`	Available domains	free
`GET /fa/v1/{domain}`	Self-description: filters, views + prices, quickstart	free
`POST /fa/v1/{domain}/search`	`{query, top_k, filters?, fields?, sort?}`	2 (`fields:"head"`: 3)
`GET /fa/v1/{domain}/read/{id}`	`?level=brief\|detail\|full`, or one `extra=…`, or `format=html`	price of that level / extra / format
`GET /fa/v1/{domain}/doc/{id}`	`?view=…` (used by the SDK)	price of that view
`POST /fa/v1/{domain}/read`	Batch read `{ids, level?}`	per id
`GET /fa/v1/{domain}/facets?field=`	Real value counts for a field	1
`POST /fa/v1/talent/resolve`	`{names: [...]}` → person ids	2
`POST /fa/v1/{domain}/ask[/stream]`	`{query, effort?}` — cited answer from that domain	daily ask allowance
`POST /fa/v1/ask[/stream]`	Same, 1stAuthor picks the domain (a `route` event says which)	daily ask allowance
`GET /fa/v1/whoami`	How your key is limited (SDK tokens: remaining quota and trials)	free

Billing

Registered keys get the same limits as 1stAuthor's own users and nothing is taken from your DeepXiv quota: during the beta, search / read are rate limited by 1stAuthor and ask uses 1stAuthor's daily ask allowance (resets 00:00 UTC). When a limit is reached you get 1stAuthor's 429 unchanged, with its message and Retry-After (meta.quota.billed_by: "1stauthor", X-DeepXiv-Agent-Tier: 1stauthor).

SDK tokens: search / read / facets / resolve take the listed number of requests from the token's daily_limit, and ask comes with 3 free trials in total (not reset daily, X-DeepXiv-Agent-Tier: trial); after that ask returns 403 with a link to register for a daily ask allowance. Upstream failures, timeouts and upstream rate limits are refunded automatically. Each response carries meta.quota and X-DeepXiv-Quota-* (ask: X-DeepXiv-Agent-*) headers.

talent profile limits. Reads at detail level or above are capped by the number of distinct people per day (search hits and brief cards are not counted; re-reading the same person is free of the cap): registered keys 300/day (100 at full), SDK tokens 30/day (10 at full), and 500/day per network across all keys. contact=1 needs a registered key (20/day). Over the limit you get 429; for higher volume, contact tommy@chien.io.

Example

curl -X POST "https://data.rag.ac.cn/fa/v1/talent/search" \

  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \

  -d '{"query": "embodied AI", "filters": {"org": "清华大学", "min_h_index": 30}}'

curl "https://data.rag.ac.cn/fa/v1/talent/read/12?level=detail" -H "Authorization: Bearer YOUR_TOKEN"

curl -sN -X POST "https://data.rag.ac.cn/fa/v1/law/ask/stream" \

  -H "Authorization: Bearer YOUR_REGISTERED_KEY" -H "Content-Type: application/json" \

  -d '{"query": "What are the consent requirements for processing personal data in China?", "effort": "low"}'

Moved: /talent/search and /talent/survey/{id} now return 410. Use POST /fa/v1/talent/search and GET /fa/v1/talent/read/{id}; person ids differ from the old endpoints, so look people up again.

📋 Get Paper Metadata

GET /arxiv/?type=head&arxiv_id={PAPER_ID}

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

GET /arxiv/?type=brief&arxiv_id={PAPER_ID}

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

GET /arxiv/?type=preview&arxiv_id={PAPER_ID}

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

GET /arxiv/?type=raw&arxiv_id={PAPER_ID}

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

GET /arxiv/?type=section&arxiv_id={PAPER_ID}§ion={SECTION_NAME}

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

GET /arxiv/?type=json&arxiv_id={PAPER_ID}

Returns the complete structured JSON file with all sections and metadata.

🌐 Get HTML View

GET /arxiv/?type=markdown&arxiv_id={PAPER_ID}

Returns a beautifully rendered HTML page for viewing in a browser.

Quick Access

🌐 HTML View (2409.05591) 👀 Preview Content 📋 Formatted Metadata (2504.21776)

🔍 Search & Retrieve

GET /arxiv/?type=retrieve&query={QUERY}

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

📚 arxiv (default)

🧬 biorxiv

🏥 medrxiv

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 /arxiv/trending_signal?arxiv_id={PAPER_ID}

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

GET /pmc/?type=head&pmc_id={PMC_ID}

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

GET /pmc/?type=json&pmc_id={PMC_ID}

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

📋 PMC Metadata (PMC544940) 📊 Full JSON (PMC514704)

⚠️ 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

GET /stats/usage?days=7

View your usage statistics for the past N days (1-30).