openapi: 3.1.0
info:
  title: Growth Intel API & MCP Server
  description: >
    Growth Intel is an AI-powered revenue intelligence, omni-channel attribution, and B2B CRM engine.
    This document describes the REST API and Model Context Protocol (MCP) endpoints for autonomous agents, LLMs, and developer integrations.
  version: 1.0.0
  contact:
    name: Growth Intel Developer Support
    url: https://growthintel.net/docs
    email: contact@growthintel.net

servers:
  - url: https://growthintel.net
    description: Production Server

paths:
  /api:
    get:
      operationId: getApiCatalog
      summary: API Root Catalog & Health Status
      description: Returns API operational health status, versions, documentation links, and sandbox testing credentials.
      responses:
        '200':
          description: Operational health status and catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCatalogResponse'

  /api/v1:
    get:
      operationId: getApiV1Status
      summary: API v1 Service Catalog
      description: Returns active endpoints, MCP discovery URLs, and sandbox mode parameters for v1.
      responses:
        '200':
          description: Active v1 endpoints and capabilities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV1StatusResponse'

  /api/v1/leads:
    post:
      operationId: createLead
      summary: Ingest & Score Inbound Lead
      description: Ingests an inbound lead from an advertising platform (Meta, Google, TikTok), webhook, or web form. Triggers real-time intent scoring (0-100) and instant sales rep assignment.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLeadRequest'
      responses:
        '201':
          description: Lead successfully ingested and scored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadRecord'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'

  /api/v1/leads/semantic-search:
    get:
      operationId: searchLeadsSemantic
      summary: Semantic Search Across Leads
      description: Vector similarity search across lead context, tags, notes, and activity history using 1536-dimensional embeddings.
      security:
        - BearerAuth: []
      parameters:
        - name: q
          in: query
          required: true
          description: Natural language search query
          schema:
            type: string
            example: "High-intent healthcare prospects asking about CRM pricing"
      responses:
        '200':
          description: Ranked array of matching leads
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SemanticLeadMatch'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/webhooks/conversions:
    post:
      operationId: storeConversionFeedback
      summary: Ingest Closed Deal Conversion Signal
      description: Ingests offline conversion signals from external billing or CRM systems. Sends offline conversions back to Google Ads and Meta Ads to optimize smart bidding.
      security:
        - ConversionWebhookAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversionRequest'
      responses:
        '200':
          description: Conversion signal stored and forwarded
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Conversion feedback recorded successfully."
        '401':
          description: Unauthorized webhook request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /mcp/leads:
    post:
      operationId: mcpLeadsStream
      summary: Model Context Protocol (MCP) Stream
      description: Connects autonomous AI agents to the Growth Intel Lead Intelligence Server via Model Context Protocol (HTTP Stream / SSE).
      security:
        - BearerAuth: []
        - OAuth2: []
      responses:
        '200':
          description: Streamed MCP protocol response

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Tenant API Bearer token. For automated testing and sandbox exploration, use 'gi_sandbox_live_demo_key'.
    ConversionWebhookAuth:
      type: apiKey
      in: header
      name: X-Conversion-Secret
    OAuth2:
      type: oauth2
      description: MCP OAuth 2.0 Authorization Code flow
      flows:
        authorizationCode:
          authorizationUrl: https://growthintel.net/oauth/authorize
          tokenUrl: https://growthintel.net/oauth/token
          scopes:
            read:crm: Read CRM pipeline, lead scores, and ad attribution data

  schemas:
    ApiCatalogResponse:
      type: object
      required:
        - status
        - name
        - version
        - mcp_server
        - openapi_spec
        - documentation
      properties:
        status:
          type: string
          example: "operational"
        name:
          type: string
          example: "Growth Intel Revenue Intelligence API"
        version:
          type: string
          example: "1.0.0"
        mcp_server:
          type: string
          example: "https://growthintel.net/mcp/leads"
        openapi_spec:
          type: string
          example: "https://growthintel.net/openapi.json"
        openapi_yaml:
          type: string
          example: "https://growthintel.net/openapi.yaml"
        documentation:
          type: string
          example: "https://growthintel.net/docs"
        sandbox_token:
          type: string
          example: "gi_sandbox_live_demo_key"

    ApiV1StatusResponse:
      type: object
      required:
        - status
        - name
        - version
        - endpoints
      properties:
        status:
          type: string
          example: "operational"
        name:
          type: string
          example: "Growth Intel API v1"
        version:
          type: string
          example: "1.0.0"
        endpoints:
          type: object
          properties:
            leads:
              type: string
            semantic_search:
              type: string
            conversions:
              type: string
        mcp_server:
          type: string
        openapi_spec:
          type: string
        documentation:
          type: string
        sandbox_token:
          type: string

    CreateLeadRequest:
      type: object
      required:
        - source
      properties:
        source:
          type: string
          description: Lead channel source
          example: "meta_ads"
        campaign_id:
          type: string
          description: External campaign identifier
          example: "1202094829384"
        metadata:
          type: object
          description: Custom lead fields and behavioral attributes
          example:
            industry: "Healthcare"
            company_size: "50-200"
            interest: "revenue_radar"

    LeadRecord:
      type: object
      required:
        - id
        - status
        - intent_score
      properties:
        id:
          type: integer
          example: 1042
        status:
          type: string
          example: "new"
        intent_score:
          type: integer
          description: Real-time intent score between 0 and 100
          example: 87
        source:
          type: string
          example: "meta_ads"
        created_at:
          type: string
          format: date-time

    SemanticLeadMatch:
      type: object
      required:
        - id
        - similarity_score
      properties:
        id:
          type: integer
          example: 852
        similarity_score:
          type: number
          format: float
          example: 0.89
        status:
          type: string
          example: "contacted"
        budget_tier:
          type: string
          example: "growth"

    ConversionRequest:
      type: object
      required:
        - lead_id
        - value
      properties:
        lead_id:
          type: integer
          example: 852
        value:
          type: number
          example: 12500.00
        currency:
          type: string
          example: "USD"
        conversion_date:
          type: string
          format: date-time

    ErrorDetail:
      type: object
      required:
        - code
        - message
        - resolution_hint
      properties:
        code:
          type: string
          example: "UNAUTHORIZED"
        message:
          type: string
          example: "Missing API token."
        resolution_hint:
          type: string
          example: "Provide a valid token via 'Authorization: Bearer <API_TOKEN>' or use sandbox token 'gi_sandbox_live_demo_key'."

    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'

    ValidationErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - resolution_hint
            - details
          properties:
            code:
              type: string
              example: "VALIDATION_ERROR"
            message:
              type: string
              example: "The given data was invalid."
            resolution_hint:
              type: string
              example: "Align request attributes with OpenAPI schema at https://growthintel.net/openapi.json."
            details:
              type: object