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.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'