Getting started
Overview
1stAuthor gives agents primary sources to reason over: full-text papers, statutes and judgments, researcher profiles, and the open web. Every domain exposes the same three verbs:
- Retrieve — hybrid search that filters like a database, returning briefs.
- Read — one document in layers:
brief → head → section → raw. - Ask — an agentic loop that retrieves, reads what it needs, and streams a cited answer.
Base URL https://data.rag.ac.cn. The API is plain HTTPS + JSON; agentic endpoints also speak NDJSON. CORS is open, so the playground on the right calls the API straight from your browser.
Free samples, no token: papers 2409.05591, 2504.21776; retrieve queries transformer, attention mechanism, large language model; PMC PMC544940, PMC514704.
Authentication
Send the token as a header or a query parameter:
Authorization: Bearer YOUR_TOKEN ?token=YOUR_TOKEN
Get a key at /signup — Google, email or a +86 phone number. The SDK also auto-registers a token on first use; that token cannot call agentic endpoints (403). Claim it from your dashboard to lift it to your account’s limits.
Quotas & rate limits
Two independent pools. Agentic calls do not consume general requests, and vice versa. Exceeding either returns 429.
| Key | General / day | Agentic / day | How |
|---|---|---|---|
| Auto-registered (SDK) | 1,000 | not eligible (403) | Automatic on first SDK/CLI use |
| Registered | 10,000 | 30, free | /signup |
| Lite / Premium | Custom | 500 / 10,000 | Email tommy@chien.io with your use case |
Costs: reading and retrieve endpoints cost 1 general request; /websearch costs 50; every agentic call (arXiv, web, talent, law) costs 1 from the agentic pool. Check usage with GET /stats/usage?days=7.
Errors
| Code | Meaning |
|---|---|
| 400 | Invalid parameters |
| 401 | Invalid or missing token |
| 403 | Valid SDK token, but this endpoint needs a registered key |
| 404 | Document not found (or, on trending, no engagement yet) |
| 422 | Request body failed validation (agentic endpoints) |
| 429 | Daily limit exceeded — detail carries your tier and calls used |
| 503 | Retrieval backend unavailable |
Errors are JSON: {"detail": "…"}.
Streaming (NDJSON)
Every agentic endpoint has a /stream variant returning application/x-ndjson: one JSON event per line, same request body. The protocol is identical across domains.
| 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 is cited) |
| done | Last line | Stats, including answer_truncated |
| error | On failure | Message |
Only with 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 |
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 inference", "verbose": true}'
The playground’s event viewer renders exactly this protocol: pick any Ask endpoint and toggle Stream.
MCP
One MCP server exposes every domain as tools: papers_search, papers_read, law_search, law_read, case_search, case_read, ask. Configuration snippets for Claude Code, Cursor and the Python SDK are on the MCP page.
SDK / CLI
pip install deepxiv-sdk deepxiv config --token YOUR_KEY deepxiv ask "what speedup does DEER report on HumanEval" --verbose deepxiv search "agentic memory" --venue NeurIPS --venue-year 2025 --min-citations 50 deepxiv paper 2409.05591 --brief deepxiv paper 2409.05591 --section "2. Method"
The package keeps its DeepXiv name for now (deepxiv-sdk on PyPI, source on GitHub). ask streams: answer to stdout, sources and progress to stderr — pipe-friendly.