{"openapi":"3.1.0","info":{"title":"PlatPhorm Dictionary API","description":"Open dictionary API for the new internet. AI-first, human-friendly definitions for modern terminology, including multilingual GitOps, release engineering, DevOps, growth marketing, social media marketing, workflow automation, Make, n8n, Zapier, IETF DNS, RFC 1918, RFC 6598, RFC 8445, CGNAT, ICE, STUN, TURN, and NAT traversal terminology. Public generated snapshots are source-labeled and degraded honestly when database storage is unavailable. Generated definition records include definition_quality_scores.readability with Flesch-Kincaid metadata and definition_quality_scores.sentiment from the Emoji sentiment API when scoring is available.","version":"1.0.0","contact":{"name":"PlatPhorm News Network","url":"https://platphormnews.com"},"license":{"name":"Open Data Commons Open Database License (ODbL)","url":"https://opendatacommons.org/licenses/odbl/"}},"servers":[{"url":"https://dictionary.platphormnews.com","description":"Production"}],"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 list of dictionary terms","operationId":"listTerms","tags":["Terms"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"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":{"description":"List of terms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermsListResponse"}}}}}},"post":{"summary":"Submit a new term","description":"Submit a new term or definition for review","operationId":"createTerm","tags":["Terms"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTermRequest"}}}},"responses":{"201":{"description":"Term submitted for review"},"400":{"description":"Validation error"}}}},"/api/v1/ingest":{"post":{"summary":"Bulk ingest terms","description":"Submit multiple terms and definitions in a single request (max 500)","operationId":"bulkIngest","tags":["Terms"],"security":[{"PlatPhormApiKey":[]},{"PlatPhormBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkIngestRequest"}}}},"responses":{"201":{"description":"Bulk ingest processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkIngestResponse"}}}},"400":{"description":"Validation error"}}}},"/api/v1/definitions":{"post":{"summary":"Submit a public-safe definition","description":"Submit a public-safe Dictionary definition. If Neon storage is unavailable, the response is STORAGE_UNAVAILABLE, the browser should keep local storage, and Dictionary attempts a tagged OpenDocs fallback copy with platphorm-dictionary-neon-fallback.","operationId":"submitDefinition","tags":["Definitions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDefinitionRequest"}}}},"responses":{"201":{"description":"Definition persisted to Dictionary storage"},"400":{"description":"Validation error"},"409":{"description":"Duplicate public definition by the same handle and locale"},"503":{"description":"Dictionary storage unavailable; local draft and OpenDocs fallback details returned"}}}},"/api/v1/terms/{slug}":{"get":{"summary":"Get term details","description":"Get a term with all its definitions","operationId":"getTerm","tags":["Terms"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string","default":"en"}}],"responses":{"200":{"description":"Term details"},"404":{"description":"Term not found"}}}},"/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":{"get":{"summary":"Search terms","description":"Full-text search with fuzzy matching","operationId":"searchTerms","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string","default":"en"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Search results"}}}},"/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/trending":{"get":{"summary":"List trending terms","description":"Return trending approved public Dictionary terms computed from recent approved terms, votes, views, and freshness.","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"],"responses":{"200":{"description":"Public categories"}}}},"/api/v1/categories/{slug}":{"get":{"summary":"Get category terms","description":"Return approved public terms in a category.","operationId":"getCategory","tags":["Terms"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Category terms"},"404":{"description":"Category not found"}}}},"/api/v1/tags":{"get":{"summary":"List tags","description":"Return public Dictionary tag counts from approved terms.","operationId":"listTags","tags":["Terms"],"responses":{"200":{"description":"Public tags"}}}},"/api/v1/tags/{slug}":{"get":{"summary":"Get tag terms","description":"Return approved public terms for a tag.","operationId":"getTag","tags":["Terms"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tag terms"},"404":{"description":"Tag not found"}}}},"/api/v1/locales":{"get":{"summary":"List locales","description":"Return the Dictionary locale registry and honest localization status.","operationId":"listLocales","tags":["Terms"],"responses":{"200":{"description":"Locale registry"}}}},"/api/v1/stats":{"get":{"summary":"Dictionary stats","description":"Return real approved public term, definition, category, and tag counts when the database is available, or an explicit seed fallback state when degraded.","operationId":"getStats","tags":["System"],"responses":{"200":{"description":"Dictionary stats"}}}},"/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 x-vercel-ja4-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 readiness, source-backed counts, and Search Console remediation targets. /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 public web readiness scorecard. /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 for Dictionary read-only tools, public-safe submissions/votes, and protected tool scaffolds.","operationId":"callMcp","tags":["MCP"],"responses":{"200":{"description":"JSON-RPC response"},"400":{"description":"Parse error"}}}},"/.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, Vercel metadata, redaction, and discovery policy.","operationId":"getTrustPolicy","tags":["Discovery"],"responses":{"200":{"description":"Trust policy"}}}},"/api/v1/definitions/{id}/vote":{"post":{"summary":"Vote on definition","description":"Upvote or downvote a definition","operationId":"voteDefinition","tags":["Definitions"],"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"}}}}},"components":{"schemas":{"HealthResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded"]},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"Term":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"canonical_term":{"type":"string"},"phonetic":{"type":"string"},"part_of_speech":{"type":"string"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}},"Definition":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"definition":{"type":"string"},"example_usage":{"type":"string"},"author_handle":{"type":"string"},"upvotes":{"type":"integer"},"downvotes":{"type":"integer"},"locale":{"type":"string"}}},"CreateTermRequest":{"type":"object","required":["term","definition","author_handle"],"properties":{"term":{"type":"string","minLength":1,"maxLength":255},"definition":{"type":"string","minLength":10,"maxLength":5000},"example_usage":{"type":"string","maxLength":1000},"author_handle":{"type":"string","minLength":2,"maxLength":50},"locale":{"type":"string","default":"en"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}},"CreateDefinitionRequest":{"type":"object","required":["term","definition","author_handle"],"properties":{"term":{"type":"string","minLength":1,"maxLength":100},"definition":{"type":"string","minLength":20,"maxLength":2000},"example_usage":{"type":"string","maxLength":500},"author_handle":{"type":"string","minLength":3,"maxLength":30},"locale":{"type":"string","default":"en","enum":["en","es","fr","de","ja","zh","ar","pt","ko","hi"]},"category":{"type":"string","maxLength":80},"tags":{"type":"array","items":{"type":"string"}},"phonetic":{"type":"string","maxLength":80},"part_of_speech":{"type":"string","maxLength":80},"source":{"type":"string","format":"uri"},"consent":{"type":"boolean","description":"Public-safe original content or rights acknowledgement"}}},"BulkIngestRequest":{"type":"object","required":["items"],"properties":{"items":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/CreateTermRequest"}}}},"BulkIngestResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"total":{"type":"integer"},"success":{"type":"integer"},"failed":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"term":{"type":"string"},"error":{"type":"string"}}}}}},"message":{"type":"string"}}},"TermsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Term"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}}}}}},"securitySchemes":{"PlatPhormApiKey":{"type":"apiKey","in":"header","name":"X-PlatPhorm-API-Key","description":"Future-protected action key. Public-safe routes remain open while PLATPHORM_REQUIRE_API_KEY=false."},"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"}]}