1 · Machine-readable specification一 · 机器可读规范
The full contract is published as OpenAPI 3.1, generated from the same router sources the server runs (scripts/build_openapi.py) — it cannot drift from the code by hand-editing. Each path carries an x-magalia-status: live verified returning 200 on this server, staged built but not yet deployed, retired deliberately tombstoned (HTTP 410).
完整契约以 OpenAPI 3.1 发布，由服务器所运行的同一路由源码生成（scripts/build_openapi.py）—— 不可能因手工编辑而与代码漂移。每个路径带 x-magalia-status：live 已验证在本服务器返回 200；staged 已构建、尚未部署；retired 有意下线（HTTP 410）。
2 · Quick start二 · 快速上手
Five one-liners. Every one of these is run against the live server before this page ships — if it's printed here, it works.五条单行命令。此处每一条在页面发布前都对生产服务器实测过 —— 凡印于此，必可运行。
Full-text search (websearch syntax)全文检索（websearch 语法）
curl -s 'https://magalia.wiki/api/search?q="dis manibus"&size=5'
# quoted phrase · augustus -caesar (negation) · augus* (prefix) · A B = ANDFacet distribution of any query任意查询的分面分布
curl -s 'https://magalia.wiki/api/facets?q=augustus'
# counts per material / period / object_type / place / language / fidelity
# add &collapsed=false for the raw, un-canonicalised distributionReverse lookup — from a print reference反向检索 —— 由印本编号出发
curl -s 'https://magalia.wiki/api/lookup?CIL=VI+1234'
# also EDCS=… EDH=… TM=… — resolves via the equivalents ledgerDictionary gloss (Lewis & Short + morphology)词典释义（Lewis & Short + 形态）
curl -s 'https://magalia.wiki/api/gloss?word=imperator&lang=la'Per-record text逐条文本
curl -s 'https://magalia.wiki/api/text?ns=isic&id=ISic000001'3 · Endpoint reference三 · 端点一览
Rendered live from openapi.json — the table below is the spec.由 openapi.json 实时渲染 —— 下表即规范本身。
4 · Research recipes四 · 研究配方
Epigraphic-habit curve for any term任意词项的铭刻习惯曲线
Loop /api/facets?q=TERM and read the period facet: the diachronic distribution of a formula, office, or deity across the corpus — the analysis behind the epigraphic-habit finding, for your own term, in one request.调用 /api/facets?q=词项 并读取 period 分面：即得某一程式、官职或神祇在语料中的历时分布 —— 铭刻习惯专题背后的分析，一次请求即可用于你自己的词项。
curl -s 'https://magalia.wiki/api/facets?q="pontifex maximus"' | jq '.facets.period'Combined authority query组合权威查询
Authority filters compose with full-text: marble inscriptions mentioning imperator found at Catina.权威筛选可与全文检索复合：如于 Catina 出土、提及 imperator 的大理石铭文。
curl -s 'https://magalia.wiki/api/search?q=imperator&material=Marble&place=Catina'Named-entity search — emperors, deities, offices命名实体检索 —— 皇帝、神祇、官职
/api/mentions/rulers lists the attested emperor authority; then filter search by person so Trajan reaches the Latin Traianus./api/mentions/rulers 列出实际见证的皇帝权威表；继而按人物过滤检索，使 Trajan 命中拉丁 Traianus。
curl -s 'https://magalia.wiki/api/mentions/rulers'
curl -s 'https://magalia.wiki/api/mentions/values?kind=deity'Bulk harvest, politely批量收取，须有节制
Page with page/size (size ≤ 100). Please keep it serial and cache locally; the corpora are also documented with checksums on the datasets page — for whole-dataset work, prefer those files over crawling the API.用 page/size 分页（size ≤ 100）。请串行请求并本地缓存；各数据集另于数据集页附校验和发布 —— 整库分析请优先取用文件而非爬取接口。
for p in 1 2 3; do
curl -s "https://magalia.wiki/api/search?q=%22dis%20manibus%22&page=$p&size=100" > dm-$p.json
doneStaged — retrieval & semantic similarity待部署 —— 溯源检索与语义相似
staged /api/retrieve (source-attributed passage retrieval, the engine behind the study assistant) and /api/similar (embedding nearest-neighbours) are built and in this spec, but not yet on the production server. They will flip to live with the next Track B deploy; this page's status chips are re-probed, not promised./api/retrieve（带出处的段落检索，学习助手的引擎）与 /api/similar（嵌入最近邻）已构建并载入本规范，但尚未部署至生产服务器。下次 Track B 部署后即转为 live；本页状态标记以实测为准，绝不预支。
5 · Citing what the API returns五 · 征引接口所返数据
ns) and upstream identifier; corpus snapshots are dated (see data status). When citing a search result in print, cite the upstream corpus record (EDCS / EDH / I.Sicily / IAph …) as primary, and the magalia query permalink as the retrieval instrument, with the date. Derived and model-assisted fields are always labelled — nothing model-generated is served as if attested.
⚠ 来源。 每行结果均带命名空间（ns）与上游标识符；语料快照均注明日期（见数据状态）。付梓征引时，应以上游语料记录（EDCS / EDH / I.Sicily / IAph 等）为首要出处，magalia 查询永久链接为检得工具并注日期。派生与模型辅助字段一律标明 —— 凡模型生成者，绝不冒充实证。