{"openapi":"3.1.0","x-service-contract":{"role":"Shared lexical service for Vanagon and Gerry. Preserved Vanagon.com bus terminology and mailing-list slang, separately sourced contemporary parts references, and clearly labeled machine-assisted translations.","repository":"https://github.com/mbarbine/vanagon-dictionary","origin":"https://dictionary.vanagon.com","consumers":{"vanagon":"https://vanagon.com","gerry":"https://gerry.vanagon.com"},"productionOrigins":{"dictionary":"https://dictionary.vanagon.com","vanagon":"https://vanagon.com","gerry":"https://gerry.vanagon.com"},"productionActivation":"Configured for dictionary.vanagon.com with the retained dictionary.ja1.io alias. Consult deployment acceptance evidence for current DNS/TLS status.","ownership":{"dictionary":"Canonical terms, definitions, translations, provenance, editorial revisions, lexical APIs and exports.","vanagon":"Historical page/capture presentation, editorial pages, navigation, and its own feeds and protocols.","gerry":"Messages, discussions, archives, community accounts, and its own feeds and protocols."},"independentServices":"Shared community footer and lexical service; each site retains its own feeds, API/MCP registry, credentials, and deployment. Dictionary RSS/Atom publishes dictionary events only; it does not mirror Vanagon or Gerry activity.","backendStatus":"Cloudflare Workers and D1 are the only configured persistence and operational backend. The API Worker also configures Queues, R2, Workflows, and Workers AI. The Neon client, legacy docs publisher, and optional Trace/Graph/event-sink destinations were removed. Frontend data routes delegate to the canonical Cloudflare Dictionary API Worker; the legacy SQL compatibility shim fails closed. Gerry’s bounded public archive-search API remains a first-party read integration and does not store Dictionary data.","gerryContext":"The Dictionary queries Gerry’s bounded public community-search API for up to three contextual matches and links to Gerry’s full archive search. Gerry remains the sole owner of those messages; matches are not imported definitions or reviewed lexical relationships.","serviceReads":"Dictionary service reads and ordinary proxies bound the wait for headers and response bytes to 10 seconds; Gerry context reads use 6 seconds. Federated search preserves available source results and labels unavailable sources. Requests are not retried automatically. Proxy request bodies have a separate 10-second deadline (408 REQUEST_TIMEOUT before dispatch); protected snapshot dispatch retains its 60-second deadline. A timeout after dispatch does not prove a mutation was rolled back; inspect its receipt before retrying.","mcpCompatibility":"The Dictionary, Gerry, and Vanagon MCP registries are independent. Dictionary exposes stateless Streamable HTTP at /api/mcp/streamable for MCP 2026-07-28 modern clients and preserves 2025-03-26 legacy Streamable HTTP behavior on the same endpoint; both paths use the same read-only registry. Both eras passed official SDK acceptance on dictionary.ja1.io after deployment. The legacy JSON-RPC endpoints /api/mcp and /api/v1/mcp remain available (2024-11-05). Gerry and Vanagon expose their independent Streamable HTTP registries at /api/mcp. Cross-service MCP tool invocation is not configured; lexical integrations use the public Dictionary REST API and Gerry community-search API.","contributions":"Dictionary browser drafts remain local. Authenticated Gerry members can submit genuine editorial proposals through the restricted service binding. Proposals remain pending until separately reviewed and applied; receipt acceptance is not publication. Operator writes require the server-configured key.","shortDefinitions":"Canonical lexical reads include nullable short_definition from the selected definition locale. Only separately recorded, bounded text is returned; absent summaries are not generated. Protected publication, import and edits support this field. Explicit null clears it. Legacy submission notes remain private; only their recorded short text is projected. Historical originals remain immutable.","definitionHistory":"GET /api/v1/definitions/{id}/history is an operator-only, no-store read of retained definition snapshots. Older unrecorded changes are not reconstructed. Snapshots can include removed or private content and never enter public search, feeds or MCP. Optional expectedRevision on protected edits rejects stale writes without mutation. See OpenAPI for limits and coverage.","translationPolicy":"Machine-assisted drafts are not human-reviewed. Missing translations return explicitly labeled source English.","termLabels":"Canonical term detail, search, browse, category/tag and author reads include term_label: a recorded requested-locale name with an eligible definition, or explicit canonical_fallback in the origin locale. Canonical IDs, URLs and alphabetical order remain unchanged. Repeated canonical labels do not establish translation coverage; label review state is unrecorded. Differing recorded names appear alongside canonical headings. This read contract does not add editorial label writes or invent translations.","sourceReferences":"GET /api/v1/terms/{slug}/sources and MCP get_term_sources enumerate recorded public definition citations and applied source annotations. Omit locale for all definition languages; explicit locale does not substitute English. References preserve record identity and source/capture provenance, are not fetched, and do not certify technical correctness. Follow nextOffset and omitted_invalid_references; unavailable storage never substitutes seed citations."},"info":{"title":"Vanagon Dictionary API","description":"Shared lexical service for Vanagon and Gerry. Preserved Vanagon.com bus terminology and mailing-list slang, separately sourced contemporary parts references, and clearly labeled machine-assisted translations. Dictionary feeds, REST and MCP remain independently addressed. Gerry community-search matches provide contextual links and do not become dictionary records. Missing translations return explicitly labeled source English; operator writes require server-side authorization. Dictionary service reads and ordinary proxies bound the wait for headers and response bytes to 10 seconds; Gerry context reads use 6 seconds. Federated search preserves available source results and labels unavailable sources. Requests are not retried automatically. Proxy request bodies have a separate 10-second deadline (408 REQUEST_TIMEOUT before dispatch); protected snapshot dispatch retains its 60-second deadline. A timeout after dispatch does not prove a mutation was rolled back; inspect its receipt before retrying.","version":"1.0.0","contact":{"name":"Vanagon community","url":"https://vanagon.com"}},"servers":[{"url":"https://dictionary.vanagon.com","description":"Vanagon Dictionary Cloudflare production Worker on dictionary.ja1.io; dictionary.vanagon.com is a separate, unconfigured hostname"}],"paths":{"/api/health":{"get":{"summary":"Health check","description":"Returns service health status and database connectivity","operationId":"getHealth","tags":["System"],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/v1/health":{"get":{"summary":"Health check (v1 alias)","description":"Alias for /api/health with the same response shape","operationId":"getHealthV1","tags":["System"],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/v1/terms":{"get":{"summary":"List terms","description":"Get paginated dictionary terms and their actual published definition locales; a selected definition may still use English when the requested locale is unavailable.","operationId":"listTerms","tags":["Terms"],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"Weak public-data ETag, a quoted validator list, or *. Anonymous GET only; per-request envelope timestamps/trace IDs do not change the weak validator.","schema":{"type":"string"}},{"name":"page","in":"query","description":"Used only when offset is absent; offset is (page - 1) times the capped limit.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"offset","in":"query","description":"Explicit zero-based offset takes precedence over page.","schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"locale","in":"query","schema":{"type":"string","default":"en"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["recent","popular","alphabetical"]}}],"responses":{"200":{"headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}},"description":"List of terms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermsListResponse"}}}},"304":{"description":"Current public data matches If-None-Match; body is empty. Request correlation headers are fresh. Storage is still read and failures are never converted to 304.","headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}}},"400":{"description":"Invalid pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}}}},"post":{"summary":"Create or retrieve a term while submitting a definition","description":"Protected alias for definition submission. The canonical term ID is read back from Dictionary storage and publication is asynchronous.","operationId":"createTerm","tags":["Terms"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDefinitionRequest"}}}},"responses":{"202":{"description":"Definition accepted with durable publication status and canonical IDs"},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/api/v1/ingest":{"post":{"summary":"Bulk ingest terms","description":"Protected bulk import for up to 1000 source terms. Each new definition, audit row, aliases, and publication outbox intent are stored atomically before queue delivery. Typed items reject malformed fields before D1 access and report INVALID_INGEST_ITEM with field names; other valid items continue. Malformed known fields, unsupported locales and dryRun/publication flags are rejected rather than coerced or ignored. Other undeclared legacy fields remain ignored for compatibility. source_url takes precedence over the legacy source alias. short_definition is optional, nullable and bounded; it takes precedence over metadata.short_definition. Duplicate definitions remain unchanged.","operationId":"bulkIngest","tags":["Terms"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkIngestRequest"}}}},"responses":{"200":{"description":"Batch processed with skipped or failed items; inspect result counts and errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkIngestResponse"}}}},"201":{"description":"Bulk ingest processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkIngestResponse"}}}},"400":{"description":"Validation error"},"401":{"description":"Operator authorization required"},"413":{"description":"Request exceeds the 1 MiB body limit"}}}},"/api/submit":{"post":{"summary":"Protected legacy submission adapter","description":"Accepts shortDefinition/fullDefinition, examples, sourceUrls, aliases, tags and class through the canonical publication service. dryRun=true validates without D1 reads/writes, publication or translation work. Descriptive relatedTerms are retained as notes, not approved lexical relations. submitterContact is not stored. Existing record provenance remains creation-only.","operationId":"submitLegacyDefinition","tags":["Definitions"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyDefinitionRequest"}}}},"responses":{"200":{"description":"Validated dry run; persisted=false, publicationStatus=not_requested"},"202":{"description":"Publication intent accepted with canonical persisted IDs"},"400":{"description":"Invalid bounded legacy input"},"401":{"description":"Operator authorization required"}}}},"/api/v1/definitions":{"post":{"summary":"Submit and publish a definition","description":"Protected Dictionary submission stored with a durable publication outbox event. The response distinguishes accepted state from asynchronous publication status and returns persisted canonical IDs. New records retain source/example and category/tag/phonetic/part-of-speech fields. Existing term attributes and duplicate definition provenance are preserved, with explicit storage booleans and warnings; use editorial proposals for changes. This protected operator publication API does not replace moderated contributions or request translations. dryRun=true validates without D1 access or publication work.","operationId":"submitDefinition","tags":["Definitions"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDefinitionRequest"}}}},"responses":{"200":{"description":"Validated dry run; no D1 access, publication or translation work"},"202":{"description":"Definition and publication intent persisted; publication status is included"},"400":{"description":"Validation error"},"401":{"description":"PLATPHORM_API_KEY required"},"408":{"description":"REQUEST_TIMEOUT: proxy request body exceeded its 10-second deadline before dispatch; no-store","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"const":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"const":"REQUEST_TIMEOUT"},"message":{"type":"string"}}}}}}}},"409":{"description":"Canonical slug or locale-scoped alias belongs to a different term"},"503":{"description":"Dictionary storage or service unavailable; no-store. After dispatch the write outcome may be unknown; inspect the canonical receipt before retrying."}}}},"/api/v1/terms/{slug}":{"get":{"summary":"Get term details","description":"Get a term with its available definitions, requested/returned locale, and locale-scoped aliases. Exact canonical URLs take precedence, then requested-locale aliases, then English. Legacy preserved alias labels and native-script/symbol slugs resolve without rewriting source rows. Alias requests return the canonical slug; ambiguous identities return 409.","operationId":"getTerm","tags":["Terms"],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"Weak public-data ETag, a quoted validator list, or *. Anonymous GET only; per-request envelope timestamps/trace IDs do not change the weak validator.","schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string","default":"en"}}],"responses":{"200":{"headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}},"description":"Term details, canonical slug, and locale-scoped aliases","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermDetailResponse"}}}},"304":{"description":"Current public data matches If-None-Match; body is empty. Request correlation headers are fresh. Storage is still read and failures are never converted to 304.","headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}}},"404":{"description":"Term not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"409":{"description":"TERM_ALIAS_AMBIGUOUS: more than one public term owns the alias in the preferred locale. Use a canonical URL; no identities were merged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"503":{"description":"TERM_ALIAS_LOOKUP_LIMIT: public alias inventory exceeds 10000 rows. No partial match is returned. Errors are no-store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}}}}},"/api/v1/terms/{slug}/sources":{"get":{"summary":"List recorded public source references for a term","operationId":"listTermSources","tags":["Terms"],"description":"Reads approved definition source_url citations and applied source annotations. Omitted locale includes all definition languages; an explicit locale selects exact citations without fallback, plus language-independent annotations. Each record keeps its own identity even when URLs repeat. Original URLs/captures/hashes are preserved when recorded. References are not fetched or certified. Pagination scans eligible records in kind/ID order, omits invalid URLs with an explicit count, and advances nextOffset by scanned records even on an empty page. Concurrent changes can shift offset pages; this is not a point-in-time export.","parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"Weak public-data ETag, a quoted validator list, or *. Anonymous GET only; per-request envelope timestamps/trace IDs do not change the weak validator.","schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","description":"Optional exact supported locale; also used for alias resolution. Omit for all definition languages.","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}}],"responses":{"200":{"headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}},"description":"Public recorded references and bounded pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermSourcesResponse"}}}},"304":{"description":"Current public data matches If-None-Match; body is empty. Request correlation headers are fresh. Storage is still read and failures are never converted to 304.","headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}}},"400":{"description":"Invalid or duplicate pagination/locale selectors"},"404":{"description":"Public term not found"},"409":{"description":"TERM_ALIAS_AMBIGUOUS: more than one public term owns the alias in the preferred locale. Use a canonical URL; no identities were merged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"503":{"description":"Canonical storage unavailable; no seed citations are substituted"}}}},"/api/v1/terms/{slug}/translations":{"get":{"summary":"List public translation and review states for a term","description":"Reads approved definition locales and allowlisted provenance from the canonical Dictionary D1 store. Historical source wording, machine-assisted drafts, recorded human review, and unrecorded review state are distinguished; pending definitions are excluded.","operationId":"listTermTranslations","tags":["Translations"],"parameters":[{"name":"locale","in":"query","description":"Alias lookup locale, falling back to English; translation listing still includes all published locales.","schema":{"type":"string","default":"en"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Published locales with translation provenance and review state"},"404":{"description":"Published term not found"},"409":{"description":"TERM_ALIAS_AMBIGUOUS: more than one public term owns the alias in the preferred locale. Use a canonical URL; no identities were merged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"503":{"description":"TERM_ALIAS_LOOKUP_LIMIT: public alias inventory exceeds 10000 rows. No partial match is returned. Errors are no-store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}}}}},"/api/v1/terms/{slug}/related":{"get":{"summary":"List related public terms","description":"Returns approved terms ranked from applied editorial relationships, shared public tags, and shared categories. Definition previews use the requested locale or explicitly report the English fallback locale; no semantic relationship is fabricated.","operationId":"getRelatedTerms","tags":["Terms"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string","default":"en"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"minimum":1,"maximum":25}}],"responses":{"200":{"description":"Source-attributed deterministic lexical relationships"},"400":{"description":"Invalid result limit"},"409":{"description":"TERM_ALIAS_AMBIGUOUS: more than one public term owns the alias in the preferred locale. Use a canonical URL; no identities were merged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"503":{"description":"TERM_ALIAS_LOOKUP_LIMIT: public alias inventory exceeds 10000 rows. No partial match is returned. Errors are no-store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}}}}},"/api/v1/export/{format}":{"get":{"summary":"Export dictionary definitions","description":"Returns JSON, Markdown, ASCII text, or USL for a bounded locale window. Set slug to resolve exactly one term through the canonical term API, independent of list pagination; all formats preserve requested/definition locale, source fallback and recorded review metadata. Unavailable vote fields are null in JSON/USL and explicitly unavailable in text, never synthesized zero counts; if that term has no requested-locale definition, English is used when available.","operationId":"exportDefinitions","tags":["Definitions"],"parameters":[{"name":"format","in":"path","required":true,"schema":{"type":"string","enum":["json","markdown","ascii","usl"]}},{"name":"locale","in":"query","schema":{"type":"string","default":"en"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}},{"name":"slug","in":"query","schema":{"type":"string"},"description":"Export this canonical term or alias only."}],"responses":{"200":{"description":"Format-specific definition output"},"400":{"description":"Unsupported format"},"503":{"description":"Cloudflare Dictionary service unavailable"}}}},"/api/v1/terms/random":{"get":{"summary":"Get random term","description":"Get a random approved term","operationId":"getRandomTerm","tags":["Terms"],"parameters":[{"name":"locale","in":"query","schema":{"type":"string","default":"en"}}],"responses":{"200":{"description":"Random term"}}}},"/api/v1/search/federated":{"get":{"summary":"Read a bounded Dictionary and Gerry search window","operationId":"searchVanagonFederation","description":"Versioned vanagon.search-federation.v1 response. Fixed leaf APIs only; up to 10 lexical and 3 community results. Concurrent source reads bound headers and body waits to 10 seconds for Dictionary and 6 seconds for Gerry, with no retries. A stalled source is unavailable; the other source retains its results. Independent Vanagon website search is currently unsupported. Independent bounded source pagination; no cross-site writes or merged ranking.","parameters":[{"name":"dictionaryOffset","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}},{"name":"gerryPage","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1}},{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"locale","in":"query","schema":{"type":"string","default":"en"}}],"responses":{"200":{"description":"Source-attributed search windows; inspect availability and degraded state"},"400":{"description":"Invalid or duplicate query selectors"},"503":{"description":"Feature disabled"}}}},"/api/v1/search":{"get":{"summary":"Search terms","description":"Cloudflare full-text prefix search with optional category, tag, provenance-corpus, model, year, and technical-system filters. When a single-token query has no exact results, the response may include up to three explicit one-edit spelling suggestions drawn from approved canonical terms and locale-eligible aliases; the query is never rewritten.","operationId":"searchTerms","tags":["Search"],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"Weak public-data ETag, a quoted validator list, or *. Anonymous GET only; per-request envelope timestamps/trace IDs do not change the weak validator.","schema":{"type":"string"}},{"name":"page","in":"query","description":"Compatibility page selector, used only when offset is absent. Offset is (page - 1) times the capped limit.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"category","in":"query","description":"Case-insensitive exact category filter","schema":{"type":"string","maxLength":200}},{"name":"tag","in":"query","description":"Case-insensitive exact tag filter","schema":{"type":"string","maxLength":200}},{"name":"corpus","in":"query","description":"Exact provenance corpus identifier; combines with other filters using AND","schema":{"type":"string","maxLength":200}},{"name":"model","in":"query","description":"Latest applied sourced vehicle scope, otherwise vehicle_models metadata or literal model_scope substring; not a fitment guarantee","schema":{"type":"string","maxLength":100}},{"name":"year","in":"query","description":"Exact explicit years in the latest applied sourced vehicle scope, otherwise model_years metadata; missing assignments do not match","schema":{"type":"integer","minimum":1900,"maximum":2199}},{"name":"system","in":"query","description":"Case-insensitive exact technical system in the same latest applied scope as model/year, otherwise explicit technical_systems metadata; never inferred from tags or dates","schema":{"type":"string","maxLength":100}},{"name":"locale","in":"query","schema":{"type":"string","default":"en"}},{"name":"offset","in":"query","description":"Explicit zero-based offset takes precedence over page.","schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}},"description":"Search results, pagination, original query, and up to three explicit spelling suggestions when an eligible single-token query has no exact result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"304":{"description":"Current public data matches If-None-Match; body is empty. Request correlation headers are fresh. Storage is still read and failures are never converted to 304.","headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}}},"400":{"description":"Invalid query selectors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}}}}},"/api/v1/recent":{"get":{"summary":"List recent terms","description":"Return recent approved public Dictionary terms. Test junk and private moderation data are excluded.","operationId":"listRecentTerms","tags":["Terms"],"parameters":[{"name":"locale","in":"query","schema":{"type":"string","default":"en"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50}}],"responses":{"200":{"description":"Recent approved terms"}}}},"/api/v1/popular":{"get":{"summary":"List popular terms","description":"Return popular approved public Dictionary terms computed from real votes, views, and approved definition counts.","operationId":"listPopularTerms","tags":["Terms"],"parameters":[{"name":"locale","in":"query","schema":{"type":"string","default":"en"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50}}],"responses":{"200":{"description":"Popular approved terms"}}}},"/api/v1/activity":{"post":{"summary":"Record anonymous displayed dictionary activity","description":"Restricted same-origin browser telemetry, not a contributor mutation. Records one view term or up to ten displayed search matches, once per tab/term/kind/UTC hour, at most 60 signals per tab/hour, plus an approximate Cloudflare limit of 30 activity requests per minute per daily-hashed tab ID. Requires application/json, approved Dictionary Origin and Sec-Fetch-Site: same-origin. Known bots, prefetch, DNT and GPC are rejected. No raw queries, IPs or raw session IDs are persisted. Tab IDs rotate for hashing daily; deduplication receipts expire after 48 hours. Anonymous counts are not verified unique people.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","session","termIds"],"properties":{"kind":{"type":"string","enum":["view","search"]},"session":{"type":"string","format":"uuid"},"termIds":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","maxLength":200}}}}}}},"responses":{"202":{"description":"Recorded count (zero for duplicates, ineligible terms, or capped activity)"},"400":{"description":"Invalid activity"},"403":{"description":"Browser/origin/privacy checks rejected activity"},"413":{"description":"Body exceeds 4096 bytes"},"429":{"description":"Activity rate limit exceeded"},"503":{"description":"Activity storage unavailable"}}}},"/api/v1/trending":{"get":{"summary":"List trending terms","description":"Rank approved terms by the sum of deduplicated displayed term views, first-page search-result matches, and recorded votes. Each signal has weight one; activity windows use UTC hour buckets. No imported counters or fabricated freshness scores are used.","operationId":"listTrendingTerms","tags":["Terms"],"parameters":[{"name":"locale","in":"query","schema":{"type":"string","default":"en"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50}},{"name":"days","in":"query","schema":{"type":"integer","default":14,"maximum":90}}],"responses":{"200":{"description":"Trending approved terms"}}}},"/api/v1/categories":{"get":{"summary":"List categories","description":"Return public Dictionary category counts from approved terms.","operationId":"listCategories","tags":["Terms"],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"Weak public-data ETag, a quoted validator list, or *. Anonymous GET only; per-request envelope timestamps/trace IDs do not change the weak validator.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}},"description":"Public categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoriesResponse"}}}},"304":{"description":"Current public data matches If-None-Match; body is empty. Request correlation headers are fresh. Storage is still read and failures are never converted to 304.","headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}}},"400":{"description":"Invalid query selectors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}}}}},"/api/v1/categories/{slug}":{"get":{"summary":"Get category terms","description":"Resolve emitted category slugs using the shared Unicode/symbol normalizer while retaining legacy space-only spellings and original labels. Unknown facets return an empty terms window. Lookup reads at most 10,001 distinct public labels and returns an uncached 503 if the 10,000-label inventory budget is exceeded, never a partial match.","operationId":"getCategory","tags":["Terms"],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"Weak public-data ETag, a quoted validator list, or *. Anonymous GET only; per-request envelope timestamps/trace IDs do not change the weak validator.","schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string","default":"en"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}},"description":"Category terms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacetTermsResponse"}}}},"304":{"description":"Current public data matches If-None-Match; body is empty. Request correlation headers are fresh. Storage is still read and failures are never converted to 304.","headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}}},"400":{"description":"Invalid result limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"503":{"description":"Storage unavailable or FACET_LOOKUP_LIMIT; no partial match is returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}}}}},"/api/v1/tags":{"get":{"summary":"List tags","description":"Return public Dictionary tag counts from approved terms.","operationId":"listTags","tags":["Terms"],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"Weak public-data ETag, a quoted validator list, or *. Anonymous GET only; per-request envelope timestamps/trace IDs do not change the weak validator.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}},"description":"Public tags","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagsResponse"}}}},"304":{"description":"Current public data matches If-None-Match; body is empty. Request correlation headers are fresh. Storage is still read and failures are never converted to 304.","headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}}},"400":{"description":"Invalid query selectors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}}}}},"/api/v1/tags/{slug}":{"get":{"summary":"Get tag terms","description":"Resolve emitted tag slugs using the shared Unicode/symbol normalizer while retaining legacy space-only spellings and original labels. Unknown facets return an empty terms window. Lookup reads at most 10,001 distinct public labels and returns an uncached 503 if the 10,000-label inventory budget is exceeded, never a partial match.","operationId":"getTag","tags":["Terms"],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"Weak public-data ETag, a quoted validator list, or *. Anonymous GET only; per-request envelope timestamps/trace IDs do not change the weak validator.","schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string","default":"en"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}},"description":"Tag terms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacetTermsResponse"}}}},"304":{"description":"Current public data matches If-None-Match; body is empty. Request correlation headers are fresh. Storage is still read and failures are never converted to 304.","headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}}},"400":{"description":"Invalid result limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"503":{"description":"Storage unavailable or FACET_LOOKUP_LIMIT; no partial match is returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}}}}},"/api/v1/authors/{handle}":{"get":{"summary":"List public author definitions","operationId":"listAuthorDefinitions","tags":["Terms"],"description":"Approved definitions attributed to a handle. Returns definitions, count and pagination (limit, offset, hasMore, nextOffset). Requested-locale and English records identify requested_locale, returned_locale and is_fallback; allowlisted metadata describes translation review state. No private author profile is returned. Follow nextOffset until null; count is this page's count, not an author total.","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string","default":"en"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Public author definition page with explicit continuation metadata"},"400":{"description":"Invalid pagination"},"503":{"description":"Dictionary service unavailable"}}}},"/api/v1/locales/{locale}":{"get":{"summary":"Get a public locale summary","operationId":"getLocaleSummary","tags":["Terms"],"description":"Uses the same public eligibility and recorded provenance counts as the locale list; it does not infer review state from language or approval.","parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"Weak public-data ETag, a quoted validator list, or *. Anonymous GET only; per-request envelope timestamps/trace IDs do not change the weak validator.","schema":{"type":"string"}},{"name":"locale","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}},"description":"Public locale summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocaleResponse"}}}},"304":{"description":"Current public data matches If-None-Match; body is empty. Request correlation headers are fresh. Storage is still read and failures are never converted to 304.","headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}}},"404":{"description":"Unsupported locale","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}}}}},"/api/v1/locales":{"get":{"summary":"List locales","description":"Return public-only definition counts and recorded review-state counts per locale. Hidden/deleted terms and pending/deleted definitions are excluded. Localization can be mixed; English or approval alone does not establish historical source or human review.","operationId":"listLocales","tags":["Terms"],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"Weak public-data ETag, a quoted validator list, or *. Anonymous GET only; per-request envelope timestamps/trace IDs do not change the weak validator.","schema":{"type":"string"}}],"responses":{"200":{"headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}},"description":"Locale registry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalesResponse"}}}},"304":{"description":"Current public data matches If-None-Match; body is empty. Request correlation headers are fresh. Storage is still read and failures are never converted to 304.","headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}}}}}},"/api/v1/stats":{"get":{"summary":"Dictionary stats","description":"Return public eligible term/definition/author/vote/locale/facet totals from one D1 read. Anonymous pendingTerms/pendingDefinitions are null with moderationCounts=protected. Valid operator credentials include moderation counts; invalid supplied credentials return 401. All responses are no-store and vary by authorization. No private counts are represented as zero.","operationId":"getStats","security":[{},{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"tags":["System"],"responses":{"200":{"description":"Scope-aware Dictionary statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"401":{"description":"Invalid supplied operator credentials"}}}},"/api/v1/events":{"get":{"summary":"List published definition events","description":"Public bounded feed of completed publication events. Historical archive imports and machine-assisted drafts are excluded; event times describe publication processing, not original historical authorship or creation.","operationId":"listPublishedDefinitionEvents","tags":["Events"],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"Weak public-data ETag, a quoted validator list, or *. Anonymous GET only; per-request envelope timestamps/trace IDs do not change the weak validator.","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}},"description":"Completed published definition events with stable event IDs and timestamps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsResponse"}}}},"304":{"description":"Current public data matches If-None-Match; body is empty. Request correlation headers are fresh. Storage is still read and failures are never converted to 304.","headers":{"ETag":{"description":"Weak SHA-256 validator for the current public data projection","schema":{"type":"string"}},"Cache-Control":{"description":"private, no-cache: client revalidation required; no shared edge cache. Credential-bearing canonical requests use private, no-store and no ETag.","schema":{"type":"string"}}}},"400":{"description":"Invalid query selectors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}}}}},"/api/collections":{"get":{"summary":"List generated collections","description":"Return optional public Dictionary collections generated from approved term classes/categories and tags. Collections are source-labeled and are not presented as editorial curated collections.","operationId":"listCollections","tags":["Collections"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":200}}],"responses":{"200":{"description":"Generated public collections"}}}},"/api/collections/{slug}":{"get":{"summary":"Get generated collection","description":"Return one generated public Dictionary collection by slug, including source label, term count, and sample term links.","operationId":"getCollection","tags":["Collections"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Generated public collection"},"404":{"description":"Collection not found"}}}},"/api/datasets/dictionary":{"get":{"summary":"Get Dictionary dataset","description":"Return the approved public-safe Dictionary definitions dataset. Private moderation notes, raw IPs, raw user agents, raw JA4 fingerprint digest values, rejected definitions, private reports, and secrets are excluded.","operationId":"getDictionaryDataset","tags":["Datasets"],"responses":{"200":{"description":"Dictionary dataset export metadata and records"}}}},"/api/datasets/dictionary/exports":{"get":{"summary":"List Dictionary dataset exports","description":"Return public export URLs for JSON, JSONL, CSV, graph JSON, and LLMS index downloads.","operationId":"listDictionaryDatasetExports","tags":["Datasets"],"responses":{"200":{"description":"Dictionary dataset export links"}}}},"/api/web/status":{"get":{"summary":"Get Web Status","description":"Return web.status.v1 source-backed counts and verification coverage. Route readiness is unverified unless backed by a live check. Search Console is not configured; no issue counts are asserted. /api/web4/status is a backward-compatible alias only.","operationId":"getWebStatus","tags":["Web Status"],"responses":{"200":{"description":"Web Status"}}}},"/api/web/scorecard":{"get":{"summary":"Get Web scorecard","description":"Return a public scorecard that awards points only for measured evidence. Declared routes without live checks are unverified and contribute no points; incomplete runtime coverage is explicitly classified. /api/web4/scorecard is a backward-compatible alias.","operationId":"getWebScorecard","tags":["Web Status"],"responses":{"200":{"description":"Web scorecard"}}}},"/graph.json":{"get":{"summary":"Get Dictionary graph","description":"Return public-safe Dictionary graph nodes and edges generated from approved records.","operationId":"getDictionaryGraph","tags":["Graph"],"responses":{"200":{"description":"Dictionary graph"}}}},"/api/v1/agent-policy":{"get":{"summary":"Get agent policy","description":"Return the public-safe Dictionary agent access policy and versioned agent platform registry.","operationId":"getAgentPolicy","tags":["Agent Policy"],"responses":{"200":{"description":"Agent policy"}}}},"/api/v1/agent-policy/platforms":{"get":{"summary":"List agent platforms","description":"Return known crawler, AI, MCP, browser-agent, and generic crawler policy entries with source labels and verification status.","operationId":"listAgentPlatforms","tags":["Agent Policy"],"responses":{"200":{"description":"Agent platform registry"}}}},"/api/v1/agent-policy/platforms/{id}":{"get":{"summary":"Get agent platform","description":"Return a single source-labeled agent platform policy entry.","operationId":"getAgentPlatform","tags":["Agent Policy"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Agent platform"},"404":{"description":"Platform not found"}}}},"/api/v1/agent-policy/robots":{"get":{"summary":"Get robots policy","description":"Return robots.txt generated from the canonical agent policy.","operationId":"getRobotsPolicy","tags":["Agent Policy"],"responses":{"200":{"description":"robots.txt policy"}}}},"/api/v1/agent-policy/summary":{"get":{"summary":"Get agent policy summary","description":"Return a compact public/protected access summary.","operationId":"getAgentPolicySummary","tags":["Agent Policy"],"responses":{"200":{"description":"Agent policy summary"}}}},"/api/v1/agent-policy/evaluate":{"post":{"summary":"Evaluate agent access","description":"Bounded public-safe policy evaluator for a path, method, and optional platform id.","operationId":"evaluateAgentAccess","tags":["Agent Policy"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path"],"properties":{"path":{"type":"string"},"method":{"type":"string","default":"GET"},"platformId":{"type":"string"}}}}}},"responses":{"200":{"description":"Policy decision"},"400":{"description":"Validation error"}}}},"/api/mcp":{"get":{"summary":"MCP metadata","description":"Return public MCP server metadata and usage details.","operationId":"getMcpMetadata","tags":["MCP"],"responses":{"200":{"description":"MCP metadata"}}},"post":{"summary":"MCP JSON-RPC endpoint","description":"Accept JSON-RPC 2.0 requests or batches. MCP tools are read-only; dictionary mutations remain on separately protected REST routes. DICTIONARY_FEATURE_MCP can disable both metadata and calls with an explicit unavailable response.","operationId":"callMcp","tags":["MCP"],"responses":{"200":{"description":"JSON-RPC response"},"400":{"description":"Parse error"},"503":{"description":"MCP service disabled by feature switch"}}}},"/api/mcp/streamable":{"post":{"summary":"Dictionary MCP Streamable HTTP","description":"Stateless MCP Streamable HTTP endpoint supporting MCP 2026-07-28 modern discovery/envelopes and backward-compatible 2025-03-26 requests. Modern requests use server/discover and per-request _meta; legacy-era requests retain bounded batches, JSON+SSE Accept requirements, empty 202 notifications and GET 405. Request bodies are capped at 1 MiB. Both protocol eras use the same read-only registry; /api/mcp and /api/v1/mcp remain legacy JSON-RPC routes.","operationId":"callDictionaryMcpStreamable","tags":["MCP"],"responses":{"200":{"description":"JSON-RPC response"},"202":{"description":"Notification accepted"},"400":{"description":"Invalid JSON-RPC request"},"403":{"description":"Origin rejected"},"406":{"description":"Required Accept media types missing"},"413":{"description":"Request body exceeds limit"},"415":{"description":"Unsupported content type"},"503":{"description":"MCP service disabled by feature switch"}}}},"/.well-known/agents.json":{"get":{"summary":"Agents manifest","description":"Public-safe AI agent and automation interaction manifest.","operationId":"getAgentsManifest","tags":["Discovery"],"responses":{"200":{"description":"Agents manifest"}}}},"/.well-known/agent-policy.json":{"get":{"summary":"Agent policy","description":"Operational allow policy for AI agents, crawlers, fetchers, and MCP/API clients.","operationId":"getWellKnownAgentPolicy","tags":["Discovery"],"responses":{"200":{"description":"Agent policy"}}}},"/.well-known/ai-policy.json":{"get":{"summary":"AI policy","description":"Public content use, citation, training, search, answer engine, and protected-action policy for AI platforms.","operationId":"getAiPolicy","tags":["Discovery"],"responses":{"200":{"description":"AI policy"}}}},"/.well-known/trust.json":{"get":{"summary":"Trust policy","description":"Dictionary trust posture including PLATPHORM_API_KEY, trace, JA4, Cloudflare metadata, redaction, and discovery policy.","operationId":"getTrustPolicy","tags":["Discovery"],"responses":{"200":{"description":"Trust policy"}}}},"/api/v1/definitions/{id}/vote":{"post":{"summary":"Vote on a definition","description":"Protected upvote, downvote, or removal of the caller's vote using a privacy-preserving fingerprint","operationId":"voteDefinition","tags":["Definitions"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"voteType":{"type":"string","enum":["up","down",null]}}}}}},"responses":{"200":{"description":"Vote recorded"}}}},"/api/v1/proposals":{"get":{"summary":"Read the protected editorial proposal inbox","security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","accepted","rejected","applied"],"default":"pending"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Private proposal records; no-store"},"401":{"description":"Operator key required"}}},"post":{"summary":"Create a pending editorial proposal","description":"Strict contribution kinds: new_term, correction, translation, alias, source, category, related_term. Source proposals may include vehicleScope with explicit vehicleModels, modelYears, technicalSystems, sourceLocator and scopeNote. Fields are validated per kind. Proposals do not change canonical records or publish. Attribution is operator-supplied and unverified. See the editorial proposal contract.","security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"X-Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditorialProposalInput"}}}},"responses":{"200":{"description":"Existing proposal receipt replayed; publication progress is not checked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalSubmissionResponse"}}}},"202":{"description":"Pending proposal persisted; not applied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalSubmissionResponse"}}}},"400":{"description":"Invalid kind-specific fields"},"401":{"description":"Operator key required"},"404":{"description":"Target is not a published term"},"409":{"description":"Idempotency content conflict"},"413":{"description":"Proposal body exceeds 16384 bytes"},"429":{"description":"Pending inbox capacity reached"},"503":{"description":"Storage unavailable; write outcome requires receipt readback"}}}},"/api/v1/proposals/{id}":{"get":{"summary":"Read a protected proposal and recorded review","security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Private proposal and review; no-store"},"401":{"description":"Operator key required"},"404":{"description":"Proposal not found"}}}},"/api/v1/proposals/{id}/plan":{"get":{"summary":"Inspect a protected read-only proposal application plan","description":"Validates stored proposal content and identifies preservation requirements. The plan is explicitly non-executable and does not publish or apply changes.","security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Versioned read-only plan; no-store"},"401":{"description":"Operator key required"},"404":{"description":"Proposal not found"},"409":{"description":"Stored proposal or target is unavailable"}}}},"/api/v1/proposals/{id}/apply":{"post":{"summary":"Apply an accepted proposal atomically","description":"Requires confirm:true. Writes lexical changes, receipt, final state, and durable indexing intent together. Repeated application replays its receipt. Historical definitions are never overwritten; historical categories use annotations.","security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirm"],"additionalProperties":false,"properties":{"confirm":{"const":true}}}}}},"responses":{"200":{"description":"Applied or replayed; inspect publicationStatus"},"202":{"description":"Applied with durable publication/indexing intent pending"},"400":{"description":"Explicit confirmation required"},"401":{"description":"Operator key required"},"409":{"description":"Proposal, target, or application state conflict"},"503":{"description":"Application outcome unavailable; re-read before retry"}}}},"/api/v1/terms/{slug}/annotations":{"get":{"summary":"Read applied public editorial annotations","description":"Explicit projections of applied source/category/relation annotations only. Private proposal reasons, attribution and review records are excluded; unpublished related targets are omitted.","parameters":[{"name":"locale","in":"query","description":"Alias lookup locale, falling back to English; translation listing still includes all published locales.","schema":{"type":"string","default":"en"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Applied public annotations"},"404":{"description":"Published term not found"},"409":{"description":"TERM_ALIAS_AMBIGUOUS: more than one public term owns the alias in the preferred locale. Use a canonical URL; no identities were merged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"503":{"description":"TERM_ALIAS_LOOKUP_LIMIT: public alias inventory exceeds 10000 rows. No partial match is returned. Errors are no-store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}}}}},"/api/v1/proposals/{id}/review":{"post":{"summary":"Record a protected proposal review decision","description":"Accepted means ready for a separate application workflow; it does not publish or alter lexical records.","security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision","reason"],"properties":{"decision":{"type":"string","enum":["accepted","rejected"]},"reason":{"type":"string","minLength":10,"maxLength":2000}}}}}},"responses":{"200":{"description":"Decision persisted; canonical records unchanged"},"401":{"description":"Operator key required"},"409":{"description":"Proposal missing or already reviewed"}}}},"/api/v1/definitions/{id}":{"patch":{"summary":"Edit a definition","description":"Protected edit of approved modern definition content. Preserved historical English source records require separate annotations and reject overwrites. Optional expectedRevision checks the current history head atomically; null requires no recorded history. A conflict writes nothing. Omitting it preserves legacy edit behavior. At least one editable field is required; text is trimmed, source URLs must be HTTP(S) without credentials. short_definition is separately recorded text; null clears it without reviving legacy short text. Revisions, edit audit and publication intent commit together.","operationId":"editDefinition","tags":["Definitions"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"definition":{"type":"string","minLength":20,"maxLength":2000},"short_definition":{"type":["string","null"],"minLength":10,"maxLength":300,"description":"Separately recorded short definition in the selected definition locale; null means absent. Trimmed on write. Explicit null clears it without restoring legacy text."},"example_usage":{"type":["string","null"],"maxLength":2000},"source_url":{"type":["string","null"],"maxLength":2000,"description":"HTTP(S) attribution URL without credentials; empty text clears the reference"},"expectedRevision":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Definition updated"},"401":{"description":"PLATPHORM_API_KEY required"},"409":{"description":"HISTORICAL_SOURCE_IMMUTABLE or REVISION_CONFLICT; read history before retrying"}}}},"/api/v1/definitions/{id}/history":{"get":{"summary":"Read protected definition revision history","description":"Operator-only retained snapshots, including private or removed content; no-store, never public MCP/feed/search data. Default 20, at most 50 revisions descending; values above 50 are clamped. before is an exclusive positive safe-integer revision cursor. Unknown/duplicate query parameters are rejected. The history head and currentRecordPresent reflect the initial summary read; subsequent appends do not enter that page. Snapshots are immutable; audit links are observed separately. Older content before migration is not reconstructed: an existing record has no history until its first actual tracked change, which records baseline and update. recordedAt is observation time, not original authorship. operatorActions links edits/moderation only; platform-operator is a role, not personal attribution. Votes and timestamp-only changes are excluded. The 512 KiB snapshot budget and 100 action-reference budget fail explicitly; request fewer rows or use protected recovery exports.","operationId":"getDefinitionHistory","tags":["Definitions"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"before","in":"query","schema":{"type":"integer","minimum":1,"maximum":9007199254740991}}],"responses":{"200":{"description":"Protected history; priorHistoryReconstructed is always false","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefinitionHistoryResponse"}}}},"400":{"description":"Invalid query"},"401":{"description":"Operator key required"},"404":{"description":"Neither current definition nor retained history exists"},"503":{"description":"HISTORY_READ_LIMIT or storage unavailable; no partial history returned"}}}},"/api/v1/definitions/{id}/removal-requests":{"post":{"summary":"Request removal of a definition","description":"Queue a protected removal request for operator review; this does not remove content","operationId":"requestDefinitionRemoval","tags":["Definitions","Moderation"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":10,"maxLength":1000}}}}}},"responses":{"202":{"description":"Removal request queued for approval"}}}},"/api/v1/exports/snapshot":{"post":{"summary":"Create a protected operational snapshot","description":"Requires PLATPHORM_API_KEY. Creates a unique private R2 export with conditional SHA-256-checked JSONL writes and the completion manifest written last. Limits: 50000 rows, 256 chunks, 2097152 bytes per chunk, 67108864 total data bytes, and 50 seconds. The dedicated proxy deadline is 60 seconds. No-store on both boundaries. Returns the manifest, storage key and manifest hash. Sequential table reads are not a cross-table point-in-time backup; derived search and migration bookkeeping are excluded. On failure, retained objects may be incomplete and an in-flight write may still finish; inspect the returned manifest key before retrying. No automatic deletion or replay.","operationId":"createOperationalSnapshot","tags":["Operations"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"responses":{"201":{"description":"Private R2 snapshot manifest created","content":{"application/json":{"schema":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"const":true},"error":{"type":"null"},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"data":{"type":"object","additionalProperties":false,"required":["schema","snapshotId","createdAt","startedAt","consistency","files","totals","manifestKey","manifestSha256"],"properties":{"schema":{"const":"platphorm.dictionary.r2-snapshot.v1"},"snapshotId":{"type":"string","pattern":"^dictionary-"},"createdAt":{"type":"string","format":"date-time"},"startedAt":{"type":"string","format":"date-time"},"consistency":{"const":"sequential_table_reads"},"manifestKey":{"type":"string","pattern":"^snapshots/.+/manifest\\.json$"},"manifestSha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"files":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["rows","chunks"],"properties":{"rows":{"type":"integer","minimum":0,"maximum":50000},"chunks":{"type":"array","maxItems":256,"items":{"type":"object","additionalProperties":false,"required":["key","rows","bytes","sha256"],"properties":{"key":{"type":"string","pattern":"^snapshots/"},"rows":{"type":"integer","minimum":0,"maximum":500},"bytes":{"type":"integer","minimum":0,"maximum":2097152},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"}}}}}}},"totals":{"type":"object","additionalProperties":false,"required":["rows","chunks","bytes"],"properties":{"rows":{"type":"integer","minimum":0,"maximum":50000},"chunks":{"type":"integer","minimum":0,"maximum":256},"bytes":{"type":"integer","minimum":0,"maximum":67108864}}}}}}}}}},"401":{"description":"PLATPHORM_API_KEY required; no storage access"},"409":{"description":"SNAPSHOT_OBJECT_CONFLICT: existing object preserved; no completed export claimed"},"413":{"description":"SNAPSHOT_LIMIT_EXCEEDED: export exceeds a bounded row/chunk/byte limit; no truncated success manifest"},"503":{"description":"Snapshot incomplete, timed out, invalid or storage unconfirmed. Inspect private retained objects before retrying; write outcome may be unknown."}}}},"/api/v1/recovery/quarantine":{"get":{"summary":"Inspect pending private R2 quarantine metadata","operationId":"listPendingQuarantine","tags":["Operations"],"description":"Operator-only bounded cursor inventory of pending quarantine objects in Dictionary R2. Lists key, byte size and upload timestamp; never reads or returns message bodies. Count is this page only, not a global backlog total. Metadata does not establish payload validity. No-store; read-only and independent of D1 availability.","security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","description":"Opaque R2 continuation cursor; omit on first request. Maximum 8192 UTF-8 bytes.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Metadata-only page and opaque next cursor"},"400":{"description":"Invalid pagination"},"401":{"description":"Operator authorization required"},"503":{"description":"Cloudflare service unavailable"}}}},"/api/v1/publication/outbox":{"get":{"summary":"Inspect publication outbox state","description":"Protected operator view of pending, enqueued, published, superseded, and quarantined publication events.","operationId":"listPublicationOutbox","tags":["Operations"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"responses":{"200":{"description":"Recent publication outbox records"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/api/v1/publication/outbox/{id}/replay":{"post":{"summary":"Replay a publication event","description":"Protected idempotent replay of a durable publication event after inspection or quarantine.","operationId":"replayPublicationOutboxEvent","tags":["Operations"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Replay queued or durably pending"},"401":{"description":"PLATPHORM_API_KEY required"},"404":{"description":"Outbox record not found"}}}},"/api/v1/removal-requests":{"get":{"summary":"List removal requests","description":"Protected moderation queue","operationId":"listRemovalRequests","tags":["Moderation"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"responses":{"200":{"description":"Removal request queue"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/api/v1/removal-requests/{id}/approve":{"post":{"summary":"Approve a removal request","description":"Protected approval that archives and removes the definition from public search","operationId":"approveRemovalRequest","tags":["Moderation"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Removal approved and applied"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/api/v1/workflows/{id}":{"get":{"summary":"Inspect a translation Workflow instance","description":"Protected Cloudflare Workflow status inspection without requiring management-plane OAuth scope","operationId":"getWorkflowInstance","tags":["Workflows"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Workflow instance status"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/api/v1/definitions/{id}/translations":{"post":{"summary":"Request a translation","description":"Protected Cloudflare Workers AI translation request. A Cloudflare Workflow creates a pending machine-assisted definition that requires human review; existing source definitions are never overwritten.","operationId":"requestTranslation","tags":["Translations"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["targetLocale"],"properties":{"targetLocale":{"type":"string","enum":["en","es","fr","de","ga","gd","ja","zh","ar","pt","ko","hi"]}}}}}},"responses":{"202":{"description":"Translation Workflow queued; the generated definition remains pending until human review"},"400":{"description":"Unsupported target locale"},"401":{"description":"PLATPHORM_API_KEY required"},"404":{"description":"Approved source definition not found"},"503":{"description":"Cloudflare Workers AI or Workflow binding unavailable; no job was queued"}}}},"/api/v1/workflows/{id}/restart":{"post":{"summary":"Restart a translation Workflow instance","description":"Protected in-place restart using the bound Cloudflare Workflow API","operationId":"restartWorkflowInstance","tags":["Workflows"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Workflow restart accepted with current status"},"401":{"description":"PLATPHORM_API_KEY required"}}}}},"components":{"schemas":{"VehicleScopeInput":{"type":"object","additionalProperties":false,"required":["vehicleModels","modelYears","technicalSystems","sourceLocator","scopeNote"],"properties":{"vehicleModels":{"type":"array","maxItems":100,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":100,"description":"Trimmed NFKC label. Runtime also enforces case-insensitive uniqueness after normalization."}},"modelYears":{"type":"array","maxItems":300,"uniqueItems":true,"items":{"type":"integer","minimum":1900,"maximum":2199}},"technicalSystems":{"type":"array","maxItems":100,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":100,"description":"Trimmed NFKC label. Runtime also enforces case-insensitive uniqueness after normalization."}},"sourceLocator":{"type":"string","minLength":3,"maxLength":500,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"scopeNote":{"type":"string","minLength":20,"maxLength":2000,"description":"Send trimmed text. Runtime enforces these bounds after trimming."}},"anyOf":[{"type":"object","required":["vehicleModels"],"properties":{"vehicleModels":{"type":"array","minItems":1}}},{"type":"object","required":["modelYears"],"properties":{"modelYears":{"type":"array","minItems":1}}},{"type":"object","required":["technicalSystems"],"properties":{"technicalSystems":{"type":"array","minItems":1}}}],"description":"Explicit source-backed applicability only; empty modelYears means unspecified years. Publication dates and year ranges are never coerced into applicability. At least one assignment is required. Schema describes normalized inputs; Unicode and trimmed/case-insensitive uniqueness remain runtime refinements."},"EditorialProposalInput":{"oneOf":[{"type":"object","additionalProperties":false,"required":["kind","reason","term","definition","locale","sourceUrl"],"properties":{"kind":{"type":"string","const":"new_term"},"reason":{"type":"string","minLength":10,"maxLength":2000,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"attribution":{"type":"string","minLength":1,"maxLength":100,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"term":{"type":"string","minLength":1,"maxLength":200,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"definition":{"type":"string","minLength":20,"maxLength":2000,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"locale":{"type":"string","enum":["en","es","fr","de","ga","gd","ja","zh","ar","pt","ko","hi"]},"sourceUrl":{"type":"string","format":"uri","maxLength":2000,"pattern":"^[hH][tT][tT][pP][sS]?://[^/@?#]+(?:[/?#]|$)","description":"Normalized HTTP(S) source reference without userinfo. Runtime URL parsing additionally rejects usernames and passwords. References are stored, never fetched."}}},{"type":"object","additionalProperties":false,"required":["kind","reason","termId","definition","locale","sourceUrl"],"properties":{"kind":{"type":"string","const":"correction"},"reason":{"type":"string","minLength":10,"maxLength":2000,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"attribution":{"type":"string","minLength":1,"maxLength":100,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"definition":{"type":"string","minLength":20,"maxLength":2000,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"locale":{"type":"string","enum":["en","es","fr","de","ga","gd","ja","zh","ar","pt","ko","hi"]},"sourceUrl":{"type":"string","format":"uri","maxLength":2000,"pattern":"^[hH][tT][tT][pP][sS]?://[^/@?#]+(?:[/?#]|$)","description":"Normalized HTTP(S) source reference without userinfo. Runtime URL parsing additionally rejects usernames and passwords. References are stored, never fetched."}}},{"type":"object","additionalProperties":false,"required":["kind","reason","termId","definition","locale","sourceUrl"],"properties":{"kind":{"type":"string","const":"translation"},"reason":{"type":"string","minLength":10,"maxLength":2000,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"attribution":{"type":"string","minLength":1,"maxLength":100,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"definition":{"type":"string","minLength":20,"maxLength":2000,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"locale":{"type":"string","enum":["en","es","fr","de","ga","gd","ja","zh","ar","pt","ko","hi"]},"sourceUrl":{"type":"string","format":"uri","maxLength":2000,"pattern":"^[hH][tT][tT][pP][sS]?://[^/@?#]+(?:[/?#]|$)","description":"Normalized HTTP(S) source reference without userinfo. Runtime URL parsing additionally rejects usernames and passwords. References are stored, never fetched."}}},{"type":"object","additionalProperties":false,"required":["kind","reason","termId","alias","locale"],"properties":{"kind":{"type":"string","const":"alias"},"reason":{"type":"string","minLength":10,"maxLength":2000,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"attribution":{"type":"string","minLength":1,"maxLength":100,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"alias":{"type":"string","minLength":1,"maxLength":200,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"locale":{"type":"string","enum":["en","es","fr","de","ga","gd","ja","zh","ar","pt","ko","hi"]}}},{"type":"object","additionalProperties":false,"required":["kind","reason","termId","sourceUrl"],"properties":{"kind":{"type":"string","const":"source"},"reason":{"type":"string","minLength":10,"maxLength":2000,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"attribution":{"type":"string","minLength":1,"maxLength":100,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"sourceUrl":{"type":"string","format":"uri","maxLength":2000,"pattern":"^[hH][tT][tT][pP][sS]?://[^/@?#]+(?:[/?#]|$)","description":"Normalized HTTP(S) source reference without userinfo. Runtime URL parsing additionally rejects usernames and passwords. References are stored, never fetched."},"vehicleScope":{"$ref":"#/components/schemas/VehicleScopeInput"}}},{"type":"object","additionalProperties":false,"required":["kind","reason","termId","category"],"properties":{"kind":{"type":"string","const":"category"},"reason":{"type":"string","minLength":10,"maxLength":2000,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"attribution":{"type":"string","minLength":1,"maxLength":100,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"category":{"type":"string","minLength":1,"maxLength":200,"description":"Send trimmed text. Runtime enforces these bounds after trimming."}}},{"type":"object","additionalProperties":false,"required":["kind","reason","termId","relatedTermId"],"properties":{"kind":{"type":"string","const":"related_term"},"reason":{"type":"string","minLength":10,"maxLength":2000,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"attribution":{"type":"string","minLength":1,"maxLength":100,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"Send trimmed text. Runtime enforces these bounds after trimming."},"relatedTermId":{"type":"string","minLength":1,"maxLength":200,"description":"Send trimmed text. Runtime enforces these bounds after trimming."}}}],"description":"Operator-authenticated submission only; strict per-kind fields and a 16384-byte total body limit. Gerry members use the separate authenticated Gerry BFF, not an operator key in the browser. Target existence and relationship constraints require storage validation."},"ProposalSubmissionResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"const":true},"error":{"type":"null"},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"data":{"type":"object","additionalProperties":false,"required":["proposalId","status","publicationStatus"],"properties":{"proposalId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","accepted","rejected","applied"]},"replayed":{"const":true},"publicationStatus":{"type":"string","enum":["not_applied","not_checked"],"description":"Applied submission replays report not_checked: this endpoint does not read publication/index progress. Review and application remain separate actions."},"attributionStatus":{"type":"string","enum":["operator_supplied_unverified","gerry_member_reference"]}}}}},"HealthResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","disabled"]},"version":{"type":"string"},"environment":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"routeComplianceScore":{"type":"integer","minimum":0,"maximum":100},"databaseStatus":{"type":"string"},"cacheStatus":{"type":"string"},"traceContextAccepted":{"type":"boolean"},"traceContextPropagated":{"type":"boolean"},"cloudflareMetadataCaptured":{"type":"boolean"},"apiStatus":{"type":"string","enum":["enabled","disabled"]},"mcpStatus":{"type":"string","enum":["enabled","disabled"]},"cloudflareBackendStatus":{"type":"string","enum":["enabled","disabled"]},"translationGenerationStatus":{"type":"string","enum":["configured","unavailable"]},"featureFlags":{"type":"object","properties":{"api":{"type":"boolean"},"mcp":{"type":"boolean"},"cloudflareBackend":{"type":"boolean"}}}}}}},"CreateTermRequest":{"type":"object","required":["term","definition","author_handle"],"properties":{"term":{"type":"string","minLength":1,"maxLength":255},"definition":{"type":"string","minLength":10,"maxLength":5000},"short_definition":{"type":["string","null"],"minLength":10,"maxLength":300,"description":"Separately recorded short definition in the selected definition locale; null means absent. Trimmed on write. Explicit null clears it without restoring legacy text."},"example_usage":{"type":"string","maxLength":1000},"author_handle":{"type":"string","minLength":2,"maxLength":50},"locale":{"type":"string","default":"en","enum":["en","es","fr","de","ga","gd","ja","zh","ar","pt","ko","hi"]},"category":{"type":"string","maxLength":200},"tags":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":100}},"source":{"type":"string","format":"uri","maxLength":2000,"description":"Legacy source_url alias; HTTP(S), no URL credentials"},"source_url":{"type":"string","format":"uri","maxLength":2000,"description":"Canonical source reference; takes precedence over source and is never fetched"},"metadata":{"type":"object","description":"Trusted operator provenance; maximum 32768 UTF-8 bytes of JSON. Existing records are not overwritten"},"aliases":{"type":"array","maxItems":20,"items":{"type":"string","minLength":1,"maxLength":100},"description":"Optional locale-scoped labels that resolve to this canonical term."}}},"CreateDefinitionRequest":{"type":"object","required":["term","definition","author_handle"],"properties":{"term":{"type":"string","minLength":1,"maxLength":100},"definition":{"type":"string","minLength":20,"maxLength":2000},"short_definition":{"type":["string","null"],"minLength":10,"maxLength":300,"description":"Separately recorded short definition in the selected definition locale; null means absent. Trimmed on write. Explicit null clears it without restoring legacy text."},"example_usage":{"type":"string","maxLength":500},"author_handle":{"type":"string","minLength":3,"maxLength":30},"locale":{"type":"string","default":"en","enum":["en","es","fr","de","ga","gd","ja","zh","ar","pt","ko","hi"]},"category":{"type":"string","maxLength":80},"tags":{"oneOf":[{"type":"array","maxItems":12,"items":{"type":"string","minLength":1,"maxLength":40}},{"type":"string","maxLength":500,"description":"Legacy comma-separated tags, at most 12 after normalization"}],"description":"Lowercased, trimmed and deduplicated on creation; existing term tags are preserved"},"aliases":{"type":"array","maxItems":20,"items":{"type":"string","minLength":1,"maxLength":100},"description":"Optional public labels that resolve to the same canonical term; aliases are locale-scoped."},"phonetic":{"type":"string","maxLength":80},"part_of_speech":{"type":"string","maxLength":80},"source":{"type":"string","format":"uri","maxLength":2000,"description":"Legacy alias for source_url; HTTP(S), no URL credentials; both fields must agree if supplied"},"source_url":{"type":"string","format":"uri","maxLength":2000,"description":"Source reference stored on new definitions; referenced URLs are not fetched"},"metadata":{"type":"object","description":"At most 5000 JSON characters; only allowlisted definition_quality_scores fields are retained. Historical/review provenance and arbitrary metadata are ignored"},"dryRun":{"type":"boolean","default":false,"description":"Validate only, with no D1 reads/writes or background work"},"consent":{"type":"boolean","description":"Public-safe original content or rights acknowledgement"}}},"LegacyDefinitionRequest":{"type":"object","required":["term","shortDefinition","fullDefinition"],"properties":{"term":{"type":"string","minLength":1,"maxLength":100},"shortDefinition":{"type":"string","minLength":10,"maxLength":300},"fullDefinition":{"type":"string","minLength":20,"maxLength":5000},"author_handle":{"type":"string"},"authorHandle":{"type":"string"},"submitterName":{"type":"string","maxLength":100},"locale":{"type":"string","default":"en","enum":["en","es","fr","de","ga","gd","ja","zh","ar","pt","ko","hi"]},"usageContext":{"type":"string","maxLength":500},"examples":{"type":"array","maxItems":5,"items":{"type":"string","maxLength":500}},"sourceUrls":{"type":"array","maxItems":5,"items":{"type":"string","format":"uri","maxLength":2000},"description":"HTTP(S) attribution references without URL credentials; not fetched"},"aliases":{"type":"array","maxItems":20,"items":{"type":"string","minLength":1,"maxLength":100}},"relatedTerms":{"type":"array","maxItems":10,"items":{"type":"string","minLength":1,"maxLength":100},"description":"Descriptive labels only; not approved canonical relations"},"tags":{"type":"array","maxItems":12,"items":{"type":"string","minLength":1,"maxLength":40}},"class":{"type":"string","maxLength":80},"dryRun":{"type":"boolean","default":false}}},"BulkIngestRequest":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#/components/schemas/CreateTermRequest"}}}},"BulkIngestResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"type":"boolean","description":"Batch processing completed; inspect failed/skipped counts rather than treating ok as per-item publication success"},"error":{"type":["object","null"]},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}},"data":{"type":"object","required":["total","success","skipped","failed","createdTerms","createdDefinitions","errors"],"properties":{"total":{"type":"integer","minimum":1,"maximum":1000},"success":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"createdTerms":{"type":"integer","minimum":0},"createdDefinitions":{"type":"integer","minimum":0},"errors":{"type":"array","items":{"type":"object","required":["index","error"],"properties":{"index":{"type":"integer","minimum":0},"term":{"type":"string","maxLength":255},"error":{"type":"string"},"code":{"type":"string","description":"INVALID_INGEST_ITEM for a rejected typed record"},"fields":{"type":"array","maxItems":16,"items":{"type":"string"},"description":"Known field names only; input values and unknown property names are not reflected"}}}}}}}},"PublicErrorResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"const":false},"data":{"type":"null"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}}}},"StatsResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","required":["terms","definitions","approvedDefinitions","authors","votes","locales","tags","classes","pendingTerms","pendingDefinitions","source","scope","moderationCounts"],"properties":{"terms":{"type":"integer","minimum":0},"definitions":{"type":"integer","minimum":0},"approvedDefinitions":{"type":"integer","minimum":0},"authors":{"type":"integer","minimum":0},"votes":{"type":"integer","minimum":0},"locales":{"type":"integer","minimum":0},"tags":{"type":"integer","minimum":0},"classes":{"type":"integer","minimum":0},"pendingTerms":{"type":["integer","null"],"minimum":0},"pendingDefinitions":{"type":["integer","null"],"minimum":0},"source":{"const":"cloudflare-d1"},"scope":{"type":"string","enum":["public","operator"]},"moderationCounts":{"type":"string","enum":["protected","included"]}},"oneOf":[{"properties":{"scope":{"const":"public"},"moderationCounts":{"const":"protected"},"pendingTerms":{"type":"null"},"pendingDefinitions":{"type":"null"}}},{"properties":{"scope":{"const":"operator"},"moderationCounts":{"const":"included"},"pendingTerms":{"type":"integer","minimum":0},"pendingDefinitions":{"type":"integer","minimum":0}}}]},"error":{"type":["object","null"]},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}}}},"Term":{"type":"object","required":["id","slug","canonical_term","tags"],"properties":{"id":{"type":"string","description":"Opaque stable identifier; historical, deterministic and UUID IDs are supported"},"slug":{"type":"string"},"canonical_term":{"type":"string"},"term_label":{"type":"object","additionalProperties":false,"required":["label","locale","requested_locale","source","is_fallback","matches_canonical","review_state"],"properties":{"label":{"type":"string"},"locale":{"type":"string"},"requested_locale":{"type":"string"},"source":{"type":"string","enum":["recorded_label","canonical_fallback"]},"is_fallback":{"type":"boolean"},"matches_canonical":{"type":"boolean"},"review_state":{"const":"unrecorded"}},"description":"Recorded name for the requested locale, only when that locale has an eligible definition; otherwise the canonical name in its origin locale. Label review provenance is unrecorded in current storage. A stored or repeated name is not evidence of a verified translation. Canonical identity, URLs and sort order remain unchanged."},"origin_locale":{"type":"string"},"phonetic":{"type":["string","null"]},"part_of_speech":{"type":["string","null"]},"category":{"type":["string","null"]},"vehicle_models":{"type":"array","items":{"type":"string"}},"model_years":{"type":"array","items":{"type":["integer","string"]}},"technical_systems":{"type":"array","items":{"type":"string"}},"vehicle_scope":{"type":"object","required":["source"],"description":"Effective recorded applicability; the latest applied source scope replaces all prior assignments together. Not a fitment guarantee. Original term metadata remains separate.","properties":{"source":{"type":"string","enum":["applied_source_annotation","term_metadata","unrecorded","unavailable"]},"annotation_id":{"type":"string"},"source_url":{"type":"string","format":"uri"},"source_locator":{"type":"string"},"scope_note":{"type":"string"}}},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["approved"]},"view_count":{"type":["integer","null"],"minimum":0},"definition_id":{"type":["string","null"]},"definition":{"type":["string","null"]},"short_definition":{"type":["string","null"],"minLength":10,"maxLength":300,"description":"Separately recorded short definition in the selected definition locale; null means absent. Trimmed on write. Explicit null clears it without restoring legacy text."},"definition_locale":{"type":["string","null"]},"author_handle":{"type":["string","null"]},"upvotes":{"type":["integer","null"],"minimum":0},"downvotes":{"type":["integer","null"],"minimum":0},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"published_at":{"type":["string","null"]},"metadata":{"type":"object","description":"Allowlisted recorded public provenance; approval alone is not human review"},"term_metadata":{"type":"object","description":"Allowlisted recorded public provenance; approval alone is not human review"},"available_locales":{"type":"array","items":{"type":"string"},"description":"Locales with approved non-deleted definitions. Does not include English fallback locales."},"aliases":{"type":"array","items":{"type":"object","required":["alias","locale"],"properties":{"alias":{"type":"string"},"locale":{"type":"string"}}}}}},"Definition":{"type":"object","required":["id","locale","definition","short_definition","author_handle","metadata"],"properties":{"id":{"type":"string","description":"Opaque stable identifier; historical, deterministic and UUID IDs are supported"},"term_id":{"type":"string"},"slug":{"type":"string"},"term":{"type":"string"},"locale":{"type":"string"},"definition":{"type":"string"},"short_definition":{"type":["string","null"],"minLength":10,"maxLength":300,"description":"Separately recorded short definition in the selected definition locale; null means absent. Trimmed on write. Explicit null clears it without restoring legacy text."},"example_usage":{"type":["string","null"]},"source_url":{"type":["string","null"]},"author_handle":{"type":"string"},"upvotes":{"type":["integer","null"],"minimum":0},"downvotes":{"type":["integer","null"],"minimum":0},"created_at":{"type":["string","null"]},"published_at":{"type":["string","null"]},"metadata":{"type":"object","description":"Allowlisted recorded public provenance; approval alone is not human review"},"definition_quality_scores":{"type":["object","null"]}}},"SourceReference":{"type":"object","required":["id","kind","definition_id","annotation_id","locale","url","title","locator","provenance"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["definition","annotation"]},"definition_id":{"type":["string","null"]},"annotation_id":{"type":["string","null"]},"locale":{"type":["string","null"]},"url":{"type":"string","format":"uri","maxLength":2000},"title":{"type":["string","null"]},"locator":{"type":["string","null"]},"provenance":{"type":"object","description":"Recorded public source/capture/hash and translation facts only. Null means unrecorded; hashes do not establish recoverability or technical correctness.","additionalProperties":false,"properties":{"corpus":{"type":["string","null"]},"source_collection":{"type":["string","null"]},"original_url":{"type":["string","null"],"format":"uri"},"requested_capture":{"type":["string","null"]},"actual_capture":{"type":["string","null"]},"source_file_sha256":{"type":["string","null"]},"source_evidence_sha256":{"type":["string","null"]},"source_definition_sha256":{"type":["string","null"]},"translation_status":{"type":["string","null"]},"machine_assisted":{"type":["boolean","null"]},"human_reviewed":{"type":["boolean","null"]}}}}},"TermSourcesResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","required":["term_id","slug","locale","sources","pagination","scope"],"properties":{"term_id":{"type":"string"},"slug":{"type":"string"},"locale":{"type":["string","null"]},"scope":{"const":"public_definition_citations_and_applied_source_annotations"},"sources":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/SourceReference"}},"pagination":{"type":"object","required":["limit","offset","scanned","omitted_invalid_references","hasMore","nextOffset"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":100},"offset":{"type":"integer","minimum":0},"scanned":{"type":"integer","minimum":0},"omitted_invalid_references":{"type":"integer","minimum":0},"hasMore":{"type":"boolean"},"nextOffset":{"type":["integer","null"],"minimum":0}}}}},"error":{"type":["object","null"]},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}}}},"Pagination":{"type":"object","required":["limit","offset","total"],"properties":{"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0}}},"LocaleSummary":{"type":"object","required":["code","name","native_name","direction","is_active","definition_count","status","localization","review_counts"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"native_name":{"type":["string","null"]},"direction":{"type":"string","enum":["ltr","rtl"]},"is_active":{"type":"boolean"},"definition_count":{"type":"integer","minimum":0},"status":{"type":"string","enum":["published","unavailable"]},"localization":{"type":"string","enum":["archived_source","machine_assisted_draft","human_reviewed","review_status_unrecorded","mixed","unavailable"]},"review_counts":{"type":"object","required":["historical_source","machine_assisted_draft","human_reviewed","unrecorded"],"properties":{"historical_source":{"type":"integer","minimum":0},"machine_assisted_draft":{"type":"integer","minimum":0},"human_reviewed":{"type":"integer","minimum":0},"unrecorded":{"type":"integer","minimum":0}}}}},"TermsListResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","required":["terms","pagination","locale","sort"],"properties":{"terms":{"type":"array","items":{"$ref":"#/components/schemas/Term"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"locale":{"type":"string"},"sort":{"type":"string","enum":["recent","alphabetical","popular","trending"]},"ranking":{"type":"object"}}},"error":{"type":["object","null"]},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}}}},"TermDetailResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","required":["id","slug","canonical_term","definitions","aliases","requested_locale","returned_locale","available_locales","availableLocales"],"properties":{"id":{"type":"string","description":"Opaque stable identifier; historical, deterministic and UUID IDs are supported"},"slug":{"type":"string"},"canonical_term":{"type":"string"},"term_label":{"type":"object","additionalProperties":false,"required":["label","locale","requested_locale","source","is_fallback","matches_canonical","review_state"],"properties":{"label":{"type":"string"},"locale":{"type":"string"},"requested_locale":{"type":"string"},"source":{"type":"string","enum":["recorded_label","canonical_fallback"]},"is_fallback":{"type":"boolean"},"matches_canonical":{"type":"boolean"},"review_state":{"const":"unrecorded"}},"description":"Recorded name for the requested locale, only when that locale has an eligible definition; otherwise the canonical name in its origin locale. Label review provenance is unrecorded in current storage. A stored or repeated name is not evidence of a verified translation. Canonical identity, URLs and sort order remain unchanged."},"origin_locale":{"type":"string"},"phonetic":{"type":["string","null"]},"part_of_speech":{"type":["string","null"]},"category":{"type":["string","null"]},"vehicle_models":{"type":"array","items":{"type":"string"}},"model_years":{"type":"array","items":{"type":["integer","string"]}},"technical_systems":{"type":"array","items":{"type":"string"}},"vehicle_scope":{"type":"object","required":["source"],"description":"Effective recorded applicability; the latest applied source scope replaces all prior assignments together. Not a fitment guarantee. Original term metadata remains separate.","properties":{"source":{"type":"string","enum":["applied_source_annotation","term_metadata","unrecorded","unavailable"]},"annotation_id":{"type":"string"},"source_url":{"type":"string","format":"uri"},"source_locator":{"type":"string"},"scope_note":{"type":"string"}}},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["approved"]},"view_count":{"type":["integer","null"],"minimum":0},"definition_id":{"type":["string","null"]},"definition":{"type":["string","null"]},"short_definition":{"type":["string","null"],"minLength":10,"maxLength":300,"description":"Separately recorded short definition in the selected definition locale; null means absent. Trimmed on write. Explicit null clears it without restoring legacy text."},"definition_locale":{"type":["string","null"]},"author_handle":{"type":["string","null"]},"upvotes":{"type":["integer","null"],"minimum":0},"downvotes":{"type":["integer","null"],"minimum":0},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"published_at":{"type":["string","null"]},"metadata":{"type":"object","description":"Allowlisted recorded public provenance; approval alone is not human review"},"term_metadata":{"type":"object","description":"Allowlisted recorded public provenance; approval alone is not human review"},"available_locales":{"type":"array","items":{"type":"object","required":["locale","count","state"],"properties":{"locale":{"type":"string"},"count":{"type":"integer","minimum":0},"state":{"type":"string","enum":["published","unavailable"]}}}},"aliases":{"type":"array","items":{"type":"object","required":["alias","locale"],"properties":{"alias":{"type":"string"},"locale":{"type":"string"}}}},"definitions":{"type":"array","items":{"$ref":"#/components/schemas/Definition"}},"availableLocales":{"type":"array","items":{"type":"object","required":["locale","count","state"],"properties":{"locale":{"type":"string"},"count":{"type":"integer","minimum":0},"state":{"type":"string","enum":["published","unavailable"]}}}},"requested_locale":{"type":"string"},"returned_locale":{"type":["string","null"]}}},"error":{"type":["object","null"]},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}}}},"SearchResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"type":"boolean"},"data":{"oneOf":[{"type":"object","required":["results","pagination","locale","query","suggestions"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Term"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"locale":{"type":"string"},"query":{"type":"string"},"suggestions":{"type":"array","maxItems":3,"items":{"type":"object","required":["slug","canonical_term"],"properties":{"slug":{"type":"string"},"canonical_term":{"type":"string"}}}}}},{"type":"object","required":["results","locale"],"not":{"required":["pagination"]},"properties":{"results":{"type":"array","maxItems":0,"items":{"$ref":"#/components/schemas/Term"}},"locale":{"type":"string"}}}]},"error":{"type":["object","null"]},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}}}},"LocalesResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","required":["locales"],"properties":{"locales":{"type":"array","items":{"$ref":"#/components/schemas/LocaleSummary"}}}},"error":{"type":["object","null"]},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}}}},"LocaleResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"type":"boolean"},"data":{"$ref":"#/components/schemas/LocaleSummary"},"error":{"type":["object","null"]},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}}}},"CategoriesResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","required":["categories"],"properties":{"categories":{"type":"array","items":{"type":"object","required":["slug","name","term_count","count","degraded"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"term_count":{"type":"integer","minimum":0},"count":{"type":"integer","minimum":0},"degraded":{"type":"boolean"}}}}}},"error":{"type":["object","null"]},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}}}},"TagsResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","required":["tags"],"properties":{"tags":{"type":"array","items":{"type":"object","required":["slug","name","term_count","count","degraded"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"term_count":{"type":"integer","minimum":0},"count":{"type":"integer","minimum":0},"degraded":{"type":"boolean"}}}}}},"error":{"type":["object","null"]},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}}}},"FacetTermsResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","required":["terms","locale"],"oneOf":[{"required":["category"]},{"required":["tag"]}],"properties":{"category":{"type":"string"},"tag":{"type":"string"},"locale":{"type":"string"},"terms":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/Term"}}}},"error":{"type":["object","null"]},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}}}},"EventsResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","required":["events","count","next_cursor"],"properties":{"count":{"type":"integer","minimum":0},"next_cursor":{"type":["string","null"]},"events":{"type":"array","items":{"type":"object","required":["id","type","source","time","data","trace_id"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["definition.published"]},"source":{"type":"string"},"time":{"type":"string"},"trace_id":{"type":"string"},"data":{"type":"object","required":["slug","canonical_term","category","locale","definition","source_url","author_handle"],"properties":{"slug":{"type":"string"},"canonical_term":{"type":"string"},"category":{"type":["string","null"]},"locale":{"type":"string"},"definition":{"type":"string"},"short_definition":{"type":["string","null"],"minLength":10,"maxLength":300,"description":"Separately recorded short definition in the selected definition locale; null means absent. Trimmed on write. Explicit null clears it without restoring legacy text."},"source_url":{"type":["string","null"]},"author_handle":{"type":"string"}}}}}}}},"error":{"type":["object","null"]},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}}}},"DefinitionHistoryResponse":{"type":"object","required":["ok","data","error","meta","warnings"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","required":["definitionId","currentRecordPresent","latestRevision","coverage","revisions","pagination","scope","priorHistoryReconstructed"],"properties":{"definitionId":{"type":"string"},"currentRecordPresent":{"type":"boolean"},"latestRevision":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991},"coverage":{"type":"string","enum":["observed_from_creation","observed_from_first_change","prior_history_unrecorded"]},"scope":{"const":"protected_definition_history"},"priorHistoryReconstructed":{"const":false},"revisions":{"type":"array","maxItems":50,"items":{"type":"object","required":["revision","operation","recordedAt","snapshot","operatorActions"],"properties":{"revision":{"type":"integer","minimum":1,"maximum":9007199254740991},"operation":{"type":"string","enum":["baseline","create","update","delete"]},"recordedAt":{"type":"string","format":"date-time"},"snapshot":{"type":"object","required":["id","term_id","locale","definition","author_handle","status","example_usage","source_url","metadata_json","created_at","updated_at","published_at","deleted_at","ai_review_score","ai_review_reason","docs_article_id","docs_article_url"],"additionalProperties":false,"properties":{"id":{"type":"string"},"term_id":{"type":"string"},"locale":{"type":"string"},"definition":{"type":"string"},"author_handle":{"type":"string"},"status":{"type":"string"},"example_usage":{"type":["string","null"]},"source_url":{"type":["string","null"]},"metadata_json":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"published_at":{"type":["string","null"]},"deleted_at":{"type":["string","null"]},"ai_review_score":{"type":["number","null"]},"ai_review_reason":{"type":["string","null"]},"docs_article_id":{"type":["string","null"]},"docs_article_url":{"type":["string","null"]}}},"operatorActions":{"type":"array","maxItems":100,"items":{"type":"object","required":["id","action","actor_handle","trace_id","created_at"],"additionalProperties":false,"properties":{"id":{"type":"string"},"action":{"type":"string"},"actor_handle":{"type":["string","null"]},"trace_id":{"type":"string"},"created_at":{"type":"string"}}}}}}},"pagination":{"type":"object","required":["limit","before","hasMore","nextBefore"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":50},"before":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991},"hasMore":{"type":"boolean"},"nextBefore":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991}}}}},"error":{"type":["object","null"]},"meta":{"type":"object","required":["generatedAt","traceId","degraded"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"traceId":{"type":"string"},"degraded":{"type":"boolean"}}},"warnings":{"type":"array","items":{"type":"string"}}}}},"securitySchemes":{"PlatPhormApiKey":{"type":"apiKey","in":"header","name":"X-PlatPhorm-API-Key","description":"Shared platform key required for protected actions. Public-safe read routes remain open."},"PlatPhormBearer":{"type":"http","scheme":"bearer","bearerFormat":"PLATPHORM_API_KEY"}}},"tags":[{"name":"System","description":"Health and system endpoints"},{"name":"Terms","description":"Dictionary term operations"},{"name":"Definitions","description":"Definition operations"},{"name":"Search","description":"Search functionality"},{"name":"Collections","description":"Generated optional public collections from approved classes and tags"},{"name":"Datasets","description":"Public-safe Dictionary dataset pages and exports"},{"name":"Graph","description":"Public-safe Dictionary graph operations"},{"name":"Web Status","description":"web.status.v1 readiness and scorecard endpoints"},{"name":"Agent Policy","description":"Public-safe agent access policy, robots policy, and platform registry"},{"name":"MCP","description":"JSON-RPC 2.0 Model Context Protocol endpoint"},{"name":"Discovery","description":"Well-known, policy, and discovery artifacts"},{"name":"Operations","description":"Protected publication reliability and recovery operations"},{"name":"Events","description":"Public completed Dictionary publication events"},{"name":"Translations","description":"Translation job availability and status"}]}