Legacy API

Legacy API (DeepXiv paths)

The original DeepXiv paths are served by this gateway unchanged — same parameters, same responses — authenticated with an fa_live_ key and billed in credits like their /v1 equivalents (op=legacy in usage). The deepxiv CLI and deepxiv-sdk package use them. Existing DeepXiv tokens keep working at https://data.rag.ac.cn under the old quotas; they are not accepted here.

Ask arXivregistered key+ /stream

POST/arxiv/agent/search

A question goes in; the service runs hybrid retrieval over the full-text corpus, reads the sections it needs, and returns an answer with real IDs — [arXiv:2512.15176]. Append /stream for NDJSON events.

CLIdeepxiv ask "…"

Parameters

Parameter	Type		Description
query	string	REQUIRED	1–2000 characters. Be specific; ask for numbers if you want numbers.
effort	default \| high \| xhigh	= default	Gather rounds ceiling: 1–2 / 3 / 4–5.
verbose	bool	= false	Include the tool-call trace (and `tool_call` / `tool_result` / `thinking` events when streaming).
top_k	integer	= 10	Speculative prefetch size, 1–30.
stream_answer	bool	= true	Streaming endpoint only. `false` emits one `answer` event instead of deltas.
max_rounds	integer	OPTIONAL	0–8. Overrides the effort preset. `0` answers straight off the prefetch — first token ≈1.3s.
force_answer_after	number	OPTIONAL	0.5–30s. Hard cutover into the answer phase.
max_answer_tokens	integer	= 4096	256–16384. Hitting it sets `answer_truncated`.
language	string	OPTIONAL	Answer language. Defaults to the query’s language.

Example

{
  "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 }
}

Registered keys only. The token the SDK auto-registers returns 403. Every registered account gets 30 agentic calls a day, free, shared across arXiv, web and talent.

Citations are real. It never invents an ID and says “no relevant papers” rather than fabricate. sources is the retrieval set, not the citation list — filter to IDs that appear in answer. answer_truncated means incomplete — say so downstream.

brief

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

Title, TLDR, keywords, publication date, citation count, GitHub URL. ~300 tokens — enough to judge whether the paper is worth reading.

CLIdeepxiv paper 2409.05591 --brief

Parameters

Parameter	Type		Description
arxiv_id	string	REQUIRED	arXiv paper ID. `2409.05591` and `2504.21776` are free.
token	string	OPTIONAL	API token, or send `Authorization: Bearer`. Not required for free papers.

Response

arxiv_idarXiv ID
titlePaper title
tldrGenerated one-paragraph summary
keywordsKeyword list
publish_atPublication date
citationsCitation count
github_urlCode repository, when found
src_urlPDF link

head

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

Structured metadata plus the section map: every section name with its own TLDR and token count, so an agent knows where the answer lives before paying for it. Total token_count included.

CLIdeepxiv paper 2409.05591 --head

Parameters

Parameter	Type		Description
arxiv_id	string	REQUIRED	arXiv paper ID. `2409.05591` and `2504.21776` are free.
token	string	OPTIONAL	API token, or send `Authorization: Bearer`. Not required for free papers.

Response

title / abstract / authorsAuthors carry name, orgs and optional misc (email, orcid)
sections[{ name, idx, tldr, token_count }]
token_countTokens in the full paper
venue / journal_name / citations / categories / publish_at / keywords / github_urlAs available

section

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

One section, in full, as clean markdown. Use the names from head.

CLIdeepxiv paper 2409.05591 --section "2. Method"

Parameters

Parameter	Type		Description
arxiv_id	string	REQUIRED	arXiv paper ID. `2409.05591` and `2504.21776` are free.
section	string	REQUIRED	Section name exactly as listed by `head`, e.g. `1. Introduction`.
token	string	OPTIONAL	API token, or send `Authorization: Bearer`. Not required for free papers.

preview

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

The first N characters of the paper. Returns is_truncated and total_characters.

Parameters

Parameter	Type		Description
arxiv_id	string	REQUIRED	arXiv paper ID. `2409.05591` and `2504.21776` are free.
characters	integer	= 10000	100–100000.
token	string	OPTIONAL	API token, or send `Authorization: Bearer`. Not required for free papers.

raw

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

The entire paper as markdown. Reach for it last.

CLIdeepxiv paper 2409.05591 --raw

Parameters

Parameter	Type		Description
arxiv_id	string	REQUIRED	arXiv paper ID. `2409.05591` and `2504.21776` are free.
token	string	OPTIONAL	API token, or send `Authorization: Bearer`. Not required for free papers.

json

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

The complete structured document: metadata and every section as JSON.

Parameters

Parameter	Type		Description
arxiv_id	string	REQUIRED	arXiv paper ID. `2409.05591` and `2504.21776` are free.
token	string	OPTIONAL	API token, or send `Authorization: Bearer`. Not required for free papers.

markdown (HTML view)

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

A rendered HTML page for reading in a browser. Open 2409.05591.

Parameters

Parameter	Type		Description
arxiv_id	string	REQUIRED	arXiv paper ID. `2409.05591` and `2504.21776` are free.
token	string	OPTIONAL	API token, or send `Authorization: Bearer`. Not required for free papers.

Search & retrieve

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

Hybrid retrieval (dense + sparse over metadata, section and RoC indexes, optional fine rerank) over arXiv, bioRxiv and medRxiv. Returns a ranked list, not an answer — for a cited answer use Ask arXiv. Queries transformer, attention mechanism, large language model are free.

CLIdeepxiv search "agentic memory" --venue NeurIPS --venue-year 2025

Parameters

Parameter	Type		Description
query	string	REQUIRED	Up to 500 characters.
source	arxiv \| biorxiv \| medrxiv	= arxiv	ID field in results follows the source: `arxiv_id` / `biorxiv_id` / `medrxiv_id`.
top_k	integer	= 10	1–100.
offset	integer	= 0	Pagination, 0–10000.
authors	string[]	OPTIONAL	Filter and ranking signal. Repeat the param per value.
orgs	string[]	OPTIONAL	Organisation filter and ranking signal.
categories	string[]	OPTIONAL	e.g. `cs.AI`, `cs.CL`. Pure filter.
venue	string[]	OPTIONAL	NeurIPS, ICLR, CVPR… aliases resolve (NeurIPS ↔ NIPS). `venues` is an alias.
venue_year	integer	OPTIONAL	1900–2100, parsed from the venue string.
min_citation	integer	OPTIONAL	Citation floor. Pure filter.
date_search_type	exact \| after \| before \| between	OPTIONAL	Pair with `date_str`.
date_str	string[]	OPTIONAL	`YYYY` / `YYYY-MM` / `YYYY-MM-DD`; for `between` pass start and end.
search_funcs	string[]	OPTIONAL	Index types, default `metadata, section, roc`.
use_fine_rerank	bool	= true	Fine rerank after recall.
return_contents	bool	= false	Include matched section contents.
return_roc	bool	= false	Include the RoC list.
token	string	OPTIONAL	API token, or send `Authorization: Bearer`. Not required for free papers.

Example

{
  "status": "success", "total_count": 3,
  "result": [ { "arxiv_id": "2506.18871", "score": 0.9475, "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"] } ]
}

Filters combine with AND. A narrow date window on a high citation floor can legitimately return 0 — loosen one. Legacy size, search_mode, bm25_weight, vector_weight, date_from, date_to are gone.

Trending signal

GET/arxiv/trending_signal?arxiv_id={arxiv_id}&token={token}

Social engagement for one paper: tweets, likes, views, replies, first and last seen. 404 means no engagement yet — normal.

CLIdeepxiv trending · deepxiv paper 2409.05591 --popularity

Parameters

Parameter	Type		Description
arxiv_id	string	REQUIRED	arXiv paper ID. `2409.05591` and `2504.21776` are free.
token	string	REQUIRED	Required for this endpoint.

Example

{ "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" }

PMC · head

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

PubMed Central metadata: title, DOI, abstract, authors, categories, date. PMC544940 and PMC514704 are free.

Parameters

Parameter	Type		Description
pmc_id	string	REQUIRED	PMC ID.
token	string	OPTIONAL	API token, or send `Authorization: Bearer`. Not required for free papers.

PMC · json

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

The complete structured article.

Parameters

Parameter	Type		Description
pmc_id	string	REQUIRED	PMC ID.
token	string	OPTIONAL	API token, or send `Authorization: Bearer`. Not required for free papers.

Ask the webregistered key+ /stream

POST/web/agent/search

Same request shape as Ask arXiv, answered from Google results plus cached page bodies. Answers with markdown links to real URLs; each source carries read: true|false. Shares the agentic quota.

CLIdeepxiv ask --web "…"

Parameters

Parameter	Type		Description
query	string	REQUIRED	1–2000 characters. Be specific; ask for numbers if you want numbers.
effort	default \| high \| xhigh	= default	Gather rounds ceiling: 1–2 / 3 / 4–5.
verbose	bool	= false	Include the tool-call trace (and `tool_call` / `tool_result` / `thinking` events when streaming).
search_type	search \| scholar \| news \| images	= search	Google vertical.
gl	string	= us	Google country code. Chinese queries auto-switch to `cn`.
hl	string	= en	Search language. Chinese queries auto-switch to `zh-cn`.
stream_answer	bool	= true	Streaming endpoint only. `false` emits one `answer` event instead of deltas.
max_rounds	integer	OPTIONAL	0–8. Overrides the effort preset. `0` answers straight off the prefetch — first token ≈1.3s.
force_answer_after	number	OPTIONAL	0.5–30s. Hard cutover into the answer phase.
max_answer_tokens	integer	= 4096	256–16384. Hitting it sets `answer_truncated`.
language	string	OPTIONAL	Answer language. Defaults to the query’s language.

Web evidence has two strengths. Only cached page bodies are read — never a live fetch — so an uncached page contributes just its snippet. Surface read so your agent can qualify weaker claims. Chinese sites and news pages are cached less often.

Web is slower than arXiv: cache misses cost 1.7–4.3s upstream. First-token target is 10s, not 5s.

Raw web search

POST/websearch

Organic results from the upstream search API, no reading, no answer. Costs 50 general requests per call. Prefer Ask the web unless you want the result list itself.

Parameters

Parameter	Type		Description
query	string	REQUIRED	Search query.
search_type	scholar \| web	= scholar	`scholar` or `web`.
page	integer	= 1	Result page.
use_cache	bool	= true	Serve from cache when available.

50 general requests per call