openapi: "3.1.0"
info: 
  title: "PlatPhorm Layout API"
  description: "Public-safe responsive layout builder, template, preview, scoring, export, discovery, and MCP tooling for layout.platphormnews.com. PLATPHORM_API_KEY is documented only for future protected actions."
  version: "0.0.1"
  contact: 
    name: "PlatPhormNews"
    url: "https://platphormnews.com"
    email: "support@platphormnews.com"
  license: 
    name: "MIT"
    url: "https://opensource.org/licenses/MIT"
servers: 
  - 
    url: "https://layout.platphormnews.com"
    description: "Production"
tags: 
  - 
    name: "Layout"
    description: "Templates, drafts, preview, score, and export"
  - 
    name: "Integrations"
    description: "Future protected integration scaffolds with honest degraded states"
  - 
    name: "Discovery"
    description: "OpenAPI, llms, sitemap, RSS, trust, and well-known files"
  - 
    name: "MCP"
    description: "JSON-RPC 2.0 Layout tooling"
paths: 
  "/api/v1/templates": 
    get: 
      tags: 
        - "Layout"
      summary: "List real public layout templates"
      description: "List real public layout templates. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/templates/{slug}": 
    get: 
      tags: 
        - "Layout"
      summary: "Fetch one template"
      description: "Fetch one template. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/layouts": 
    get: 
      tags: 
        - "Layout"
      summary: "Ephemeral server layout drafts and local-first creation"
      description: "Ephemeral server layout drafts and local-first creation. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
    post: 
      tags: 
        - "Layout"
      summary: "Ephemeral server layout drafts and local-first creation"
      description: "Ephemeral server layout drafts and local-first creation. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/layouts/{id}": 
    get: 
      tags: 
        - "Layout"
      summary: "Ephemeral layout lookup/update when available"
      description: "Ephemeral layout lookup/update when available. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
    put: 
      tags: 
        - "Layout"
      summary: "Ephemeral layout lookup/update when available"
      description: "Ephemeral layout lookup/update when available. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/layouts/preview": 
    post: 
      tags: 
        - "Layout"
      summary: "Generate deterministic responsive preview data"
      description: "Generate deterministic responsive preview data. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/layouts/score": 
    post: 
      tags: 
        - "Layout"
      summary: "Run deterministic Layout score"
      description: "Run deterministic Layout score. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/layouts/export": 
    post: 
      tags: 
        - "Layout"
      summary: "Export JSON, HTML/CSS, or React/Tailwind scaffold"
      description: "Export JSON, HTML/CSS, or React/Tailwind scaffold. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/viewport/check": 
    post: 
      tags: 
        - "Layout"
      summary: "Check one viewport for overflow and tap-target risk"
      description: "Check one viewport for overflow and tap-target risk. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/grid/analyze": 
    post: 
      tags: 
        - "Layout"
      summary: "Analyze grid and region structure"
      description: "Analyze grid and region structure. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/accessibility/check": 
    post: 
      tags: 
        - "Layout"
      summary: "Run deterministic accessibility hints"
      description: "Run deterministic accessibility hints. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/responsive/check": 
    post: 
      tags: 
        - "Layout"
      summary: "Check configured breakpoints"
      description: "Check configured breakpoints. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/audit/url": 
    post: 
      tags: 
        - "Layout"
      summary: "Audit URL with deterministic layout checks and explicit degraded remote inspection state"
      description: "Audit URL with deterministic layout checks and explicit degraded remote inspection state. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/audit/config": 
    post: 
      tags: 
        - "Layout"
      summary: "Audit layout config with deterministic findings"
      description: "Audit layout config with deterministic findings. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/reports/layout": 
    post: 
      tags: 
        - "Layout"
      summary: "Create a degraded local report summary"
      description: "Create a degraded local report summary. Boundary: future-protected."
      security: 
        - 
          PlatPhormApiKey: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/integrations/status": 
    get: 
      tags: 
        - "Integrations"
      summary: "List Layout integration configuration/degraded state"
      description: "List Layout integration configuration/degraded state. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/integrations/phorm": 
    post: 
      tags: 
        - "Integrations"
      summary: "Future protected Phorm handoff scaffold"
      description: "Future protected Phorm handoff scaffold. Boundary: future-protected."
      security: 
        - 
          PlatPhormApiKey: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/integrations/browserops": 
    post: 
      tags: 
        - "Integrations"
      summary: "Future protected BrowserOps layout check scaffold"
      description: "Future protected BrowserOps layout check scaffold. Boundary: future-protected."
      security: 
        - 
          PlatPhormApiKey: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/integrations/docs": 
    post: 
      tags: 
        - "Integrations"
      summary: "Future protected Docs report scaffold"
      description: "Future protected Docs report scaffold. Boundary: future-protected."
      security: 
        - 
          PlatPhormApiKey: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/integrations/decks": 
    post: 
      tags: 
        - "Integrations"
      summary: "Future protected Deck summary scaffold"
      description: "Future protected Deck summary scaffold. Boundary: future-protected."
      security: 
        - 
          PlatPhormApiKey: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/integrations/sheets": 
    post: 
      tags: 
        - "Integrations"
      summary: "Future protected Sheets report scaffold"
      description: "Future protected Sheets report scaffold. Boundary: future-protected."
      security: 
        - 
          PlatPhormApiKey: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/v1/integrations/insights": 
    post: 
      tags: 
        - "Integrations"
      summary: "Future protected Insights scoring handoff scaffold"
      description: "Future protected Insights scoring handoff scaffold. Boundary: future-protected."
      security: 
        - 
          PlatPhormApiKey: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/indexnow": 
    get: 
      tags: 
        - "Layout"
      summary: "Future protected IndexNow status/submission endpoint"
      description: "Future protected IndexNow status/submission endpoint. Boundary: future-protected."
      security: 
        - 
          PlatPhormApiKey: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
    post: 
      tags: 
        - "Layout"
      summary: "Future protected IndexNow status/submission endpoint"
      description: "Future protected IndexNow status/submission endpoint. Boundary: future-protected."
      security: 
        - 
          PlatPhormApiKey: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/api/mcp": 
    get: 
      tags: 
        - "MCP"
      summary: "Layout MCP JSON-RPC endpoint"
      description: "Layout MCP JSON-RPC endpoint. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
    post: 
      tags: 
        - "MCP"
      summary: "Layout MCP JSON-RPC endpoint"
      description: "Layout MCP JSON-RPC endpoint. Boundary: public-safe."
      security: []
      responses: 
        "200": 
          description: "Successful response"
          content: 
            "application/json": 
              schema: 
                type: "object"
                properties: 
                  ok: 
                    type: "boolean"
                  data: 
                    type: "object"
                required: 
                  - "ok"
        "400": 
          description: "Invalid request"
        "401": 
          description: "AUTH_REQUIRED when PLATPHORM_REQUIRE_API_KEY is enabled for future protected actions"
  "/openapi.yaml": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /openapi.yaml"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/openapi.json": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /openapi.json"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/llms.txt": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /llms.txt"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/llms-full.txt": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /llms-full.txt"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/llms-index.json": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /llms-index.json"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/robots.txt": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /robots.txt"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/sitemap.xml": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /sitemap.xml"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/sitemap-main.xml": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /sitemap-main.xml"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/sitemap-index.xml": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /sitemap-index.xml"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/rss.xml": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /rss.xml"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/feed.xml": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /feed.xml"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/manifest.webmanifest": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /manifest.webmanifest"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/.well-known/mcp.json": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /.well-known/mcp.json"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/.well-known/agents.json": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /.well-known/agents.json"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/.well-known/ai-plugin.json": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /.well-known/ai-plugin.json"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/.well-known/security.txt": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /.well-known/security.txt"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
  "/.well-known/trust.json": 
    get: 
      tags: 
        - "Discovery"
      summary: "Read /.well-known/trust.json"
      description: "Public-safe discovery surface generated from the Layout route registry."
      security: []
      responses: 
        "200": 
          description: "Discovery response"
components: 
  securitySchemes: 
    PlatPhormApiKey: 
      type: "apiKey"
      in: "header"
      name: "X-PlatPhorm-API-Key"
      description: "Public-safe Phase 1 access is open. PLATPHORM_API_KEY support is scaffolded for future protected actions."
    PlatPhormBearer: 
      type: "http"
      scheme: "bearer"
      bearerFormat: "PLATPHORM_API_KEY"
      description: "Future protected actions may use Authorization: Bearer $PLATPHORM_API_KEY when PLATPHORM_REQUIRE_API_KEY is enabled."
  schemas: 
    ApiSuccess: 
      type: "object"
      properties: 
        ok: 
          type: "boolean"
        data: 
          type: "object"
      required: 
        - "ok"
    ApiError: 
      type: "object"
      properties: 
        ok: 
          type: "boolean"
          const: false
        error: 
          type: "object"
          properties: 
            code: 
              type: "string"
            message: 
              type: "string"
            details: 
              type: "object"
          required: 
            - "code"
            - "message"
      required: 
        - "ok"
        - "error"