Appraise
Overview
Which academicians and society fellows have cited a paper, in their own words — and a citable appraisal written from those sentences.
- status
- live
- document id
target_keye.g.arxiv:2402.03216- citation
[appraise:]
Common calls
Who of note has cited a paper
POST /v1/appraise/search {"query": "BGE-M3"}Read what they said
GET /v1/appraise/read/arxiv:2402.03216Only positive citations by Chinese academicians
GET /v1/appraise/read/arxiv:2402.03216?org=CAS,CAE&stance=positiveWrite it up in Chinese
POST /v1/appraise/ask {"query": "BGE-M3 有哪些知名学者的评价", "effort": "medium"}Give it a paper — a title, an arXiv id, or the name people call it by — and it answers with the academicians and society fellows who have cited it, the sentence each of them wrote, and whether that sentence endorses the work or merely lists it. resolved_by says how the paper was recognised: citation-alias means the name lives in other people's bibliographies rather than in the paper's own title.
The fine print
- 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:<paper 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:<id>.
- 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 <person_id> 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.
Search
POST
/v1/appraise/searchHybrid retrieval, one card per hit. 3 credits. Free sample:
BGE-M3.Filter fields
| field | type · ops | meaning |
|---|---|---|
| org | keyword · eq anyCAS · CAE · NAS · NAE · ROYALSOC · RAENG … 13 values, /facets lists them all | 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 anyacademy · major · other | Weight class: academy (academicians) / major (ACM, IEEE … fellows) / other |
| stance | keyword · eq anypositive · neutral · negative | Stance of the citing sentence (model-assigned): positive / neutral / negative |
| type | keyword · eq anyendorse · buildon · exemplar · baseline · critique · resource · motivate · background | 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 |
4 more, all usable
| field | type · ops | meaning |
|---|---|---|
| affiliation | text · text | Filter by the citer's affiliation (Google Scholar string, substring) |
| section | text · text | Section of the citing paper where the citation appears (substring, e.g. related work) |
| mentions_name | bool · eq | Whether the sentence names the method or model |
| annotated | bool · eq | Whether the sentence has been annotated (false = raw sentence only) |
Parameters
| Parameter | Type | Description |
|---|---|---|
| query REQUIRED | string | 1–1000 characters. Or an array of up to 5 (batch; hits become results[]). |
| top_k | integer= 10 | 1–20. |
| fields | brief · head= brief | head costs one more credit and returns the head view per hit. |
| filters | json | Filter DSL object (see Getting started); declared fields are listed above. |
| mode | hybrid · title= hybrid | Retrieval mode. Leave it out to use the first. |
| offset | integer= 0 | Pagination. |
Example
{ "domain": "appraise", "query": "…", "hits": [ { "id": "arxiv:2402.03216", "score": 0.83, "brief": { … } } ], "total": null, "coverage": …, "warnings": [],
"meta": { "request_id": "req_…", "credits": { "charged": 2, "balance": 1998, "pool": "allowance" }, "latency_ms": 41, "cached": false } } Undeclared filter fields return 400 rather than being ignored silently. Filters combine with AND;
_or / _not are available.Read
GET
/v1/appraise/read/{target_key}Three depths.
detail is the default. Free sample: arxiv:2402.03216.Levels
| 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 |
Extras
One side of the same document, in place of a level.
| 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) |
Parameters
| Parameter | Type | Description |
|---|---|---|
| target_key (path) REQUIRED | string | Document id (target_key). |
| level | brief · detail · full= detail | How deep to read. |
| extra | honorees | Read one side instead of a level. |
| format | json · md · html= json | Response shape. |
| stance | string | comma-separated (level = detail) |
| type | string | comma-separated citation types (level = detail) |
| org | string | comma-separated honour bodies (level = detail) |
| bucket | string | academy / major / other (level = detail) |
| min_h_index | integer | minimum h-index (level = detail) |
| honoree | string | filter by name (substring) (level = detail) |
| section | string | filter by section (substring) (level = detail) |
| max_sentences | integer= 8 | 每人最多几条原句 (level = detail) |
Example
{ "domain": "appraise", "id": "arxiv:2402.03216", "level": "detail", "view": "citations", "data": { … } | "text": "…", "token_count": 1834, "meta": { … } } The older
GET /v1/appraise/doc/{id}?view=… still works.Read many
POST
/v1/appraise/readUp to 50 ids, one level. Missing ids come back with
error: "not_found" and are not charged.Parameters
| Parameter | Type | Description |
|---|---|---|
| ids REQUIRED | string[] | Document ids. |
| level | brief · detail · full= detail | Level for every id. |
| extra | honorees | Read one side instead. |
Example
{ "domain": "appraise", "level": "detail", "docs": [ { "id": "…", "data": { … } }, { "id": "…", "error": "not_found" } ], "meta": { … } } Facets
GET
/v1/appraise/facets?field={field}Legal values for a filter field, so an agent never guesses; precomputed fields carry counts, declared enums come without. Free, no key.
Parameters
| Parameter | Type | Description |
|---|---|---|
| field REQUIRED | org · bucket · type · stance | Filter field with facets. |
| limit | integer= 50 | Max values. |
Example
{ "domain": "appraise", "field": "…", "values": [ { "value": "…", "count": 3120 } ], "meta": { … } } Askregistered key+ /stream
POST
/v1/appraise/askTurns "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).
effort low / medium / high = 50 / 100 / 200 credits. Append /stream for NDJSON; the first event is always billing. A failure before the first answer_delta is refunded.Parameters
| Parameter | Type | Description |
|---|---|---|
| query REQUIRED | string | 1–2000 characters. Be specific; ask for numbers if you want numbers. |
| paper | string | name the paper directly (arXiv id / DOI / title) and skip resolution |
| filters | string | restrict which citations are used (same DSL as search filters) |
| effort | low · medium · high= low | Reading rounds, and the price: 50 / 100 / 200 credits. Your plan caps it. |
| verbose | bool= false | Include the tool-call trace (tool_call / tool_result / thinking events when streaming). |
| top_k | integer= 10 | Speculative prefetch size. |
| stream_answer | bool= true | Streaming only: false emits one answer event instead of deltas. |
| max_rounds | integer | 0–8, overrides the effort preset. |
| force_answer_after | number | Seconds; hard cutover into the answer phase. |
| max_answer_tokens | integer= 4096 | Hitting it sets answer_truncated. |
| language | string | Answer language; defaults to the query’s. |
Example
{ "answer": "… [appraise:<honoree_id> <name>] …", "sources": [ … ], "stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false }, "coverage"?: { … }, "meta": { "credits": { "charged": 50, … } } } Citations are real — every id in
answer exists in this domain (format [appraise: ] ). sources is the retrieval set, not the citation list. answer_truncated means incomplete.