The service currently runs on a single small machine: about 50 search requests/s and ~20 concurrent ask sessions across all users. Please keep concurrency modest (≤ 5 per client) and back off on 429 using Retry-After. Details →

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 URLForServed from
https://api.1stauthor.comeverywhere elseTokyo
https://api.rag.ac.cnmainland ChinaShanghai

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:

Planper minuteat onceper day
Free · Pay as you go6055,000
Starter1201010,000
Pro3001025,000
Team6001050,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.

OperationCredits
discovery, facets, free samples0
search2
read · brief / detail / full1 / 1–3 / 2–10
ask · effort=low50
ask · effort=medium100
ask · effort=high200
PlanCredits / monthrpmKeysMax effortPrice
Free2,000603highfree
Pay as you go2,000605highpacks only
Starter25,00012010high$9.90 / mo
Pro150,00030025high$49.90 / mo
Team700,000600100high$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_…"}
HTTPcodeWhen
400invalid_requestBad parameter, unknown level, undeclared filter field
401unauthorizedNo key / invalid / revoked / expired
402insufficient_creditsBalance below this call's cost
403forbiddenKey not scoped to this domain, missing a permission the read needs, or plan does not allow this effort
404not_foundid does not exist (not charged)
429rate_limitedOver rpm; see Retry-After
429quota_exceededA daily quota is used up (talent profiles); retrying will not help, see below
502upstream_errorUpstream failed; refunded
503domain_unavailableDomain 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:

SyntaxMeaningTypes
"field": "v"equalskeyword / integer / bool
"field": ["a", "b"]any ofkeyword
"field": {"gte": 20, "lte": 50}range, inclusive; ISO dates for datetimeinteger / number / datetime
"field": {"text": "张"}full-text matchtext
"_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.

eventWhenPayload
billingFirst linecredits.charged, credits.balance, request_id
startRun beginsResolved effort, rounds, budget
answer_startAnswer phase opens—
answer_deltaRepeatedlyAnswer text chunk
sourcesAfter the answerRetrieval set (superset of what is cited)
doneLast lineStats incl. answer_truncated
errorOn failureMessage
Only with verbose: true
tool_call / tool_resultTool invoked / returnedName + arguments / summary
thinkingReasoning emittedText
warningDegraded pathMessage
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"]