# knowledge

> A sourced knowledge base connecting people, places, events, organizations, works and concepts.

## Language

This guide is in English. Prefer an explicit lang parameter or language-prefixed URL.
Otherwise use a supported Accept-Language preference; if it is absent or unrecognized,
default to English. The content source language remains Chinese (zh). Public reading
may fall back to Chinese when a published translation is unavailable; respect the
returned lang/fallback/availableLangs fields and never invent a translation.

## Start Here

- [English home](https://knowledge.ivjn.us/en/index.html)
- [Traditional Chinese home](https://knowledge.ivjn.us/zh-hant/index.html)
- [About the knowledge base](https://knowledge.ivjn.us/en/about.html)
- [Categories](https://knowledge.ivjn.us/en/categories.html)
- [Tags](https://knowledge.ivjn.us/en/tags.html)
- [Search](https://knowledge.ivjn.us/en/search.html)
- [Same-name entries](https://knowledge.ivjn.us/en/same-name.html)
- [Ask with citations](https://knowledge.ivjn.us/en/ask.html)
- [OpenAPI: full request and response schemas](https://knowledge.ivjn.us/api/v1/openapi.json)
- [Build, storage and language metadata](https://knowledge.ivjn.us/api/v1/version)
- [English RSS](https://knowledge.ivjn.us/en/feed.xml)
- [English sitemap](https://knowledge.ivjn.us/en/sitemap.xml)

## Reading and Citation

Use GET /api/v1/entities?lang=en&limit=20&offset=0 to browse, and
GET /api/v1/search?q=museum&lang=en to search. Filters include type, tag and category.
Traditional Chinese uses the canonical locale zh-hant; zh-TW, zh-HK, zh-MO and
zh-Hant are recognized visitor preferences. Editorial writes use lang=zh-hant.
Untranslated entries retain the original source text with an explicit fallback flag.
GET /api/v1/same-names?q=Military%20Museum&lang=en finds exact titles/aliases;
id selects an entry and its alternatives. Names may repeat; IDs and URL slugs are distinct.

Public pages support .html, .json, .md, .xml and .txt. Cite canonical .html URLs
and the entry's reference sources. Factual history and content revisions are separate.
Only published entries/translations are public. Do not expose or infer draft content.
Ask can return placeholder=true when a generation model is not configured.

An entry may contain published perspectives with separate attribution, regional scope,
applicable dates and reference sources. Language does not imply a country or political
stance. GET /api/v1/entities/{id}/perspectives lists these accounts; an optional region
filter is explicit and does not infer the visitor's location. Preserve attribution and
time when citing a disputed name or claim; inclusion does not imply endorsement.
Draft and archived perspectives are excluded from public reads, search and Ask.
Body references use [^sourceId] and render as numbered links [1], [2] to reference
lists, with backlinks to each occurrence. Each perspective has its own source scope.

## Editing and Administration

POST /api/v1/auth/login returns a JWT. New accounts are readers; content editing
requires an active editor/admin JWT or the operator-configured API_TOKEN.
Send credentials in Authorization: Bearer, never in URL query parameters.
POST /api/v1/tags and /api/v1/categories create taxonomy terms.

For exact multilingual editing, GET /api/v1/editorial/entities/{id}?lang=en,
then PUT the complete entity with its current shared revision to the same URL.
Editorial lang defaults to zh (the source), not the visitor language. Missing
translations start as blank drafts. A stale revision returns 409: reload and reconcile.
Source IDs/types are immutable; publish the source before publishing a translation.
Use aliases and disambiguation labels to connect and distinguish same-name entries.

The browser editor is /editor/ and administration is /admin/. Backoffice endpoints
also accept user JWTs; cookie-authenticated writes require a matching Origin.
Account administration requires an administrator, and protects the last active admin.
Production content is stored in PostgreSQL. Reindex reloads the authoritative backend.

GET /api/v1/templates describes entity fields and multilingual page text. Administrators
can PUT /api/v1/admin/templates to change field labels, order and visibility or add
custom fields. Editors can PUT /api/v1/editorial/site-text to replace one locale's
page text. Both require the current settings revision. Hidden fields retain values;
visibility controls presentation and does not make metadata secret.

GET /api/v1/admin/embeddings reports 768-dimensional indexing progress; POST schedules
an incremental scan. These endpoints require an administrator JWT or API_TOKEN.
Vectors cover actual non-deleted content locales, update asynchronously, and remain private.
Embedding indexing does not change the existing keyword search or enable answer generation.

## MCP

Connect an MCP Streamable HTTP client to https://knowledge.ivjn.us/mcp.
Initialization, tools/list and public read tools need no authorization. Forward the
Bearer header for protected tools. The wiki_api tool covers every documented REST
endpoint with method, path, query and body fields; it cannot call arbitrary URLs.
Dedicated tools include wiki_search, wiki_get_entity, wiki_list_entities,
wiki_same_names, wiki_get_editorial_entity, wiki_save_translation,
wiki_create_term, wiki_embedding_status, wiki_entity_perspectives and wiki_get_templates.
Use tools/list for complete tool schemas.

## Endpoint Catalog

The following catalog is generated from the same OpenAPI contract served by this build.

- `GET /api/v1/admin/embeddings`: Embedding progress (administrator JWT or API_TOKEN)
- `POST /api/v1/admin/embeddings`: Schedule incremental embedding scan (administrator JWT or API_TOKEN)
- `POST /api/v1/admin/import`: Batch-import content documents in one validated commit: create absent paths, replace only when expectSha256 matches, report conflicts (administrator JWT or API_TOKEN)
- `PUT /api/v1/admin/templates`: Configure field labels, order, visibility and custom fields (administrator JWT or API_TOKEN)
- `POST /api/v1/ask`: Ask with citations (placeholder without LLM key)
- `POST /api/v1/auth/login`: Login; returns JWT
- `POST /api/v1/auth/logout`: Logout (client discards JWT)
- `POST /api/v1/auth/register`: Register user
- `GET /api/v1/backoffice/admin/embeddings`: Backoffice get admin/embeddings
- `POST /api/v1/backoffice/admin/embeddings`: Backoffice post admin/embeddings
- `GET /api/v1/backoffice/admin/overview`: Backoffice get admin/overview
- `POST /api/v1/backoffice/admin/reindex`: Reload content from the authoritative backend
- `PUT /api/v1/backoffice/admin/templates`: Backoffice put admin/templates
- `GET /api/v1/backoffice/admin/users`: Backoffice get admin/users
- `POST /api/v1/backoffice/admin/users`: Backoffice post admin/users
- `PATCH /api/v1/backoffice/admin/users/{id}`: Backoffice patch admin/users/{id}
- `GET /api/v1/backoffice/entities`: Backoffice get entities
- `POST /api/v1/backoffice/entities`: Backoffice post entities
- `GET /api/v1/backoffice/entities/{id}`: Backoffice get entities/{id}
- `PUT /api/v1/backoffice/entities/{id}`: Backoffice put entities/{id}
- `DELETE /api/v1/backoffice/entities/{id}`: Backoffice delete entities/{id}
- `POST /api/v1/backoffice/login`: Backoffice post login
- `POST /api/v1/backoffice/logout`: Backoffice post logout
- `GET /api/v1/backoffice/me`: Backoffice get me
- `POST /api/v1/backoffice/preview`: Backoffice post preview
- `GET /api/v1/backoffice/site-text`: Backoffice get site-text
- `PUT /api/v1/backoffice/site-text`: Backoffice put site-text
- `POST /api/v1/backoffice/taxonomy/categories`: Backoffice post taxonomy/categories
- `POST /api/v1/backoffice/taxonomy/tags`: Backoffice post taxonomy/tags
- `GET /api/v1/backoffice/templates`: Backoffice get templates
- `GET /api/v1/categories`: Category tree (or flat with ?flat=1; the flat list is paged with total/offset/limit)
- `POST /api/v1/categories`: Create categories
- `GET /api/v1/categories/{id}`: Get category by id or slug
- `GET /api/v1/discover`: Browse published new, today or hot content
- `GET /api/v1/editorial/entities`: List editable source entries, including drafts
- `POST /api/v1/editorial/entities`: Create source entry
- `GET /api/v1/editorial/entities/{id}`: Read exact editable locale
- `PUT /api/v1/editorial/entities/{id}`: Save exact editable locale with shared revision
- `DELETE /api/v1/editorial/entities/{id}`: Soft-delete source and hide its published translations
- `POST /api/v1/editorial/preview`: Preview Markdown, maps, flowcharts, images and citations (editor/admin JWT or API_TOKEN)
- `GET /api/v1/editorial/site-text`: Read page text for editing
- `PUT /api/v1/editorial/site-text`: Replace one locale of page text with revision check (editor/admin JWT or API_TOKEN)
- `GET /api/v1/entities`: List/search entities
- `POST /api/v1/entities`: Create entity
- `GET /api/v1/entities/{id}`: Get entity; relations holds at most 50 edges, relationsTotal the full count (page the rest via /relation)
- `PUT /api/v1/entities/{id}`: Replace entity
- `PATCH /api/v1/entities/{id}`: Patch entity fields
- `DELETE /api/v1/entities/{id}`: Soft-delete entity (status=deleted)
- `GET /api/v1/entities/{id}/history`: Factual timeline (not content revisions)
- `GET /api/v1/entities/{id}/perspectives`: Read published attributed regional/institutional perspectives
- `GET /api/v1/entities/{id}/perspectives/{perspectiveId}`: Read published attributed regional/institutional perspectives
- `GET /api/v1/entities/{id}/relation`: Editable relation page + groups; relations paged with total/offset/limit
- `POST /api/v1/entities/{id}/relation`: Upsert relation doc
- `PUT /api/v1/entities/{id}/relation`: Upsert relation doc
- `PATCH /api/v1/entities/{id}/relation`: Upsert relation doc
- `DELETE /api/v1/entities/{id}/relation`: Delete relation doc
- `GET /api/v1/entities/{id}/versions`: Content edit revisions
- `GET /api/v1/entities/{id}/versions/{n}`: Revision snapshot
- `GET /api/v1/me`: Current user
- `PATCH /api/v1/me`: Update profile
- `GET /api/v1/openapi.json`: This document
- `POST /api/v1/reindex`: Reload content from the authoritative backend
- `GET /api/v1/relation-types`: List relation rules and directed [fromType,toType] pairs; labels use the Chinese source language
- `GET /api/v1/relations`: List relation edges (?entity=&type=); paged with total/offset/limit, count equals total
- `POST /api/v1/relations`: Create factual relation edge
- `DELETE /api/v1/relations`: Delete factual relation edge by id
- `GET /api/v1/same-names`: Find published same-name entries
- `GET /api/v1/search`: Search entities (same filters as list; includes highlight hits)
- `POST /api/v1/search`: Search with JSON body filters
- `GET /api/v1/stats/hot`: Hot entities
- `GET /api/v1/stats/summary`: Stats summary
- `GET /api/v1/tags`: List tags with counts; paged with total/offset/limit
- `POST /api/v1/tags`: Create tags
- `GET /api/v1/tags/{id}`: Get tag by id or slug
- `GET /api/v1/templates`: Read template fields and multilingual page text
- `GET /api/v1/types`: List supported entity types and directories; labels use the Chinese source language
- `GET /api/v1/users/{id}`: Public user profile
- `GET /api/v1/version`: Build and content version
- `POST /mcp`: MCP Streamable HTTP (anonymous reads; Bearer for writes)