openapi: 3.0.3
info:
  title: HMorix Enterprise Platform API
  version: 2.4.0
  description: "The official REST API for HMorix Enterprise Cloud Platform. Provides endpoints for AI agent automation, BillingFlow invoicing, public services, contact submissions, blogs, recruitment, and developer tools. Fully typed and optimized for LLM function calling and agent integration."
  contact:
    name: HMorix Developer Support
    email: "support@hmorix.com"
    url: "https://hmorix.in/developers"
  license:
    name: MIT
    url: "https://opensource.org/licenses/MIT"
servers:
  - url: "https://hmorix.in/api"
    description: Production API Gateway
tags:
  - name: System
    description: "Platform health, status, and configuration"
  - name: AI Agent
    description: Enterprise AI workflows and LLM chat completions
  - name: Services
    description: HMorix professional services and catalog
  - name: Contact
    description: "Public inquiries, lead generation, and client support"
  - name: Content
    description: "Blog articles, categories, and knowledge base"
  - name: Careers
    description: Job openings and talent acquisition
  - name: Authentication
    description: "User sessions, credentials, and email OTP verification"
  - name: Developer
    description: API keys and sandbox management
paths:
  /health:
    get:
      tags:
        - "System"
      summary: Check API health status
      description: "Returns operational connectivity status for the API gateway, MongoDB primary datastore, and Supabase auxiliary store."
      operationId: getHealthStatus
      responses:
        200:
          description: System health summary
          content:
            application/json:
              schema:
                : "#/components/schemas/HealthResponse"
  /status:
    get:
      tags:
        - "System"
      summary: Retrieve live platform component metrics
      description: "Returns uptime percentages, operational status, and latency benchmarks for all HMorix subsystems including BillingFlow, AI Agent Engine, PDF Processing, and Database Cluster."
      operationId: getSystemStatus
      responses:
        200:
          description: Platform status breakdown
          content:
            application/json:
              schema:
                : "#/components/schemas/StatusResponse"
  /services:
    get:
      tags:
        - "Services"
      summary: List enterprise software and agency services
      description: "Returns all active services offered by HMorix including AI & Machine Learning, Web Design, Mobile App Development, Digital Marketing, and Custom Software with starting prices."
      operationId: listServices
      responses:
        200:
          description: List of available services
          content:
            application/json:
              schema:
                : "#/components/schemas/ServicesResponse"
  /contact:
    post:
      tags:
        - "Contact"
      summary: Submit a business inquiry or consultation request
      description: Sends a message to HMorix sales and engineering teams. Automatically generates a CRM lead pipeline entry and notifies project triage.
      operationId: submitContactInquiry
      requestBody:
        required: true
        description: Contact inquiry payload
        content:
          application/json:
            schema:
              : "#/components/schemas/ContactRequest"
      responses:
        200:
          description: Inquiry accepted successfully
          content:
            application/json:
              schema:
                : "#/components/schemas/SuccessResponse"
        400:
          description: Invalid submission payload
          content:
            application/json:
              schema:
                : "#/components/schemas/ErrorResponse"
  /blogs:
    get:
      tags:
        - "Content"
      summary: List published blog articles
      description: "Retrieves published technical articles, engineering updates, and market insights with author metadata, tags, and reading times."
      operationId: listBlogPosts
      parameters:
        - name: page
          in: query
          required: false
          description: Page number for pagination (starts at 1)
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          required: false
          description: Maximum number of posts to return
          schema:
            type: integer
            default: 10
        - name: category
          in: query
          required: false
          description: Filter by article category slug
          schema:
            type: string
      responses:
        200:
          description: Paginated list of blog articles
          content:
            application/json:
              schema:
                : "#/components/schemas/BlogListResponse"
  /blog/{slug}:
    get:
      tags:
        - "Content"
      summary: Get article by slug
      description: "Retrieves the full markdown/HTML content, SEO metadata, and published timestamps for a specific blog post."
      operationId: getBlogPostBySlug
      parameters:
        - name: slug
          in: path
          required: true
          description: Unique URL slug of the blog article
          schema:
            type: string
      responses:
        200:
          description: Article details
          content:
            application/json:
              schema:
                : "#/components/schemas/BlogPostResponse"
        404:
          description: Article not found
          content:
            application/json:
              schema:
                : "#/components/schemas/ErrorResponse"
  /ai/status:
    get:
      tags:
        - "AI Agent"
      summary: Check AI agent engine status
      description: Returns operational status and active LLM models (e.g. NVIDIA NIM Llama 3.1 405B) for autonomous workflows.
      operationId: getAiEngineStatus
      responses:
        200:
          description: AI engine status
          content:
            application/json:
              schema:
                : "#/components/schemas/AiStatusResponse"
  /ai/chat:
    post:
      tags:
        - "AI Agent"
      summary: Send prompt to HMorix AI Assistant
      description: "Executes enterprise workflow automation, code generation, or customer support reasoning via HMorix AI orchestration."
      operationId: createAiChatCompletion
      requestBody:
        required: true
        description: Chat prompt message
        content:
          application/json:
            schema:
              : "#/components/schemas/AiChatRequest"
      responses:
        200:
          description: AI response generated
          content:
            application/json:
              schema:
                : "#/components/schemas/AiChatResponse"
        400:
          description: Bad request
          content:
            application/json:
              schema:
                : "#/components/schemas/ErrorResponse"
  /careers:
    get:
      tags:
        - "Careers"
      summary: List active career opportunities
      description: "Returns current job openings, engineering roles, and internship opportunities at HMorix."
      operationId: listCareers
      responses:
        200:
          description: Active job listings
          content:
            application/json:
              schema:
                : "#/components/schemas/CareersResponse"
  /auth/signin:
    post:
      tags:
        - "Authentication"
      summary: Sign in with email and password
      description: "Authenticates a registered user or employee and sets a signed HMAC-SHA256 session cookie ()."
      operationId: signInUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              : "#/components/schemas/SignInRequest"
      responses:
        200:
          description: Authentication successful
          content:
            application/json:
              schema:
                : "#/components/schemas/AuthUserResponse"
        401:
          description: Invalid credentials
          content:
            application/json:
              schema:
                : "#/components/schemas/ErrorResponse"
  /auth/me:
    get:
      tags:
        - "Authentication"
      summary: Get authenticated user profile
      description: "Returns user identity, active role (admin, manager, hr, employee, sales, user), and verification status for current session."
      operationId: getCurrentUser
      security:
        - SessionCookie:

        - BearerAuth:

      responses:
        200:
          description: Authenticated session profile
          content:
            application/json:
              schema:
                : "#/components/schemas/AuthUserResponse"
        401:
          description: Not authenticated
          content:
            application/json:
              schema:
                : "#/components/schemas/ErrorResponse"
  /account/api-keys:
    get:
      tags:
        - "Developer"
      summary: List developer API keys
      description: Returns masked API keys created by the current authenticated developer account.
      operationId: listApiKeys
      security:
        - SessionCookie:

        - BearerAuth:

      responses:
        200:
          description: List of active developer keys
          content:
            application/json:
              schema:
                : "#/components/schemas/ApiKeysResponse"
    post:
      tags:
        - "Developer"
      summary: Generate a new developer API key
      description: Creates a secure API key with configurable rate limits for programmatic automation and function calling.
      operationId: generateApiKey
      security:
        - SessionCookie:

        - BearerAuth:

      requestBody:
        required: true
        content:
          application/json:
            schema:
              : "#/components/schemas/CreateApiKeyRequest"
      responses:
        201:
          description: Key generated successfully
          content:
            application/json:
              schema:
                : "#/components/schemas/ApiKeyCreatedResponse"
components:
  securitySchemes:
    SessionCookie:
      type: apiKey
      in: cookie
      name: hm_session
      description: "Signed HMAC-SHA256 session cookie"
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT / HMKey
      description: API key generated in Developer Portal or JWT authorization token
  schemas:
    HealthResponse:
      type: object
      required:
        - "success"
        - "status"
        - "timestamp"
      properties:
        success:
          type: boolean
          example: true
        status:
          type: object
          required:
            - "api"
            - "mongodb"
            - "supabase"
          properties:
            api:
              type: boolean
              example: true
            mongodb:
              type: boolean
              example: true
            supabase:
              type: boolean
              example: true
        timestamp:
          type: string
          format: "date-time"
    StatusItem:
      type: object
      required:
        - "name"
        - "status"
        - "uptime"
        - "latency"
      properties:
        name:
          type: string
          example: API Gateway
        status:
          type: string
          example: operational
        uptime:
          type: number
          example: 99.99
        latency:
          type: string
          example: 12ms
    StatusResponse:
      type: object
      required:
        - "success"
        - "overall"
        - "services"
        - "lastUpdated"
      properties:
        success:
          type: boolean
          example: true
        overall:
          type: string
          example: operational
        services:
          type: array
          items:
            : "#/components/schemas/StatusItem"
        lastUpdated:
          type: string
          format: "date-time"
    ServiceItem:
      type: object
      required:
        - "id"
        - "name"
        - "category"
        - "description"
        - "startingPrice"
        - "popular"
      properties:
        id:
          type: string
          example: "ai-solutions"
        name:
          type: string
          example: "AI & Machine Learning"
        category:
          type: string
          example: AI
        description:
          type: string
          example: "Custom AI agents, NLP, computer vision solutions"
        startingPrice:
          type: number
          example: 9999
        popular:
          type: boolean
          example: true
    ServicesResponse:
      type: object
      required:
        - "success"
        - "data"
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            : "#/components/schemas/ServiceItem"
    ContactRequest:
      type: object
      required:
        - "first_name"
        - "email"
        - "message"
      properties:
        first_name:
          type: string
          maxLength: 80
          example: John
        last_name:
          type: string
          maxLength: 80
          example: Doe
        email:
          type: string
          format: email
          example: "john@company.com"
        service:
          type: string
          maxLength: 120
          example: "AI Agents & Autonomous Workflows"
        message:
          type: string
          maxLength: 2000
          example: We want to automate our enterprise invoice matching and customer support.
    SuccessResponse:
      type: object
      required:
        - "success"
        - "message"
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Thank you for contacting us. We will get back to you soon.
    ErrorResponse:
      type: object
      required:
        - "error"
      properties:
        error:
          type: string
          example: Invalid request parameter
        code:
          type: string
          example: BAD_REQUEST
    BlogPost:
      type: object
      required:
        - "slug"
        - "title"
        - "excerpt"
        - "category"
        - "publishedAt"
      properties:
        slug:
          type: string
          example: "what-is-hmorix-ai-solutions-guide"
        title:
          type: string
          example: "Enterprise AI Solutions: Architecture & Best Practices"
        excerpt:
          type: string
          example: A comprehensive architectural breakdown of autonomous enterprise agents...
        category:
          type: string
          example: "AI & Engineering"
        readingTime:
          type: number
          example: 6
        publishedAt:
          type: string
          format: "date-time"
    BlogListResponse:
      type: object
      required:
        - "success"
        - "data"
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            : "#/components/schemas/BlogPost"
        total:
          type: integer
          example: 24
    BlogPostResponse:
      type: object
      required:
        - "success"
        - "data"
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          required:
            - "slug"
            - "title"
            - "content"
          properties:
            slug:
              type: string
            title:
              type: string
            content:
              type: string
            publishedAt:
              type: string
              format: "date-time"
    AiStatusResponse:
      type: object
      required:
        - "success"
        - "model"
        - "status"
      properties:
        success:
          type: boolean
          example: true
        model:
          type: string
          example: "meta/llama-3.1-405b-instruct"
        status:
          type: string
          example: ready
    AiChatRequest:
      type: object
      required:
        - "message"
      properties:
        message:
          type: string
          example: Explain BillingFlow features and GST calculation support.
        conversationId:
          type: string
          example: conv_982431
    AiChatResponse:
      type: object
      required:
        - "success"
        - "reply"
      properties:
        success:
          type: boolean
          example: true
        reply:
          type: string
          example: HMorix BillingFlow automatically calculates Indian GST (CGST/SGST/IGST)...
    CareersResponse:
      type: object
      required:
        - "success"
        - "data"
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              title:
                type: string
              department:
                type: string
              location:
                type: string
              type:
                type: string
    SignInRequest:
      type: object
      required:
        - "email"
        - "password"
      properties:
        email:
          type: string
          format: email
          example: "dev@company.com"
        password:
          type: string
          format: password
          example: "SecretPass123!"
    AuthUserResponse:
      type: object
      required:
        - "success"
        - "user"
      properties:
        success:
          type: boolean
          example: true
        user:
          type: object
          required:
            - "id"
            - "email"
            - "name"
            - "role"
          properties:
            id:
              type: string
            email:
              type: string
            name:
              type: string
            role:
              type: string
              enum:
                - "admin"
                - "manager"
                - "hr"
                - "employee"
                - "sales"
                - "crm"
                - "user"
            emailVerified:
              type: boolean
    CreateApiKeyRequest:
      type: object
      required:
        - "name"
      properties:
        name:
          type: string
          example: Production Agent Pipeline
        rateLimit:
          type: integer
          default: 600
          description: Requests per minute limit
    ApiKeysResponse:
      type: object
      required:
        - "success"
        - "data"
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              maskedKey:
                type: string
                example: hm_live_••••••••3a9b
              createdAt:
                type: string
                format: "date-time"
    ApiKeyCreatedResponse:
      type: object
      required:
        - "success"
        - "apiKey"
        - "name"
      properties:
        success:
          type: boolean
          example: true
        name:
          type: string
        apiKey:
          type: string
          example: hm_live_8f7b3c2e1a90d45f6a7b8c9d0e
        note:
          type: string
          example: Store this key safely. It will not be shown again.