{
  "openapi": "3.1.0",
  "info": {
    "title": "Peak Studios Developer API",
    "version": "1.0.0",
    "description": "Official OpenAPI 3.1.0 specification for Peak Studios (peakrp.net). Provides endpoints for discovering FiveM scripts, documentation, system telemetry, GitHub statistics, contact submissions, and Model Context Protocol (MCP) tool executions.",
    "contact": {
      "name": "Peak Studios Developer Support",
      "url": "https://peakrp.net/contact",
      "email": "contact@peakrp.net"
    },
    "license": {
      "name": "Proprietary & Open Source Components",
      "url": "https://github.com/Peak-Studios"
    }
  },
  "servers": [
    {
      "url": "https://peakrp.net",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/v1/info": {
      "get": {
        "operationId": "getStudioInfo",
        "summary": "Get studio metadata, brand details, and resource directory",
        "description": "Returns top-level metadata about Peak Studios, including supported FiveM frameworks, social links, documentation URLs, and directory of public endpoints.",
        "responses": {
          "200": {
            "description": "Studio metadata successfully retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StudioInfoResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "operationId": "getHealthStatus",
        "summary": "Get API health and service status",
        "description": "Returns operational status and uptime for Peak Studios web services, database connectivity, and API gateway.",
        "responses": {
          "200": {
            "description": "Service is operational.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scripts": {
      "get": {
        "operationId": "listPublicScripts",
        "summary": "List public FiveM scripts and resources",
        "description": "Returns a list of all official Peak Studios FiveM resources with framework compatibility, dependencies, and repository URLs.",
        "parameters": [
          {
            "name": "framework",
            "in": "query",
            "required": false,
            "description": "Filter scripts by framework (e.g., 'QBCore', 'ESX', 'QBX', 'Standalone')",
            "schema": {
              "type": "string",
              "enum": ["QBCore", "ESX", "QBX", "Standalone", "Custom"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of scripts successfully retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScriptsListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scripts/{id}": {
      "get": {
        "operationId": "getScriptById",
        "summary": "Get documentation and metadata for a specific script",
        "description": "Returns detailed metadata and raw markdown documentation for an official Peak Studios resource by its script identifier.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The unique script slug (e.g. 'peak-sprays', 'peak-trucking', 'peak-barbers', 'peak-chess', 'peak-ai-npc', 'peak-pedmanager')",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Script documentation retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScriptDetailResponse"
                }
              }
            }
          },
          "404": {
            "description": "Script not found in catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/github/stats": {
      "get": {
        "operationId": "getStudioStats",
        "summary": "Get public GitHub statistics and stars",
        "description": "Returns the aggregate star count and total open source repository count across the Peak-Studios GitHub organization.",
        "responses": {
          "200": {
            "description": "GitHub telemetry retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GitHubStats"
                }
              }
            }
          }
        }
      }
    },
    "/api/plans/public": {
      "get": {
        "operationId": "getPublicRoadmap",
        "summary": "Get active public development roadmap",
        "description": "Retrieves the latest public development plan and feature milestones.",
        "responses": {
          "200": {
            "description": "Roadmap retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicPlanResponse"
                }
              }
            }
          },
          "404": {
            "description": "No active public plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/tags": {
      "get": {
        "operationId": "listTags",
        "summary": "List categorization tags for scripts and issues",
        "description": "Returns available category tags used across the Peak Studios ecosystem.",
        "responses": {
          "200": {
            "description": "Tags retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TagsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "operationId": "submitContactInquiry",
        "summary": "Submit project inquiry or developer message",
        "description": "Accepts contact requests and project commission inquiries. Dispatches a notification to the Peak Studios developer team.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactInquiryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Inquiry accepted and scheduled for developer review.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactInquiryResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error on submitted fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (5 requests per 10 minutes).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "operationId": "executeMcpJsonRpc",
        "summary": "Execute Model Context Protocol JSON-RPC 2.0 requests",
        "description": "Streamable HTTP MCP endpoint allowing AI agents (Claude, ChatGPT, Cursor, Copilot) to invoke Peak Studios tools (list_scripts, get_script_docs, search_docs, get_system_status, get_openapi_spec, get_agent_guidance).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/McpJsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response with tool output or capability manifest.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpJsonRpcResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON-RPC request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpJsonRpcError"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "getMcpManifest",
        "summary": "Get Model Context Protocol server manifest or establish SSE stream",
        "description": "Returns tool directory and server capabilities when requested via HTTP GET. If Accept header contains text/event-stream, initiates an MCP SSE connection.",
        "responses": {
          "200": {
            "description": "MCP server manifest.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpManifest"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "object",
            "required": ["code", "message", "hint", "status"],
            "properties": {
              "code": {
                "type": "string",
                "example": "VALIDATION_ERROR"
              },
              "message": {
                "type": "string",
                "example": "Invalid contact submission parameters."
              },
              "hint": {
                "type": "string",
                "example": "Verify name, email, projectType, and message meet length and format constraints."
              },
              "status": {
                "type": "integer",
                "example": 400
              },
              "details": {
                "type": "object",
                "description": "Optional validation error list or context."
              }
            }
          }
        }
      },
      "StudioInfoResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "name": { "type": "string", "example": "Peak Studios" },
              "tagline": { "type": "string", "example": "High-Performance FiveM Scripts & Roleplay Infrastructure" },
              "description": { "type": "string" },
              "website": { "type": "string", "example": "https://peakrp.net" },
              "frameworks": {
                "type": "array",
                "items": { "type": "string" },
                "example": ["QBCore", "ESX", "QBX", "Standalone"]
              },
              "socials": {
                "type": "object",
                "properties": {
                  "github": { "type": "string" },
                  "discord": { "type": "string" },
                  "instagram": { "type": "string" }
                }
              },
              "protocols": {
                "type": "object",
                "properties": {
                  "openapi": { "type": "string" },
                  "mcp": { "type": "string" },
                  "llmsTxt": { "type": "string" },
                  "sitemap": { "type": "string" }
                }
              }
            }
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "status": { "type": "string", "example": "healthy" },
              "uptimeSeconds": { "type": "integer", "example": 3600 },
              "timestamp": { "type": "string", "format": "date-time" },
              "services": {
                "type": "object",
                "properties": {
                  "web": { "type": "string", "example": "operational" },
                  "database": { "type": "string", "example": "operational" },
                  "mcp": { "type": "string", "example": "operational" }
                }
              }
            }
          }
        }
      },
      "ScriptsListResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "name", "description", "repository", "frameworkCompatibility"],
              "properties": {
                "id": { "type": "string", "example": "peak-sprays" },
                "name": { "type": "string", "example": "Peak Sprays" },
                "description": { "type": "string", "example": "High performance graffiti and turf spraying system." },
                "repository": { "type": "string", "example": "https://github.com/Peak-Studios/peak-sprays" },
                "frameworkCompatibility": {
                  "type": "array",
                  "items": { "type": "string" },
                  "example": ["QBCore", "ESX", "QBX"]
                },
                "dependencies": {
                  "type": "array",
                  "items": { "type": "string" },
                  "example": ["ox_lib", "oxmysql"]
                },
                "docsUrl": { "type": "string", "example": "https://peakrp.net/docs/peak-sprays" }
              }
            }
          }
        }
      },
      "ScriptDetailResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "id": { "type": "string", "example": "peak-sprays" },
              "name": { "type": "string", "example": "Peak Sprays" },
              "description": { "type": "string" },
              "repository": { "type": "string" },
              "frameworkCompatibility": { "type": "array", "items": { "type": "string" } },
              "docsUrl": { "type": "string" },
              "rawMarkdown": { "type": "string", "nullable": true }
            }
          }
        }
      },
      "GitHubStats": {
        "type": "object",
        "required": ["totalStars", "totalRepos", "success"],
        "properties": {
          "totalStars": { "type": "integer", "example": 78 },
          "totalRepos": { "type": "integer", "example": 11 },
          "success": { "type": "boolean", "example": true }
        }
      },
      "PublicPlanResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "title": { "type": "string" },
              "description": { "type": "string" },
              "canvasState": { "type": "object" },
              "updatedAt": { "type": "string", "format": "date-time" }
            }
          }
        }
      },
      "TagsResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "tags": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "name": { "type": "string" },
                    "color": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      },
      "ContactInquiryRequest": {
        "type": "object",
        "required": ["name", "email", "projectType", "message"],
        "properties": {
          "name": { "type": "string", "minLength": 2, "maxLength": 80, "example": "Alex Rivers" },
          "email": { "type": "string", "format": "email", "example": "alex@example.com" },
          "projectType": { "type": "string", "minLength": 1, "maxLength": 80, "example": "Custom FiveM Script" },
          "message": { "type": "string", "minLength": 10, "maxLength": 2000, "example": "Looking for bespoke FiveM banking and heist script integration." }
        }
      },
      "ContactInquiryResponse": {
        "type": "object",
        "required": ["success", "data"],
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "received": { "type": "boolean", "example": true },
              "delivered": { "type": "boolean", "example": true },
              "message": { "type": "string", "example": "Your message has been submitted successfully." }
            }
          }
        }
      },
      "McpJsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"], "example": "2.0" },
          "id": { "type": ["string", "number", "null"], "example": 1 },
          "method": { "type": "string", "example": "tools/call" },
          "params": {
            "type": "object",
            "properties": {
              "name": { "type": "string", "example": "list_scripts" },
              "arguments": { "type": "object" }
            }
          }
        }
      },
      "McpJsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc"],
        "properties": {
          "jsonrpc": { "type": "string", "example": "2.0" },
          "id": { "type": ["string", "number", "null"], "example": 1 },
          "result": { "type": "object" },
          "error": { "$ref": "#/components/schemas/McpJsonRpcError" }
        }
      },
      "McpJsonRpcError": {
        "type": "object",
        "required": ["code", "message"],
        "properties": {
          "code": { "type": "integer", "example": -32601 },
          "message": { "type": "string", "example": "Method not found" }
        }
      },
      "McpManifest": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "example": "peak-studios-mcp-server" },
          "version": { "type": "string", "example": "1.0.0" },
          "protocol": { "type": "string", "example": "mcp/1.0" },
          "tools": { "type": "array", "items": { "type": "object" } }
        }
      }
    }
  }
}