--- name: 1stauthor-appraise description: The 1stAuthor appraise domain. --- # 1stAuthor Appraise Academic appraisal: which academicians and society fellows have cited a paper, and what they actually said. 112k arXiv papers authored by 5,427 fellows and academicians (Chinese Academies, US NAS/NAE, Royal Society / RAEng, ACM / IEEE / AAAI / ACL / AAAS / IAPR / CCF), with 5.26M parsed references and 8.3M citing sentences, each classified by type and stance. The id is the paper being appraised (arXiv id / DOI / title). ask turns the matched sentences into a Chinese appraisal paragraph for grant reports and promotion dossiers, with the English original attached to every claim. Base URL `https://api.1stauthor.com`. Every call takes `Authorization: Bearer $FA_API_KEY`; the free samples named below work without a key. Free sample id: `arxiv:2402.03216`, free sample query: `BGE-M3`. ## Three verbs, every domain ``` POST /v1/{domain}/search {query, filters?, top_k?} → hits[].id + a card each GET /v1/{domain}/read/{id}?level=brief|detail|full → read as deep as you need POST /v1/{domain}/ask {query, effort: low|medium|high} → an answer with real citations ``` `read` also takes `extra=` for another side of the same document and `format=json|md|html`. At `level=full`, `section=` reads one section and `characters=N` the first N characters. ## Start here - **Who of note has cited a paper** — `POST /v1/appraise/search {"query": "BGE-M3"}` - **Read what they said** — `GET /v1/appraise/read/arxiv:2402.03216` - **Only positive citations by Chinese academicians** — `GET /v1/appraise/read/arxiv:2402.03216?org=CAS,CAE&stance=positive` - **Write it up in Chinese** — `POST /v1/appraise/ask {"query": "BGE-M3 有哪些知名学者的评价", "effort": "medium"}` ## Search filters | field | type | meaning | |---|---|---| | `org` | keyword · eq any | Honour body: CAS / CAE (Chinese academies), NAS / NAE (US), ROYALSOC / RAENG (UK), ACM / IEEE / AAAI / ACL / AAAS / IAPR / CCF (fellows); several allowed | | `bucket` | keyword · eq any | Weight class: academy (academicians) / major (ACM, IEEE … fellows) / other | | `stance` | keyword · eq any | Stance of the citing sentence (model-assigned): positive / neutral / negative | | `type` | keyword · eq any | Citation type (model-assigned): endorse / buildon / exemplar / baseline / resource / critique / motivate / background | | `about_target` | bool · eq | Whether the sentence is about this paper itself rather than a passing mention | | `min_h_index` | integer · eq | Only people with at least this h-index | | `honoree` | text · text | Filter by name (zh/en, substring) | | `citing_year` | integer · eq range | Year of the citing paper; ranges allowed | Rarely needed, but valid: `affiliation`, `section`, `mentions_name`, `annotated`. Filters combine with AND; `_or` / `_not` are available. Ranges are `{"gte": n}` / `{"lte": n}`, full text is `{"text": "…"}`. ## Read | level | credits | returns | |---|---|---| | `brief` | 1 | Summary card: how many fellows, citing papers and sentences, the stance and type breakdown, and the single strongest sentence | | `detail` (default) | 3 | The list plus the sentences (the default, level=detail): per citation the type, stance, whether it is about this paper, the model's one-line claim, a Chinese translation, the English original, the section and the citing paper. Only opinionated types by default (no background); pass type= for everything | | `full` | 5 | All the evidence (level=full): background citations included, every sentence with its neighbouring sentences and the raw bibliography entry — for verification | | extra | credits | returns | |---|---|---| | `honorees` | 2 | The list: each fellow's Chinese titles, affiliation, h-index, talent person_id, how many times they cited it and in which papers (no sentences) | ## Ask `POST /v1/appraise/ask {query, effort}` — Turns "who of note has evaluated this paper" into Chinese appraisal text: resolves the paper (semantic search over papers → arXiv id), pulls the fellows' citing sentences, then writes one paragraph per person. Wording may be positive but must not exceed what the original says; every paragraph carries the English original and its source. effort sets how many people are written up (low 5 / medium 10 / high 20). Costs 50 / 100 / 200 credits by effort. Append `/stream` for NDJSON; the first event is always `billing`. `sources` is the retrieval set, not the citation list — filter it by the ids that appear in `answer`. `answer_truncated` means the answer is incomplete; say so. ## Also here ## Facets `GET /v1/appraise/facets?field=` lists the legal values for `org`, `bucket`, `type`, `stance` — free, no key. Use it instead of guessing a spelling. ## Working rules - **Search first, read second.** A search hit is a card; decide from the card which ids deserve a read. - **Read in layers.** `detail` answers most questions; go to `full` only when the answer is not in it. - **Filters are declared.** An undeclared filter field is a 400, never a silent no-op. `GET /v1/{domain}` lists what exists. - **Cite what you read.** Use the citation format below, and say plainly when the corpus has nothing. - **Failures are not charged.** A 404 costs nothing; an upstream error is refunded. Quote `meta.request_id` when reporting one. Citation format: `[appraise: ]`. ## What this corpus will and will not tell you - Coverage: Covers only arXiv full texts authored by these 5,427 fellows and academicians; their journal-only papers and citations by anyone else are not included. No hit means this set of papers does not cite it — not that the work is uncited. - Three id forms: arxiv:2402.03216 (bare ids accepted), doi:10.1145/…, and title:. The first two are exact lookups (~40ms); title: is a substring match over normalised bibliography text — 3–6 seconds, and papers with similar titles can collide, so the response carries warnings. - search has no vector index: the query first goes through the papers domain's semantic search to identify the paper (so a title, a model name or a one-line description all work), then the arXiv id is used for lookup. If it picks the wrong paper, read by id instead: read arxiv:. - type / stance / about_target / claim / zh are model-assigned; the sentence itself is the evidence. Quote the sentence in anything formal. Sentences with annotated=false have not been classified yet. - level=detail returns only opinionated citation types by default; background citations are more than half the total — use level=full or pass type= to get them. - How ask writes: early work may become 'early pioneering work' and a baseline 'widely adopted as a comparison baseline', but nothing may be asserted that the original sentence does not say. Every paragraph carries the English original so a reader can check it. - people[].person_id is the talent domain's id — read talent for that person's full profile. - Attribution: author-year references ('Li et al., 2025') can match several bibliography entries; such sentences are marked ambiguous=true. --- Generated from https://api.1stauthor.com/v1/appraise on 2026-10-14. Full reference: https://1stauthor.com/docs/appraise/