{
  "openapi": "3.1.0",
  "info": {
    "title": "Sandeep Gautam Portfolio API",
    "version": "1.0.0",
    "description": "Public API for Sandeep Gautam — Front-End Developer & UI Specialist in Cyprus. Provides programmatic access to project case studies, blog articles, developer tools, contact services, and MCP server tools.",
    "contact": {
      "name": "Sandeep Gautam",
      "email": "bagosandeep@gmail.com",
      "url": "https://www.sandeep-gautam.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://www.sandeep-gautam.com",
      "description": "Production server"
    },
    {
      "url": "http://localhost:3001",
      "description": "Local development server"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "operationId": "getHealthStatus",
        "summary": "Check API health status",
        "description": "Returns operational status and timestamp of the portfolio API server.",
        "responses": {
          "200": {
            "description": "API server is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "timestamp": { "type": "string", "format": "date-time" },
                    "uptime": { "type": "number" }
                  },
                  "required": ["status", "timestamp"]
                }
              }
            }
          }
        }
      }
    },
    "/api/projects": {
      "get": {
        "operationId": "listProjects",
        "summary": "List client projects and case studies",
        "description": "Retrieves portfolio case studies including tech stack, features, live links, and descriptions.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter projects by tag (e.g. web, saas, mobile, ecommerce)",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of portfolio projects",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "projects": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Project" }
                    }
                  },
                  "required": ["projects"]
                }
              }
            }
          }
        }
      }
    },
    "/api/projects/{slug}": {
      "get": {
        "operationId": "getProjectBySlug",
        "summary": "Get project detail by slug",
        "description": "Retrieves full details for a specific project case study.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Unique identifier of the project (e.g. nikolas-lawyer-booking, clipboard-sync)",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Project details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "project": { "$ref": "#/components/schemas/Project" }
                  },
                  "required": ["project"]
                }
              }
            }
          },
          "404": {
            "description": "Project not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/blog": {
      "get": {
        "operationId": "listBlogPosts",
        "summary": "List technical blog posts",
        "description": "Retrieves published technical blog articles about front-end architecture, web design, and PWAs.",
        "responses": {
          "200": {
            "description": "List of blog posts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "posts": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/BlogPost" }
                    }
                  },
                  "required": ["posts"]
                }
              }
            }
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "operationId": "submitContactForm",
        "summary": "Send a message to Sandeep Gautam",
        "description": "Submits a contact form message. Rate-limited to 5 submissions per 15 minutes per IP.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "minLength": 2, "maxLength": 100, "example": "Jane Doe" },
                  "email": { "type": "string", "format": "email", "example": "jane@example.com" },
                  "message": { "type": "string", "minLength": 10, "maxLength": 5000, "example": "Hi Sandeep, we would like to collaborate on a front-end project." },
                  "honeypot": { "type": "string", "description": "Spam prevention field. Must be left empty." }
                },
                "required": ["name", "email", "message"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message sent successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "example": true },
                    "message": { "type": "string", "example": "Message sent successfully." }
                  },
                  "required": ["success", "message"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "headers": {
              "Retry-After": {
                "schema": { "type": "integer" },
                "description": "Seconds until rate limit reset"
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "operationId": "callMcpTool",
        "summary": "Execute Model Context Protocol (MCP) tool",
        "description": "Allows AI agents to execute portfolio tools (search_portfolio, get_projects, send_inquiry).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "method": { "type": "string", "example": "tools/call" },
                  "params": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string", "example": "get_projects" },
                      "arguments": { "type": "object" }
                    },
                    "required": ["name"]
                  }
                },
                "required": ["method", "params"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "MCP tool execution response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "content": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": { "type": "string", "example": "text" },
                          "text": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/indexnow": {
      "post": {
        "operationId": "submitIndexNowUrls",
        "summary": "Submit URLs to IndexNow Protocol",
        "description": "Submits updated URLs for instant indexing across Bing, Yandex, Seznam, and Naver search engines.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "urlList": {
                    "type": "array",
                    "items": { "type": "string" },
                    "example": ["https://sandeep-gautam.com/about", "https://sandeep-gautam.com/work"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "URLs successfully submitted to IndexNow API",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "example": true },
                    "message": { "type": "string" },
                    "submittedUrls": { "type": "array", "items": { "type": "string" } },
                    "keyLocation": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Project": {
        "type": "object",
        "properties": {
          "slug": { "type": "string", "example": "nikolas-lawyer-booking" },
          "title": { "type": "string", "example": "Nikolas Leontides Legal Booking" },
          "description": { "type": "string", "example": "Responsive legal consultation booking platform." },
          "tags": { "type": "array", "items": { "type": "string" } },
          "url": { "type": "string", "example": "https://sandeep-gautam.com/work/nikolas-lawyer-booking" },
          "liveUrl": { "type": "string", "example": "https://leontideslaw.com" }
        },
        "required": ["slug", "title", "description", "tags"]
      },
      "BlogPost": {
        "type": "object",
        "properties": {
          "slug": { "type": "string", "example": "pwas-in-2026-outperforming-native-apps" },
          "title": { "type": "string", "example": "PWAs in 2026: Outperforming Native Apps" },
          "date": { "type": "string", "example": "2026-07-25" },
          "excerpt": { "type": "string" },
          "url": { "type": "string" }
        },
        "required": ["slug", "title", "date", "excerpt"]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string", "example": "BAD_REQUEST" },
              "message": { "type": "string", "example": "Validation failed" },
              "hint": { "type": "string", "example": "Check required parameters" }
            },
            "required": ["code", "message"]
          }
        },
        "required": ["error"]
      }
    }
  }
}