openapi: 3.1.0
info:
  title: Platphorm Files
  version: 1.1.0
  description: A Dropbox-style file workspace backed by S3-compatible object storage. Human readable, agent native. Upload, organize, share, and index files over a clean UI, a REST API, and MCP tools.
servers:
  - url: https://files.platphormnews.com
security:
  - PlatphormApiKey: []
paths:
  /api/health:
    get:
      summary: Public-safe health and platform compliance status.
      parameters:
        - in: header
          name: traceparent
          schema: { type: string }
        - in: header
          name: X-PlatPhorm-Request-Id
          schema: { type: string }
      responses:
        "200":
          description: Health payload
          headers:
            traceparent:
              description: Propagated W3C Trace Context with a Platphorm child span.
              schema: { type: string }
            X-PlatPhorm-Trace-Id:
              description: Platphorm trace identifier.
              schema: { type: string }
            X-PlatPhorm-Request-Id:
              description: Platphorm request identifier.
              schema: { type: string }
  /api/v1/health:
    get:
      summary: Versioned public-safe health and platform compliance status.
      responses:
        "200": { description: Health payload }
  /api/v1/public/bbs:
    get:
      summary: List public-safe files and folders below the fixed bbs/public prefix.
      security: []
      parameters:
        - in: query
          name: prefix
          schema: { type: string, default: bbs/public/ }
      responses:
        "200": { description: Public BBS folder listing }
        "400": { description: Prefix attempted to leave bbs/public/ }
  /api/v1/public/bbs/upload:
    post:
      summary: Upload a file anonymously below the fixed bbs/public prefix.
      security: []
      responses:
        "201": { description: Public BBS file stored }
        "413": { description: Public file exceeds 10 MB }
        "429": { description: Public mutation rate limit exceeded }
  /api/v1/public/bbs/folder:
    post:
      summary: Create a folder anonymously below the fixed bbs/public prefix.
      security: []
      responses:
        "201": { description: Public BBS folder created }
        "400": { description: Invalid folder or attempted prefix escape }
        "429": { description: Public mutation rate limit exceeded }
  /api/v1/list:
    get:
      summary: List folders and files or search by path/hash.
      security:
        - PlatphormApiKey: []
      parameters:
        - in: query
          name: prefix
          schema: { type: string }
        - in: query
          name: query
          schema: { type: string }
      responses:
        "200": { description: File listing }
        "401": { description: PLATPHORM_API_KEY required }
  /api/v1/upload:
    post:
      summary: Upload multipart or raw file bytes with SHA-256 dedupe and history.
      security:
        - PlatphormApiKey: []
      responses:
        "201": { description: Stored file metadata }
        "409": { description: Duplicate SHA-256 blocked }
  /api/v1/ingest-url:
    post:
      summary: Fetch an allowlisted URL and store it as a file.
      security:
        - PlatphormApiKey: []
      responses:
        "201": { description: Ingested file metadata }
        "400": { description: Invalid or blocked URL }
  /api/v1/bulk-ingest:
    post:
      summary: Bounded batch URL ingest, maximum 25 URLs.
      security:
        - PlatphormApiKey: []
      responses:
        "200": { description: Per-item ingest results }
  /api/v1/metadata:
    get:
      summary: Read file metadata including hash, kind, source, and version.
      security:
        - PlatphormApiKey: []
      responses:
        "200": { description: File metadata }
  /api/v1/history:
    get:
      summary: Read recorded change history for a file or folder path.
      security:
        - PlatphormApiKey: []
      responses:
        "200": { description: Change history }
  /api/mcp:
    get:
      summary: Public MCP server metadata.
      responses:
        "200": { description: MCP metadata }
    post:
      summary: Protected JSON-RPC 2.0 MCP endpoint.
      security:
        - PlatphormApiKey: []
      responses:
        "200": { description: JSON-RPC response }
components:
  securitySchemes:
    PlatphormApiKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
