{
  "openapi": "3.1.0",
  "info": {
    "title": "Las Vegas Mermaids API",
    "version": "0.3.1",
    "description": "Public-safe performance, portfolio, booking-inquiry, discovery, and read-only MCP surfaces. Submission delivery is reported honestly as delivered or degraded."
  },
  "servers": [
    {
      "url": "https://mermaids.platphormnews.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "PlatPhormApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-PlatPhorm-API-Key",
        "description": "Shared platform key for protected administrative actions."
      },
      "PlatPhormBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "PLATPHORM_API_KEY",
        "description": "Authorization: Bearer $PLATPHORM_API_KEY"
      }
    },
    "schemas": {
      "ApiSuccess": {
        "type": "object",
        "required": [
          "ok",
          "data"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "data": {}
        }
      },
      "ApiError": {
        "type": "object",
        "required": [
          "ok",
          "error"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {}
            }
          }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "method": {
            "type": "string"
          },
          "params": {}
        }
      }
    }
  },
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Get product and platform health",
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "summary": "Get versioned health",
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/performances": {
      "get": {
        "summary": "List performance concepts",
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/performances/{slug}": {
      "get": {
        "summary": "Get a performance concept",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/showcase": {
      "get": {
        "summary": "List bundled portfolio images",
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/testimonials": {
      "get": {
        "summary": "List source-attributed reviews or an honest empty state",
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/events": {
      "get": {
        "summary": "Get configured external event reference",
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/social-links": {
      "get": {
        "summary": "Get configured social references",
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/shop": {
      "get": {
        "summary": "Get configured external shop reference",
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/booking/request": {
      "post": {
        "summary": "Submit a bounded booking inquiry",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "maxProperties": 16
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/contact": {
      "post": {
        "summary": "Submit a bounded contact message",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "maxProperties": 16
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/newsletter/subscribe": {
      "post": {
        "summary": "Submit a bounded newsletter request",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "maxProperties": 16
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/integrations/status": {
      "get": {
        "summary": "Get configured and unverified integration states",
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/integrations/events": {
      "get": {
        "summary": "Get event integration metadata",
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/integrations/shop": {
      "get": {
        "summary": "Get shop integration metadata",
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "summary": "Get MCP usage metadata",
        "responses": {
          "200": {
            "description": "Successful REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                }
              }
            }
          },
          "default": {
            "description": "Error REST envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Call the read-only MCP JSON-RPC endpoint",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/JsonRpcRequest"
                  },
                  {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "$ref": "#/components/schemas/JsonRpcRequest"
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response or batch."
          }
        }
      }
    },
    "/api/cron/refresh": {
      "post": {
        "summary": "Reserved protected refresh route; currently unsupported",
        "security": [
          {
            "PlatPhormBearer": []
          },
          {
            "PlatPhormApiKey": []
          }
        ],
        "responses": {
          "401": {
            "description": "Key required."
          },
          "501": {
            "description": "No refresh job is implemented."
          }
        }
      }
    }
  },
  "x-mermaids": {
    "productPurpose": "Mermaid performance portfolio and booking inquiry",
    "publicRoutes": [
      "/",
      "/about",
      "/performances",
      "/showcase",
      "/events",
      "/shop",
      "/contact",
      "/booking",
      "/faq",
      "/privacy",
      "/terms",
      "/disclaimer",
      "/api/health",
      "/api/v1/health",
      "/api/docs",
      "/openapi.yaml",
      "/openapi.json",
      "/llms.txt",
      "/llms-full.txt",
      "/llms-index.json",
      "/rss.xml",
      "/feed.xml",
      "/sitemap.xml",
      "/sitemap-index.xml",
      "/sitemap-main.xml",
      "/robots.txt",
      "/.well-known/mcp.json",
      "/.well-known/agents.json",
      "/.well-known/security.txt",
      "/.well-known/trust.json",
      "/manifest.webmanifest",
      "/api/mcp",
      "/api/v1/performances",
      "/api/v1/showcase",
      "/api/v1/testimonials",
      "/api/v1/events",
      "/api/v1/social-links",
      "/api/v1/shop",
      "/api/v1/integrations/status",
      "/api/v1/integrations/events",
      "/api/v1/integrations/shop"
    ],
    "publicSubmissionBoundary": "Booking, contact, and newsletter submissions are rate-limited public product actions.",
    "protectedBoundary": "Administrative actions require PLATPHORM_API_KEY.",
    "unsupported": [
      "MCP mutations",
      "payment processing",
      "availability guarantees",
      "automated platform reports"
    ]
  }
}
