openapi: 3.1.0
info:
  title: "DESA - Dynamic Encoded Script Analysis API"
  version: 1.0.0
  description: "Public-safe static encoded-script analysis, PowerShell deobfuscation, IOC extraction, deterministic detection-rule matching, exports, and JSON-RPC MCP tooling. DESA never executes submitted scripts."
  contact:
    name: PlatPhormNews
    url: https://platphormnews.com
  license:
    name: MIT
    url: https://desa.platphormnews.com/license
servers:
  - 
    url: https://desa.platphormnews.com
    description: Production
tags:
  - 
    name: Analysis
    description: "Static-only script analysis and decoding."
  - 
    name: Rules
    description: "Public detection-rule browsing."
  - 
    name: Samples
    description: "Public-safe sample scripts."
  - 
    name: Export
    description: "Public-safe analysis exports."
  - 
    name: Integrations
    description: "DESA network integrations with degraded fallbacks."
  - 
    name: MCP
    description: "JSON-RPC 2.0 MCP endpoint."
  - 
    name: Discovery
    description: "Health, discovery, SEO, and platform contract routes."
paths:
  /api/health:
    get:
      tags:
        - Discovery
      summary: "Health summary"
      responses:
        200:
          description: "DESA health or degraded health summary"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
  /api/v1/health:
    get:
      tags:
        - Discovery
      summary: "Versioned health summary"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
  /api/v1/analyze:
    post:
      tags:
        - Analysis
      summary: "Analyze script content statically"
      description: "Runs deterministic static analysis only. DESA does not execute scripts, invoke PowerShell, fetch embedded payload URLs, or submit samples to external services."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  description: "Script content to analyze. Max 5 MB."
                file_url:
                  type: string
                  format: uri
                  description: "Optional public URL fetched with SSRF protection and no redirects."
                analysis_type:
                  type: string
                  enum:
                    - full
                    - decode_only
                    - deobfuscate
                    - ioc_extract
                    - threat_detect
                    - syntax_check
                options:
                  type: object
          "multipart/form-data":
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                file_url:
                  type: string
                  format: uri
      responses:
        200:
          description: "Static analysis result"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
        400:
          description: "Error response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    const: false
                  success:
                    type: boolean
                    const: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                    required:
                      - code
                      - message
        429:
          description: "Rate limit exceeded"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    const: false
                  success:
                    type: boolean
                    const: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                    required:
                      - code
                      - message
  /api/v1/decode:
    post:
      tags:
        - Analysis
      summary: "Decode Base64, UTF-16LE PowerShell, hex, or auto-detected content"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
        400:
          description: "Error response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    const: false
                  success:
                    type: boolean
                    const: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                    required:
                      - code
                      - message
  "/api/v1/extract-iocs":
    post:
      tags:
        - Analysis
      summary: "Extract IOCs from text statically"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
        400:
          description: "Error response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    const: false
                  success:
                    type: boolean
                    const: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                    required:
                      - code
                      - message
  "/api/v1/url-preview":
    post:
      tags:
        - Analysis
      summary: "Safely preview a public script URL"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
        400:
          description: "Error response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    const: false
                  success:
                    type: boolean
                    const: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                    required:
                      - code
                      - message
  "/api/v1/analyze-url":
    post:
      tags:
        - Analysis
      summary: "Safely fetch and analyze a public script URL"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
        400:
          description: "Error response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    const: false
                  success:
                    type: boolean
                    const: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                    required:
                      - code
                      - message
  /api/v1/samples:
    get:
      tags:
        - Samples
      summary: "List or fetch public-safe DESA samples"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
        404:
          description: "Error response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    const: false
                  success:
                    type: boolean
                    const: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                    required:
                      - code
                      - message
  /api/v1/rules:
    get:
      tags:
        - Rules
      summary: "List detection rules"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
    post:
      tags:
        - Rules
      summary: "Create a future protected custom rule"
      security:
        - 
          PlatPhormApiKey: []
      responses:
        201:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
        400:
          description: "Error response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    const: false
                  success:
                    type: boolean
                    const: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                    required:
                      - code
                      - message
  /api/v1/rules/{id}:
    get:
      tags:
        - Rules
      summary: "Get a detection rule"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
        404:
          description: "Error response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    const: false
                  success:
                    type: boolean
                    const: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                    required:
                      - code
                      - message
  /api/v1/history:
    get:
      tags:
        - Analysis
      summary: "Server analysis history; returns an honest empty degraded result without database storage"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
  /api/v1/scripts:
    get:
      tags:
        - Analysis
      summary: "Server script history when backend persistence is available"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
  /api/v1/export:
    post:
      tags:
        - Export
      summary: "Create a public-safe analysis export from content or an analysis payload"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
        400:
          description: "Error response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    const: false
                  success:
                    type: boolean
                    const: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                    required:
                      - code
                      - message
  /api/v1/integrations/json:
    post:
      tags:
        - Integrations
      summary: "Send JSON-safe analysis data to JSON Tree or local degraded formatter"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
  /api/v1/integrations/ascii:
    post:
      tags:
        - Integrations
      summary: "Send text to ASCII Converter or local degraded formatter"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
  /api/v1/integrations/xml:
    post:
      tags:
        - Integrations
      summary: "Send structured data to XML Validator or local degraded converter"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
  /api/v1/integrations:
    get:
      tags:
        - Integrations
      summary: "List integration status"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
  /api/mcp:
    get:
      tags:
        - MCP
      summary: "MCP metadata and public tool list"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
    post:
      tags:
        - MCP
      summary: "JSON-RPC 2.0 MCP endpoint"
      description: "Supports initialize, ping, tools/list, tools/call, resources/list, resources/read, prompts/list, and prompts/get."
      responses:
        200:
          description: "JSON-RPC 2.0 response"
  /api/docs:
    get:
      tags:
        - Discovery
      summary: "OpenAPI JSON"
      responses:
        200:
          description: "OpenAPI 3.1 JSON"
  /openapi.json:
    get:
      tags:
        - Discovery
      summary: "OpenAPI JSON alias"
      responses:
        200:
          description: "OpenAPI 3.1 JSON"
  /openapi.yaml:
    get:
      tags:
        - Discovery
      summary: "OpenAPI YAML"
      responses:
        200:
          description: "OpenAPI 3.1 YAML"
  /llms.txt:
    get:
      tags:
        - Discovery
      summary: "LLM context summary"
      responses:
        200:
          description: "Text summary"
  "/llms-full.txt":
    get:
      tags:
        - Discovery
      summary: "Full LLM context"
      responses:
        200:
          description: "Text context"
  "/llms-index.json":
    get:
      tags:
        - Discovery
      summary: "LLM JSON index"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
  /rss.xml:
    get:
      tags:
        - Discovery
      summary: "Public-safe RSS feed"
      responses:
        200:
          description: "RSS XML"
  /sitemap.xml:
    get:
      tags:
        - Discovery
      summary: "Validated public-safe sitemap"
      responses:
        200:
          description: "Sitemap XML"
  "/.well-known/trust.json":
    get:
      tags:
        - Discovery
      summary: "Trust policy"
      responses:
        200:
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  success:
                    type: boolean
                  data:
                    type: object
                  meta:
                    type: object
components:
  securitySchemes:
    PlatPhormApiKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
      description: "Future protected DESA actions accept PLATPHORM_API_KEY via this header or Authorization: Bearer."
  schemas:
    ApiEnvelope:
      type: object
      properties:
        ok:
          type: boolean
        success:
          type: boolean
        data:
          type: object
        meta:
          type: object
    ErrorEnvelope:
      type: object
      properties:
        ok:
          type: boolean
          const: false
        success:
          type: boolean
          const: false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
          required:
            - code
            - message
"x-desa-policy":
  publicSafeDefault: true
  staticOnly: true
  executionDisabled: true
  futureProtectedEnv: PLATPHORM_API_KEY
