{"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.","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/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/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"}}}},"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":"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"}]}