{
  "openapi": "3.1.0",
  "info": {
    "title": "PlatPhorm Capability Catalog",
    "version": "1.0.0",
    "description": "Static public catalog artifacts for repositories, capabilities, search, graph, and reuse recommendations."
  },
  "servers": [
    {
      "url": "https://catalog.platphormnews.com"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Static catalog health",
        "responses": {
          "200": {
            "description": "Catalog health and generation status"
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "summary": "Versioned static catalog health",
        "responses": {
          "200": {
            "description": "Catalog health and generation status"
          }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "summary": "MCP server metadata and public read-only capability names",
        "responses": {
          "200": {
            "description": "MCP endpoint metadata"
          }
        }
      },
      "post": {
        "summary": "Public read-only JSON-RPC MCP transport",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response"
          }
        }
      }
    },
    "/catalog/generated/capabilities.json": {
      "get": {
        "summary": "Global capability index",
        "responses": {
          "200": {
            "description": "Global capability index JSON"
          }
        }
      }
    },
    "/catalog/generated/repos.json": {
      "get": {
        "summary": "Repository index",
        "responses": {
          "200": {
            "description": "Repository index JSON"
          }
        }
      }
    },
    "/catalog/generated/search-index.json": {
      "get": {
        "summary": "Search index",
        "responses": {
          "200": {
            "description": "Plain JSON search index"
          }
        }
      }
    },
    "/catalog/generated/best-implementations.json": {
      "get": {
        "summary": "Best implementation rankings",
        "responses": {
          "200": {
            "description": "Best reusable implementation candidates"
          }
        }
      }
    },
    "/catalog/generated/vision-tool-selection.json": {
      "get": {
        "summary": "Vision tool selection",
        "responses": {
          "200": {
            "description": "Browser, PlatPhorm Content, and PlatPhorm Docs mapped to catalog capabilities"
          }
        }
      }
    },
    "/api/vision/capabilities": {
      "get": {
        "summary": "Vision capability selection API",
        "responses": {
          "200": {
            "description": "Standard ok/data wrapper around the public vision selection artifact"
          }
        }
      }
    },
    "/api/vision/evidence-pack": {
      "get": {
        "summary": "Vision evidence pack API",
        "responses": {
          "200": {
            "description": "Preview-only JSON and Markdown-ready evidence pack generated from catalog state"
          }
        }
      }
    },
    "/catalog/generated/vision-evidence-pack.json": {
      "get": {
        "summary": "Static vision evidence pack",
        "responses": {
          "200": {
            "description": "Public read-only evidence pack artifact"
          }
        }
      }
    },
    "/rss.xml": {
      "get": {
        "summary": "Capability update feed",
        "responses": {
          "200": {
            "description": "RSS feed of high-signal catalog capabilities"
          }
        }
      }
    },
    "/api/v1/catalog/census": {
      "get": {
        "summary": "Catalog census snapshot",
        "responses": {
          "200": {
            "description": "Repository and dependency census generated by GitHub-native collection"
          },
          "404": {
            "description": "Census not ready"
          }
        }
      }
    },
    "/api/v1/catalog/dependencies": {
      "get": {
        "summary": "Dependency observations",
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dependency observations with repository impact counts"
          },
          "404": {
            "description": "Dependencies not available"
          }
        }
      }
    },
    "/api/v1/catalog/technologies": {
      "get": {
        "summary": "Technology observations",
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Technology observations with evidence sources"
          },
          "404": {
            "description": "Technologies not available"
          }
        }
      }
    },
    "/api/v1/catalog/publications": {
      "get": {
        "summary": "Publication summaries",
        "parameters": [
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Publication index from local and remote storage"
          }
        }
      },
      "post": {
        "summary": "Publish catalog evidence payload",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Publication accepted for persistence"
          },
          "201": {
            "description": "Publication persisted in configured GitHub destination"
          }
        }
      }
    },
    "/api/v1/catalog/publications/{filename}": {
      "get": {
        "summary": "Fetch a publication by filename",
        "parameters": [
          {
            "in": "path",
            "name": "filename",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Publication payload"
          },
          "404": {
            "description": "Publication not found"
          }
        }
      }
    },
    "/api/v1/scans": {
      "get": {
        "summary": "Scan and publication artifact inventory",
        "responses": {
          "200": {
            "description": "Generated scan and publication artifact listing"
          }
        }
      }
    },
    "/api/v1/route-compliance": {
      "get": {
        "summary": "Route compliance and protected-action status",
        "responses": {
          "200": {
            "description": "Route implementation status and contract metadata"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PlatPhormApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-PlatPhorm-API-Key",
        "description": "Protected catalog mutations require PLATPHORM_API_KEY or trusted OIDC bearer tokens. Public reads require no auth."
      },
      "PlatPhormBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Protected catalog mutations also accept Authorization: Bearer <PLATPHORM_API_KEY or trusted OIDC token>."
      }
    }
  }
}