{
  "openapi": "3.1.0",
  "info": {
    "title": "Shriraj Patil Portfolio API",
    "version": "1.0.0",
    "description": "Public API and machine-readable endpoints for Shriraj Patil's developer portfolio, analytics dispatch, and AI agent interaction. API version: v1.0.0. Versioning: Semantic versioning via X-API-Version response header. Deprecation policy: deprecated endpoints emit Deprecation: true and Sunset headers with at least 90 days notice.",
    "contact": {
      "name": "Shriraj Patil",
      "email": "shriraj399@gmail.com",
      "url": "https://portfolio-shriraj.vercel.app"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "x-api-version": "1.0.0",
    "x-deprecation-policy": "Deprecated endpoints include Deprecation and Sunset response headers with at least 90 days advance notice. No endpoints are currently deprecated.",
    "x-rate-limit": {
      "limit": 60,
      "window": "60s",
      "headers": ["RateLimit-Limit", "RateLimit-Remaining", "RateLimit-Reset", "Retry-After"]
    }
  },
  "servers": [
    {
      "url": "https://portfolio-shriraj.vercel.app",
      "description": "Production Server"
    },
    {
      "url": "http://localhost:5173",
      "description": "Local Development Server"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "Portfolio Homepage / Machine-Readable Profile",
        "description": "Returns HTML for standard browsers or clean Markdown for AI agents based on HTTP Accept content negotiation.",
        "operationId": "getPortfolioHome",
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "Media type preference. Use `text/markdown` for token-efficient agent consumption or `text/html` for human web browsing.",
            "schema": {
              "type": "string",
              "default": "text/html"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Portfolio content in the negotiated format.",
            "headers": {
              "Vary": {
                "description": "Informs caches that response varies by Accept and Accept-Encoding headers.",
                "schema": {
                  "type": "string",
                  "example": "Accept, Accept-Encoding"
                }
              }
            },
            "content": {
              "text/html": {
                "schema": {
                  "type": "string",
                  "description": "Complete HTML webpage with pre-rendered semantic DOM."
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string",
                  "description": "Clean Markdown document containing full developer bio, skills, projects, and contact info."
                }
              }
            }
          },
          "406": {
            "description": "Not Acceptable — The requested media type is not supported.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "summary": "LLM Context Index",
        "description": "Curated summary index of portfolio documentation and developer context conforming to the llmstxt.org standard.",
        "operationId": "getLlmsTxt",
        "responses": {
          "200": {
            "description": "LLM index in plain text markdown.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "summary": "Comprehensive LLM Context",
        "description": "Complete unabridged developer context for LLM agents including all project architectures, tech stacks, and career milestones.",
        "operationId": "getLlmsFullTxt",
        "responses": {
          "200": {
            "description": "Full LLM context markdown document.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "API Health Check and Discovery",
        "description": "Returns current API health status, available machine-readable endpoints, and portfolio metadata.",
        "operationId": "getApiHealth",
        "responses": {
          "200": {
            "description": "System health and discovery response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/notify": {
      "post": {
        "summary": "Telegram Visitor Analytics Dispatch",
        "description": "Serverless webhook that forwards visitor analytics signals and recruiter alerts to the portfolio owner.",
        "operationId": "postNotify",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NotifyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Notification dispatched successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request — Missing required message field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed — Only POST and OPTIONS methods are permitted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error or misconfigured server environment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "Bad Gateway — Upstream Telegram API failure.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "NotifyRequest": {
        "type": "object",
        "required": ["message"],
        "properties": {
          "message": {
            "type": "string",
            "description": "Telegram markdown formatted analytics message."
          },
          "type": {
            "type": "string",
            "description": "Event classification (e.g., 'recruiter_visit', 'page_view').",
            "example": "page_view"
          }
        }
      },
      "SuccessResponse": {
        "type": "object",
        "required": ["success"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "required": ["status", "service", "version", "endpoints"],
        "properties": {
          "status": {
            "type": "string",
            "example": "healthy"
          },
          "service": {
            "type": "string",
            "example": "shriraj-portfolio-api"
          },
          "version": {
            "type": "string",
            "example": "1.0.0"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "endpoints": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "ErrorDetail": {
        "type": "object",
        "required": ["code", "message", "status", "hint"],
        "properties": {
          "code": {
            "type": "string",
            "description": "Machine-readable error classification code.",
            "example": "BAD_REQUEST"
          },
          "message": {
            "type": "string",
            "description": "Human and agent readable error description.",
            "example": "Missing required field: 'message'."
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code.",
            "example": 400
          },
          "hint": {
            "type": "string",
            "description": "Actionable resolution advice for AI agents and clients.",
            "example": "Send a JSON payload with a 'message' string property."
          },
          "documentation_url": {
            "type": "string",
            "description": "Link to developer documentation for further details.",
            "example": "https://portfolio-shriraj.vercel.app/developers"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorDetail"
          }
        }
      }
    }
  }
}