openapi: 3.1.0
info:
  title: "Dr. Amit Puri Public API (amitpuri)"
  version: "1.0.0"
  description: >
    Official public REST API, developer resources, and agent tools for Dr. Amit Puri (amitpuri).
    Provides structured programmatic endpoints for executive bio, advisory services, publications,
    health checks, and deprecation policies. Official developer resources for amitpuri include
    OpenAPI 3.1.0 specifications, authentication guides, webhooks, Model Context Protocol (MCP) server,
    CLI tools, and LLM context files.
  contact:
    name: Dr. Amit Puri
    email: info@amitpuri.com
    url: https://www.amitpuri.com/developers
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  x-api-version: "1.0.0"
  x-versioning-strategy: >
    URL path versioning (/v1/, /v2/) and API-Version header parameter. The current stable release is v1,
    available under /api/v1/* and aliased at /api/*.
  x-deprecation-policy: >
    Deprecated endpoints will carry a Sunset header (RFC 8594) indicating the removal date
    and a Deprecation header (RFC 9745) with a deprecation timestamp. Deprecation policy page is published
    at https://www.amitpuri.com/deprecation with a minimum 90-day transition notice.
  x-rate-limit-policy: >
    60 requests per minute per IP. Requests exceeding the limit receive a 429 Too Many Requests response
    with a Retry-After header. Headers RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy
    are returned on all API responses.
  x-developer-resources:
    developer-portal: https://www.amitpuri.com/developers
    openapi-json: https://www.amitpuri.com/openapi.json
    openapi-yaml: https://www.amitpuri.com/openapi.yaml
    auth-docs: https://www.amitpuri.com/developers#auth
    webhooks-docs: https://www.amitpuri.com/developers#webhooks
    mcp-server: https://www.amitpuri.com/developers#mcp
    mcp-manifest: https://www.amitpuri.com/.well-known/mcp.json
    cli-tool: "npx @amitpuri/cli"
    deprecation-policy: https://www.amitpuri.com/deprecation
    llms-txt: https://www.amitpuri.com/llms.txt
    agent-instructions: https://www.amitpuri.com/agent-instructions.md

servers:
  - url: https://www.amitpuri.com/api/v1
    description: Versioned Production Server (v1 — current stable)
  - url: https://www.amitpuri.com/api
    description: Production Server (latest stable v1 aliased)
  - url: https://www.amitpuri.com
    description: Root Server

components:
  parameters:
    ApiVersionHeader:
      name: API-Version
      in: header
      description: "API version string (e.g. 'v1'). Defaults to latest stable version (v1)."
      required: false
      schema:
        type: string
        default: "v1"
        enum:
          - "v1"
          - "1.0.0"
    XApiVersionHeader:
      name: X-API-Version
      in: header
      description: "Custom API version header."
      required: false
      schema:
        type: string
        default: "1.0.0"
    FormatQuery:
      name: format
      in: query
      description: "Desired response representation format. Defaults to 'json'."
      required: false
      schema:
        type: string
        default: json
        enum:
          - json

  schemas:
    Problem:
      type: object
      description: RFC 9457 application/problem+json error model. Returned on all 4xx and 5xx responses.
      properties:
        type:
          type: string
          format: uri
          description: A URI reference that identifies the problem type.
          example: https://www.amitpuri.com/api/errors/not-found
        title:
          type: string
          description: A short, human-readable summary of the problem type.
          example: Not Found
        status:
          type: integer
          description: The HTTP status code.
          example: 404
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          example: The requested resource was not found.
        instance:
          type: string
          format: uri
          description: A URI reference that identifies the specific occurrence of the problem.
          example: /api/nonexistent
        code:
          type: string
          description: A unique, machine-readable error code for programmatic handling.
          example: API_ENDPOINT_NOT_FOUND
        invalid_params:
          type: array
          description: If applicable, a list of invalid parameters causing the error.
          items:
            type: object
            properties:
              name:
                type: string
                description: Parameter name
              reason:
                type: string
                description: Reason parameter is invalid
            required:
              - name
              - reason
      required:
        - type
        - title
        - status
        - detail
        - instance
        - code

    Error:
      $ref: '#/components/schemas/Problem'

    SocialLinks:
      type: object
      description: Verified social profiles for Dr. Amit Puri
      properties:
        twitter:
          type: string
          format: uri
          description: Twitter/X handle URL
          example: https://twitter.com/iamamitpuri
        github:
          type: string
          format: uri
          description: GitHub profile URL
          example: https://github.com/amitpuri
        linkedin:
          type: string
          format: uri
          description: LinkedIn profile URL
          example: https://linkedin.com/in/amitpuri

    Profile:
      type: object
      description: Executive profile and professional bio for Dr. Amit Puri
      properties:
        name:
          type: string
          example: Dr. Amit Puri
          description: Full professional name
        title:
          type: string
          example: Enterprise Cloud & AI Architect, Author, Advisor
          description: Professional title and primary advisory roles
        bio:
          type: string
          description: Executive biography summarizing 25+ years experience in enterprise architecture and AI transformation
          example: Executive Cloud & AI Architect, Author, and Advisor helping organizations modernize enterprise architectures with AI.
        email:
          type: string
          format: email
          example: info@amitpuri.com
          description: Primary verified contact email
        website:
          type: string
          format: uri
          example: https://www.amitpuri.com
          description: Official website URL
        booking_url:
          type: string
          format: uri
          example: https://topmate.io/amitpuri
          description: Direct Topmate booking hub URL
        social:
          $ref: '#/components/schemas/SocialLinks'
        expertise:
          type: array
          description: List of core subject matter expertise and advisory domains
          items:
            type: string
          example:
            - Enterprise Cloud Architecture
            - AI Transformation
            - Citizen Development
            - Design Patterns
        experience_years:
          type: integer
          example: 25
          description: Total cumulative years of professional technology experience
      required:
        - name
        - title
        - bio
        - email
        - website
        - booking_url
        - expertise
        - experience_years

    ServiceItem:
      type: object
      description: Individual advisory or mentorship offering
      properties:
        id:
          type: string
          description: Unique service identifier
          example: ai-transformation-advice
        title:
          type: string
          description: Service title
          example: AI Transformation Advice
        type:
          type: string
          description: Engagement type (e.g. Advisory, Mentorship, Strategy)
          example: Advisory
        description:
          type: string
          description: Summary of what is covered in the session
          example: Expert consultation on enterprise AI strategy and multi-agent implementation.
        booking_url:
          type: string
          format: uri
          description: Direct Topmate URL to book this specific session
          example: https://topmate.io/amitpuri/858803
      required:
        - id
        - title
        - type
        - description
        - booking_url

    ServicesResponse:
      type: object
      description: Catalog of advisory services and booking URLs for Dr. Amit Puri
      properties:
        provider:
          type: string
          example: Dr. Amit Puri (amitpuri)
          description: Provider name
        booking_hub:
          type: string
          format: uri
          example: https://topmate.io/amitpuri
          description: Canonical booking hub URL
        services:
          type: array
          description: List of available consultation offerings
          items:
            $ref: '#/components/schemas/ServiceItem'
      required:
        - provider
        - booking_hub
        - services

    ProjectItem:
      type: object
      description: Initiative or open publication item
      properties:
        id:
          type: string
          description: Unique initiative identifier
          example: openagi
        name:
          type: string
          description: Initiative title
          example: Open AGI
        tagline:
          type: string
          description: Key focus or mission statement
          example: Democratizing Artificial General Intelligence and Agentic Architectures
        url:
          type: string
          format: uri
          description: Canonical project URL
          example: https://www.amitpuri.com/openagi
        category:
          type: string
          description: Focus domain
          example: AI & Agentic Systems
      required:
        - id
        - name
        - tagline
        - url
        - category

    ProjectsResponse:
      type: object
      description: Portfolio of key initiatives, research publications, and open platforms
      properties:
        provider:
          type: string
          example: Dr. Amit Puri (amitpuri)
          description: Provider name
        initiatives:
          type: array
          description: List of published initiatives and knowledge bases
          items:
            $ref: '#/components/schemas/ProjectItem'
      required:
        - provider
        - initiatives

    HealthResponse:
      type: object
      description: API health check, active versioning, and documentation index
      properties:
        status:
          type: string
          example: healthy
          description: Service operational status
        service:
          type: string
          example: amitpuri.com Public API
          description: Service name
        version:
          type: string
          example: 1.0.0
          description: Semantic version
        api_version:
          type: string
          example: v1
          description: Active API path version
        timestamp:
          type: string
          description: ISO 8601 status timestamp
          example: 2026-08-22T00:00:00Z
        docs:
          type: string
          format: uri
          example: https://www.amitpuri.com/openapi.json
          description: OpenAPI specification URL
        developer_portal:
          type: string
          format: uri
          example: https://www.amitpuri.com/developers
          description: Developer portal URL
      required:
        - status
        - service
        - version
        - api_version

    DeprecationPolicy:
      type: object
      description: Detailed deprecation signaling standards and timeline guarantees
      properties:
        minimum_notice_days:
          type: integer
          example: 90
          description: Minimum advance notice period in days before removing a deprecated endpoint
        sunset_header:
          type: string
          example: Sunset (RFC 8594)
          description: Header communicating endpoint retirement date
        deprecation_header:
          type: string
          example: Deprecation (RFC 9745)
          description: Header communicating deprecation effective timestamp
        link_header:
          type: string
          example: Link (RFC 8288) rel="deprecation"
          description: Link header pointing to successor documentation
        policy_url:
          type: string
          format: uri
          example: https://www.amitpuri.com/deprecation
          description: Canonical HTML deprecation policy page
        markdown_policy_url:
          type: string
          format: uri
          example: https://www.amitpuri.com/deprecation.md
          description: Markdown deprecation policy URL
        developer_portal:
          type: string
          format: uri
          example: https://www.amitpuri.com/developers
          description: Developer portal URL
        openapi_spec:
          type: string
          format: uri
          example: https://www.amitpuri.com/openapi.json
          description: OpenAPI spec URL
      required:
        - minimum_notice_days
        - sunset_header
        - deprecation_header
        - policy_url
        - developer_portal
        - openapi_spec

    DeprecationResponse:
      type: object
      description: API Versioning and Deprecation Policy response payload
      properties:
        service:
          type: string
          example: Dr. Amit Puri Public API (amitpuri)
          description: Service name
        active_version:
          type: string
          example: v1
          description: Current active major API release
        versioning_strategy:
          type: string
          example: URL path versioning (/v1/, /v2/) and API-Version header parameter.
          description: Strategy description
        deprecation_policy:
          $ref: '#/components/schemas/DeprecationPolicy'
      required:
        - service
        - active_version
        - versioning_strategy
        - deprecation_policy

  headers:
    RateLimit-Limit:
      description: Maximum number of requests allowed per 60-second window.
      schema:
        type: integer
        example: 60
    RateLimit-Remaining:
      description: Number of requests remaining in the current window.
      schema:
        type: integer
        example: 59
    RateLimit-Reset:
      description: Seconds or timestamp until the rate-limit window resets.
      schema:
        type: integer
        example: 0
    RateLimit-Policy:
      description: "Rate limit policy specification (quota;w=window_seconds)."
      schema:
        type: string
        example: "60;w=60"
    Retry-After:
      description: Number of seconds to wait before retrying a rate-limited request.
      schema:
        type: integer
        example: 60
    API-Version:
      description: Current active API version string.
      schema:
        type: string
        example: "v1"
    Sunset:
      description: RFC 8594 Sunset date when a deprecated endpoint will be removed.
      schema:
        type: string
        example: "Wed, 11 Nov 2026 00:00:00 GMT"
    Deprecation:
      description: RFC 9745 Deprecation date when an endpoint was marked deprecated.
      schema:
        type: string
        example: "@1762819200"

  responses:
    BadRequest:
      description: Bad Request (RFC 9457). The request parameters were malformed or invalid.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://www.amitpuri.com/api/errors/bad-request
            title: Bad Request
            status: 400
            detail: The request parameters were invalid.
            instance: /api/profile.json
            code: BAD_REQUEST
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'

    Unauthorized:
      description: Unauthorized (RFC 9457). Valid Bearer Token required for private or webhook endpoints.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://www.amitpuri.com/api/errors/unauthorized
            title: Unauthorized
            status: 401
            detail: Authentication required. Provide a valid Bearer Token.
            instance: /api/private
            code: UNAUTHORIZED
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'

    Forbidden:
      description: Forbidden (RFC 9457). The authenticated user or agent does not have access to this resource.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://www.amitpuri.com/api/errors/forbidden
            title: Forbidden
            status: 403
            detail: Access to the requested resource is denied.
            instance: /api/restricted
            code: FORBIDDEN
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'

    NotFound:
      description: Resource Not Found (RFC 9457).
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://www.amitpuri.com/api/errors/not-found
            title: Not Found
            status: 404
            detail: The requested API endpoint does not exist on amitpuri.com.
            instance: /api/nonexistent
            code: API_ENDPOINT_NOT_FOUND
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'

    TooManyRequests:
      description: Rate Limit Exceeded (RFC 9457). Self-throttle using Retry-After header.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://www.amitpuri.com/api/errors/rate-limit-exceeded
            title: Too Many Requests
            status: 429
            detail: Rate limit of 60 requests per minute exceeded. Please self-throttle.
            instance: /api/health.json
            code: RATE_LIMIT_EXCEEDED
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'

    InternalServerError:
      description: Internal Server Error (RFC 9457).
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://www.amitpuri.com/api/errors/internal-server-error
            title: Internal Server Error
            status: 500
            detail: An unexpected error occurred. Please contact info@amitpuri.com.
            instance: /api/health.json
            code: INTERNAL_SERVER_ERROR
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'

    DefaultError:
      description: Default unexpected error response (RFC 9457).
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'

paths:
  /api/profile.json:
    get:
      summary: Get Profile & Bio (Dr. Amit Puri)
      description: Retrieves verified professional biography, titles, social media channels, expertise domains, and booking coordinates for Dr. Amit Puri (amitpuri). Suitable for agent tool calls and entity resolution.
      operationId: getProfile
      parameters:
        - $ref: '#/components/parameters/ApiVersionHeader'
        - $ref: '#/components/parameters/FormatQuery'
        - name: fields
          in: query
          description: Optional comma-separated list of profile fields to retrieve (e.g. 'name,title,bio,expertise,booking_url').
          required: false
          schema:
            type: string
            example: name,title,bio,booking_url
      responses:
        '200':
          description: Successful profile response
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'

  /api/v1/profile.json:
    get:
      summary: Get Profile & Bio (v1 Stable)
      description: Versioned endpoint returning executive bio, contact endpoints, and expertise for Dr. Amit Puri (amitpuri).
      operationId: getProfileV1
      parameters:
        - $ref: '#/components/parameters/FormatQuery'
        - name: fields
          in: query
          description: Optional comma-separated list of profile fields to retrieve.
          required: false
          schema:
            type: string
            example: name,title,bio,booking_url
      responses:
        '200':
          description: Successful profile response
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'

  /api/services.json:
    get:
      summary: List Advisory Services & Bookings
      description: Returns full catalog of advisory sessions, 1:1 mentorship bookings, workshops, and direct Topmate booking URLs for Dr. Amit Puri (amitpuri).
      operationId: getServices
      parameters:
        - $ref: '#/components/parameters/ApiVersionHeader'
        - $ref: '#/components/parameters/FormatQuery'
        - name: category
          in: query
          description: Filter services by category type (e.g. 'all', 'advisory', 'mentorship', 'cloud', 'ai').
          required: false
          schema:
            type: string
            default: all
            enum:
              - all
              - advisory
              - mentorship
              - cloud
              - ai
      responses:
        '200':
          description: List of advisory offerings
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'

  /api/v1/services.json:
    get:
      summary: List Advisory Services (v1 Stable)
      description: Versioned endpoint returning advisory catalog and booking URLs for Dr. Amit Puri.
      operationId: getServicesV1
      parameters:
        - $ref: '#/components/parameters/FormatQuery'
        - name: category
          in: query
          description: Filter services by category type.
          required: false
          schema:
            type: string
            default: all
            enum:
              - all
              - advisory
              - mentorship
              - cloud
              - ai
      responses:
        '200':
          description: List of advisory offerings
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'

  /api/projects.json:
    get:
      summary: List Key Initiatives & Portfolios
      description: Returns open initiatives, research knowledge bases (Open AGI, Citizen Developer, Open Cloud, designpattern.fyi), and published books for Dr. Amit Puri (amitpuri).
      operationId: getProjects
      parameters:
        - $ref: '#/components/parameters/ApiVersionHeader'
        - $ref: '#/components/parameters/FormatQuery'
        - name: category
          in: query
          description: Filter initiatives by category (e.g. 'all', 'ai', 'governance', 'cloud', 'patterns').
          required: false
          schema:
            type: string
            default: all
            enum:
              - all
              - ai
              - governance
              - cloud
              - patterns
      responses:
        '200':
          description: List of initiatives
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'

  /api/v1/projects.json:
    get:
      summary: List Key Initiatives (v1 Stable)
      description: Versioned endpoint returning portfolio initiatives and publications for Dr. Amit Puri.
      operationId: getProjectsV1
      parameters:
        - $ref: '#/components/parameters/FormatQuery'
        - name: category
          in: query
          description: Filter initiatives by category.
          required: false
          schema:
            type: string
            default: all
            enum:
              - all
              - ai
              - governance
              - cloud
              - patterns
      responses:
        '200':
          description: List of initiatives
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'

  /api/health.json:
    get:
      summary: API Service Health Check
      description: Returns operational health status, active API version, timestamp, and developer resource links for amitpuri.com.
      operationId: getHealth
      parameters:
        - $ref: '#/components/parameters/ApiVersionHeader'
        - $ref: '#/components/parameters/FormatQuery'
        - name: check
          in: query
          description: Optional component check identifier (e.g. 'all', 'ping', 'version').
          required: false
          schema:
            type: string
            default: all
            enum:
              - all
              - ping
              - version
      responses:
        '200':
          description: Service health status
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'

  /api/v1/health.json:
    get:
      summary: API Health Check (v1 Stable)
      description: Versioned endpoint returning API operational health and version metadata.
      operationId: getHealthV1
      parameters:
        - $ref: '#/components/parameters/FormatQuery'
        - name: check
          in: query
          description: Optional component check identifier.
          required: false
          schema:
            type: string
            default: all
            enum:
              - all
              - ping
              - version
      responses:
        '200':
          description: Service health status
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'

  /api/deprecation.json:
    get:
      summary: API Versioning & Deprecation Policy
      description: Retrieves official semantic versioning roadmap, Sunset/Deprecation header specifications, and 90-day grace period policies for amitpuri APIs.
      operationId: getDeprecationPolicy
      parameters:
        - $ref: '#/components/parameters/ApiVersionHeader'
        - $ref: '#/components/parameters/FormatQuery'
      responses:
        '200':
          description: Versioning and deprecation policy document
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeprecationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'

  /api/v1/deprecation.json:
    get:
      summary: API Versioning & Deprecation Policy (v1 Stable)
      description: Versioned endpoint returning API deprecation and version lifecycle policies for Dr. Amit Puri.
      operationId: getDeprecationPolicyV1
      parameters:
        - $ref: '#/components/parameters/FormatQuery'
      responses:
        '200':
          description: Versioning and deprecation policy document
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeprecationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'

  /api/404.json:
    get:
      summary: RFC 9457 API Not Found Error Demonstration
      description: Demonstration error endpoint returning an RFC 9457 Problem Details error payload with machine-readable error codes.
      operationId: getApiNotFound
      parameters:
        - $ref: '#/components/parameters/FormatQuery'
      responses:
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'

  /llms.txt:
    get:
      summary: LLM Context Guidance File
      description: Standardized llmstxt.org markdown guidance file for AI agents, multi-agent systems, and LLMs.
      operationId: getLlmsTxt
      parameters:
        - name: Accept
          in: header
          description: Requested media type (e.g. text/plain).
          required: false
          schema:
            type: string
            default: text/plain
      responses:
        '200':
          description: Raw text/plain llms.txt content
          content:
            text/plain:
              schema:
                type: string
                description: UTF-8 Markdown text per llmstxt.org specification
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'