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
