Getting started
Overview
1stAuthor gives agents primary sources to reason over — papers, statutes, judgments, researcher profiles, the open web — behind one URL scheme:
POST /v1/{domain}/search cards to choose from
GET /v1/{domain}/read/{id}?level=brief|detail|full read as deep as you need (detail by default)
POST /v1/{domain}/ask[/stream] a question in, a cited answer out
Three verbs, the same everywhere. read also takes extra=… for another side of the same document and format=json|md|html. Each domain page opens with its common calls; rarer fields are folded away, not removed.
Base URL https://api.1stauthor.com — or https://api.rag.ac.cn from mainland China, see Base URL. Domains today: papers (live), law (live), cases (live), us_law (live), uk_eu_law (live), trials (live), drugs (live), grants (live), filings (live), stocks (live), standards (live), talent (live), appraise (live), web (live), cve (live), osv (live), fr (live). GET /v1/domains lists them; GET /v1/{domain} returns each one's self-description — filters, levels, prices, free samples — which is also what this page is generated from (snapshot 2026-10-22).
Every success response carries meta: request_id, credits.charged, credits.balance, latency_ms, cached. The playground on the right calls the API from your browser; free samples need no key.
From a terminal or from Python the client is deepxiv — pip install deepxiv-sdk, then deepxiv fa. 1stAuthor is in beta, and while it is, the SDK ships with DeepXiv, who we work closely with: SDK / CLI below.
Base URL
| Base URL | For | Served from |
|---|---|---|
| https://api.1stauthor.com | everywhere else | Tokyo |
| https://api.rag.ac.cn | mainland China | Shanghai |
Users in mainland China: use https://api.rag.ac.cn as the base URL — faster and steadier from there. It is the same gateway behind a second door, so paths, keys, credits, billing and rate limits are identical; only the host changes. Signing in, the console and billing stay on 1stauthor.com.
curl -X POST https://api.rag.ac.cn/v1/papers/search \
-H "Authorization: Bearer $FA_API_KEY" -H "Content-Type: application/json" \
-d '{"query": "agentic memory", "top_k": 5}'
The playground on every docs page has a Base URL switch; the code it writes follows it.
Capacity & rate limits
The service currently runs on a single small machine: about 50 search requests/s and ~20 concurrent ask sessions in total — across all users, not per key. Please keep concurrency modest and back off on 429 using Retry-After. Contact tommy@chien.io for bulk access or higher limits.
Searching and reading cost no credits during the beta — facets, read, resolve, search and the rest — within fair use, paced by these limits per user:
| Plan | per minute | at once | per day |
|---|---|---|---|
| Free · Pay as you go | 60 | 5 | 5,000 |
| Starter | 120 | 10 | 10,000 |
| Pro | 300 | 10 | 25,000 |
| Team | 600 | 10 | 50,000 |
Ask draws on a daily ask allowance, one per user, reset at 00:00 UTC. Within it ask costs no credits, and every plan — Free included — may use effort=high. Once it is used up, paid plans carry on in credits (low / medium / high = 50 / 100 / 200); Free returns 429 quota_exceeded until the reset. There is also a site-wide daily total, which can run out early at busy times.
Every 429 carries Retry-After in seconds: 60 for the per-minute limit, 1 for too many requests at once, and the time until 00:00 UTC for the daily limit and the daily ask allowance. Wait that long, then retry once; a loop that retries immediately only makes the queue longer for everyone. Talent profiles keep their own daily cap, below under Errors.
Skills
Rather than paste this page into a prompt: every domain has a skill — one markdown file an agent reads before it calls anything, generated from the same self-description as these pages.
Authentication & keys
Authorization: Bearer fa_live_… # recommended X-API-Key: fa_live_… # alternative ?api_key=fa_live_… # browser playground only
Keys are created in the dashboard and shown once; the server stores only a hash. A key can be scoped to specific domains, capped per day, rotated and revoked. Sign in with Google at /login. Free samples — each domain's free_samples — and the discovery endpoints (/v1/domains, /v1/{domain}, /facets) need no key.
Credits & pricing
Every paid request costs a fixed number of credits, set by what it costs to serve — reading in layers is cheaper than pulling everything. Upstream errors are refunded; 404s are not charged.
| Operation | Credits |
|---|---|
| discovery, facets, free samples | 0 |
| search | 2 |
| read · brief / detail / full | 1 / 1–3 / 2–10 |
| ask · effort=low | 50 |
| ask · effort=medium | 100 |
| ask · effort=high | 200 |
| Plan | Credits / month | rpm | Keys | Max effort | Price |
|---|---|---|---|---|---|
| Free | 2,000 | 60 | 3 | high | free |
| Pay as you go | 2,000 | 60 | 5 | high | packs only |
| Starter | 25,000 | 120 | 10 | high | $9.90 / mo |
| Pro | 150,000 | 300 | 25 | high | $49.90 / mo |
| Team | 700,000 | 600 | 100 | high | $99.00 / mo |
Packs: $5 → 10,000 · $20 → 45,000 · $50 → 125,000. Monthly allowance resets and does not roll over; purchased credits never expire and are spent after the allowance. Details on Billing. Over the limit: 402 insufficient_credits; over rpm: 429 with Retry-After.
During the beta searching and reading count 0 and ask draws on a daily ask allowance first — see Capacity & rate limits.
Errors
{"error": {"code": "insufficient_credits", "message": "…", "details": {"required": 50, "balance": 12}}, "request_id": "req_…"}
| HTTP | code | When |
|---|---|---|
| 400 | invalid_request | Bad parameter, unknown level, undeclared filter field |
| 401 | unauthorized | No key / invalid / revoked / expired |
| 402 | insufficient_credits | Balance below this call's cost |
| 403 | forbidden | Key not scoped to this domain, missing a permission the read needs, or plan does not allow this effort |
| 404 | not_found | id does not exist (not charged) |
| 429 | rate_limited | Over rpm; see Retry-After |
| 429 | quota_exceeded | A daily quota is used up (talent profiles); retrying will not help, see below |
| 502 | upstream_error | Upstream failed; refunded |
| 503 | domain_unavailable | Domain is building / in maintenance |
A missing permission says what to do. Some reads need a permission on the key beyond the domain itself (cases:fulltext is the first). The 403 carries details.grant — the one that is missing — details.alternative, a call that needs no permission, and details.how. Nothing is charged.
{"error": {"code": "forbidden", "message": "view 'raw' of 'cases' needs the 'cases:fulltext' grant on your API key",
"details": {"grant": "cases:fulltext", "alternative": "GET /v1/cases/read/<id>?level=detail", "how": "…"}}, "request_id": "req_…"}
Two kinds of 429. rate_limited is a per-minute or at-once limit and clears by itself (Retry-After 60 or 1). quota_exceeded is a daily count that resets at 00:00 UTC: your daily search-and-read limit, your daily ask allowance (see Capacity & rate limits), or the talent cap — distinct people whose profile you have read (and, separately, live Scholar refreshes), which only a talent:bulk permission lifts. Reading the same person again does not count toward that one; card, brief and search are never capped by it. details carries limit, used_today, resets_at and, where it applies, requested_new, grant and how; GET /v1/me shows where you stand before you hit it.
Streaming endpoints that fail after output has started emit {"event":"error", …} instead of an HTTP status. Quote request_id when reporting a problem.
Filter DSL
One filter grammar for every domain, in search.filters:
| Syntax | Meaning | Types |
|---|---|---|
| "field": "v" | equals | keyword / integer / bool |
| "field": ["a", "b"] | any of | keyword |
| "field": {"gte": 20, "lte": 50} | range, inclusive; ISO dates for datetime | integer / number / datetime |
| "field": {"text": "张"} | full-text match | text |
| "_not": {…} | negate | — |
| "_or": [{…}, {…}] | or | — |
Each domain declares its fields, types and allowed ops in GET /v1/{domain} (and in the search section of each domain page here). Undeclared fields return 400 — silently ignoring them would let a caller believe it filtered when it did not.
Streaming (NDJSON)
Every ask has a /stream variant returning application/x-ndjson: one JSON event per line, same request body, identical across domains. The first line is always billing.
| event | When | Payload |
|---|---|---|
| billing | First line | credits.charged, credits.balance, request_id |
| 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 incl. answer_truncated |
| error | On failure | Message |
Only with verbose: true | ||
| tool_call / tool_result | Tool invoked / returned | Name + arguments / summary |
| thinking | Reasoning emitted | Text |
| warning | Degraded path | Message |
curl -sN -X POST "https://api.1stauthor.com/v1/papers/ask/stream" \
-H "Authorization: Bearer $FA_KEY" -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: open 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 for Claude Code, Cursor and Python is on the MCP page.
SDK / CLI — with DeepXiv
The client lives with DeepXiv. While 1stAuthor is in beta we work closely with them, and their SDK is how you reach these domains from a terminal or from Python: deepxiv covers arXiv papers and the web natively, deepxiv fa covers every domain on this site, and one token works for both. Those calls go through https://data.rag.ac.cn/fa — itself in mainland China — so you can start without a 1stAuthor key at all.
pip install deepxiv-sdk deepxiv fa domains # what is there (free) deepxiv fa spec talent # filters, read levels, prices (free) deepxiv fa search talent "Federica Sarro" # search → ids deepxiv fa read talent 7870 --level brief # read only as deep as you need deepxiv fa ask "…" -d law -e high # a cited answer (registered key)
Filters are -F "h_index>=50", repeated and ANDed, and they are checked against the domain's self-description before anything is spent. In Python the same calls are from deepxiv_sdk import FAClient. Every command, filter and price: the deepxiv fa guide.
A key from this site is the other door: it talks to https://api.1stauthor.com directly, with the credits, rate limits and per-key controls on the pricing page — the same three verbs, the same responses. DeepXiv's token stays free within its daily limit. Everything below works with either one, over plain HTTPS + JSON:
import requests
BASE = "https://api.1stauthor.com" # mainland China: "https://api.rag.ac.cn"
H = {"Authorization": "Bearer fa_live_…"}
hits = requests.post(f"{BASE}/v1/papers/search", json={"query": "agentic memory", "top_k": 5}, headers=H).json()["hits"]
doc = requests.get(f"{BASE}/v1/papers/read/{hits[0]['id']}", headers=H).json()["data"] # level=detail
sec = requests.get(f"{BASE}/v1/papers/read/{hits[0]['id']}", params={"level": "full", "section": doc["sections"][1]["name"]}, headers=H).json()["text"]