openapi: 3.0.3
info:
  title: Andru Revenue Intelligence API
  version: 1.0.0
  description: |
    Headless revenue intelligence platform for technical SaaS founders ($500K-$5M ARR).
    Buyer understanding, persona profiling, deal classification, messaging frameworks,
    competitive positioning, and pre-call intelligence — consumed via MCP Server,
    Chrome Extension, A2A Protocol, and REST API.
  contact:
    name: Andru (H&S)
    url: https://andru-ai.com
  license:
    name: Proprietary

servers:
  - url: https://platform.andru-ai.com
    description: Production

security:
  - BearerAuth: []
  - ApiKeyAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: "Platform API key as Bearer token: `Authorization: Bearer sk_live_...`"
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: "Platform API key: `X-API-Key: sk_live_...`"

  schemas:
    MCPToolCallRequest:
      type: object
      required: [tool]
      properties:
        tool:
          type: string
          description: Tool name to execute
          example: get_icp_fit_score
        arguments:
          type: object
          description: Tool-specific arguments

    MCPToolCallResponse:
      type: object
      properties:
        content:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum: [text]
              text:
                type: string
        isError:
          type: boolean

    MCPResourceReadRequest:
      type: object
      required: [uri]
      properties:
        uri:
          type: string
          description: Resource URI
          example: "andru://icp/profile"

    A2ATaskRequest:
      type: object
      required: [jsonrpc, method, params]
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        method:
          type: string
          enum: [tasks/send, tasks/get, tasks/cancel]
        params:
          type: object
          properties:
            id:
              type: string
              description: Task ID
            message:
              type: object
              properties:
                role:
                  type: string
                  enum: [user]
                parts:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum: [text]
                      text:
                        type: string
        id:
          type: string
          description: JSON-RPC request ID

    AgentCard:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        version:
          type: string
        url:
          type: string
        protocolVersion:
          type: string
        skills:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              description:
                type: string
              tags:
                type: array
                items:
                  type: string
              examples:
                type: array
                items:
                  type: string
        capabilities:
          type: object
          properties:
            streaming:
              type: boolean
            pushNotifications:
              type: boolean
            stateTransitionHistory:
              type: boolean

    # --- Tool Input Schemas ---

    GetICPFitScoreInput:
      type: object
      properties:
        companyName:
          type: string
          description: Company name to evaluate
        domain:
          type: string
          description: Company website domain
        industry:
          type: string
          description: Industry vertical
        employeeCount:
          type: number
          description: Number of employees
        revenue:
          type: string
          description: "Revenue range (e.g., \"$1M-$5M\")"
        geography:
          type: string
          description: HQ location
        techStack:
          type: array
          items:
            type: string
          description: Technologies the company uses
        painPoints:
          type: array
          items:
            type: string
          description: Known pain points or challenges
        triggerEvents:
          type: array
          items:
            type: string
          description: "Recent trigger events (e.g., \"just raised Series B\")"
        productDescription:
          type: string
          description: "Cold start: what your product does (1-2 sentences)"
        vertical:
          type: string
          description: "Cold start: industry you sell into"
        targetRole:
          type: string
          description: "Cold start: buyer role (e.g., \"CTO\")"

    GetPersonaProfileInput:
      type: object
      required: [title]
      properties:
        title:
          type: string
          description: "Job title (e.g., \"VP Engineering\", \"CTO\")"
        industry:
          type: string
          description: Industry context
        companySize:
          type: string
          description: Company size range
        productDescription:
          type: string
          description: "Cold start: what your product does"
        vertical:
          type: string
          description: "Cold start: industry you sell into"
        targetRole:
          type: string
          description: "Cold start: buyer role"

    GetDisqualificationSignalsInput:
      type: object
      properties:
        companyName:
          type: string
          description: Company name
        industry:
          type: string
        employeeCount:
          type: number
        revenue:
          type: string
          description: Revenue range
        geography:
          type: string
        techStack:
          type: array
          items:
            type: string
        dealContext:
          type: object
          properties:
            dealValue:
              type: number
            stage:
              type: string
            daysInPipeline:
              type: number
            championIdentified:
              type: boolean
        productDescription:
          type: string
        vertical:
          type: string
        targetRole:
          type: string

    GetMessagingFrameworkInput:
      type: object
      properties:
        segment:
          type: string
          description: Target segment or vertical
        stage:
          type: string
          enum: [awareness, consideration, decision]
          description: Buyer journey stage
        channel:
          type: string
          description: "Channel (email, linkedin, phone)"
        personaType:
          type: string
          description: Target persona title
        mbtiCategory:
          type: string
          enum: [Analytical, Driver, Expressive, Amiable]
          description: MBTI communication category
        productDescription:
          type: string
        vertical:
          type: string
        targetRole:
          type: string

    GetCompetitivePositioningInput:
      type: object
      properties:
        competitorName:
          type: string
          description: Competitor company name
        competitorFeatures:
          type: array
          items:
            type: string
          description: Known competitor features
        context:
          type: string
          description: "Additional context (e.g., \"enterprise deal\")"
        productDescription:
          type: string
        vertical:
          type: string
        targetRole:
          type: string

    ClassifyOpportunityInput:
      type: object
      required: [companyName]
      properties:
        companyName:
          type: string
        contactTitle:
          type: string
          description: Primary contact job title
        industry:
          type: string
        employeeCount:
          type: number
        revenue:
          type: string
        geography:
          type: string
        dealValue:
          type: number
        dealStage:
          type: string
        techStack:
          type: array
          items:
            type: string
        painPoints:
          type: array
          items:
            type: string
        triggerEvents:
          type: array
          items:
            type: string
        championIdentified:
          type: boolean
        competitorInvolved:
          type: string
        productDescription:
          type: string
        vertical:
          type: string
        targetRole:
          type: string

    GetAccountPlanInput:
      type: object
      required: [accountName]
      properties:
        accountName:
          type: string
          description: Target account/company name
        domain:
          type: string
        industry:
          type: string
        stakeholders:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              title:
                type: string
              role:
                type: string
                description: "Buying committee role (champion, economic_buyer, etc.)"
        dealContext:
          type: object
          properties:
            stage:
              type: string
            value:
              type: number
            nextMeeting:
              type: string

    GetCapabilityProfileInput:
      type: object
      properties:
        includeOutcomes:
          type: boolean
          description: "Include verified outcomes (default: true)"
        includeTrustSignals:
          type: boolean
          description: "Include trust signals (default: true)"
        forceRefresh:
          type: boolean
          description: "Force regeneration even if cached (default: false)"

    GetEvaluationCriteriaInput:
      type: object
      properties:
        buyerPainPoints:
          type: array
          items:
            type: string
          description: Buyer's known pain points
        buyerIndustry:
          type: string
        buyerSize:
          type: string
        requiredCapabilities:
          type: array
          items:
            type: string
        productDescription:
          type: string
        vertical:
          type: string
        targetRole:
          type: string

    GetICPProfileInput:
      type: object
      properties:
        layers:
          type: array
          items:
            type: number
            enum: [1, 2, 3, 4, 5]
          description: "Specific layers to include (1-5). Omit for all."
        includeSevenAnswers:
          type: boolean
          description: "Include seven answers (default: true)"
        includeAntiPatterns:
          type: boolean
          description: "Include anti-patterns (default: true)"

    DiscoverProspectsInput:
      type: object
      required: [companyName, productDescription]
      properties:
        companyName:
          type: string
          description: Your company name
        productDescription:
          type: string
          description: Description of your product
        coreCapability:
          type: string
          description: Your core capability or "pure signal"
        industry:
          type: string
          description: Target industry to search
        targetMarket:
          type: string
          description: "Target market segment (e.g., \"Series A SaaS\")"

    GetPreBriefInput:
      type: object
      properties:
        eventId:
          type: string
          description: Calendar event ID (from Andru calendar integration)
        dealId:
          type: string
          description: Associated deal ID
        briefType:
          type: string
          enum: [general, discovery, demo, negotiation, renewal, expansion]
          description: "Type of meeting brief (default: general)"

    GetSyndicationStatusInput:
      type: object
      properties: {}

    TriggerSyndicationInput:
      type: object
      properties:
        platforms:
          type: array
          items:
            type: string
          description: "Platforms to sync (e.g., [\"hubspot\"]). Omit for all stale."

    BatchFitScoreInput:
      type: object
      required: [companies]
      properties:
        companies:
          type: array
          maxItems: 50
          items:
            type: object
            properties:
              companyName:
                type: string
              domain:
                type: string
              industry:
                type: string
              employeeCount:
                type: number
              revenue:
                type: string
              geography:
                type: string
              techStack:
                type: array
                items:
                  type: string
              painPoints:
                type: array
                items:
                  type: string
              triggerEvents:
                type: array
                items:
                  type: string
          description: Companies to score (max 50)

    Error:
      type: object
      properties:
        error:
          type: string
        success:
          type: boolean

paths:
  # --- Agent Discovery ---
  /.well-known/agent.json:
    get:
      operationId: getAgentCard
      summary: A2A Agent Card Discovery
      description: Returns the Andru agent card for A2A protocol discovery. No authentication required.
      tags: [A2A Protocol]
      security: []
      responses:
        "200":
          description: Agent card
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentCard"

  # --- MCP Proxy Endpoints ---
  /api/mcp/tools/list:
    post:
      operationId: listMCPTools
      summary: List all MCP tools
      description: Returns definitions for all 15 MCP tools including inputSchema.
      tags: [MCP Proxy]
      responses:
        "200":
          description: Tool list
          content:
            application/json:
              schema:
                type: object
                properties:
                  tools:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        description:
                          type: string
                        inputSchema:
                          type: object

  /api/mcp/tools/call:
    post:
      operationId: callMCPTool
      summary: Execute an MCP tool
      description: |
        Execute any of the 15 MCP tools by name. Rate limited to 50 calls per 15 minutes.

        Available tools: get_icp_fit_score, get_persona_profile, get_disqualification_signals,
        get_messaging_framework, get_competitive_positioning, classify_opportunity,
        get_account_plan, get_capability_profile, get_evaluation_criteria, get_icp_profile,
        discover_prospects, get_pre_brief, get_syndication_status, trigger_syndication,
        batch_fit_score.
      tags: [MCP Proxy]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MCPToolCallRequest"
            examples:
              score_company:
                summary: Score a company against ICP
                value:
                  tool: get_icp_fit_score
                  arguments:
                    companyName: Datadog
                    industry: cloud monitoring
                    employeeCount: 5000
              discover_prospects:
                summary: Discover matching prospects
                value:
                  tool: discover_prospects
                  arguments:
                    companyName: Acme Corp
                    productDescription: AI-powered revenue intelligence for B2B SaaS
              batch_score:
                summary: Batch score companies
                value:
                  tool: batch_fit_score
                  arguments:
                    companies:
                      - companyName: Datadog
                        industry: monitoring
                      - companyName: PagerDuty
                        industry: incident management
      responses:
        "200":
          description: Tool execution result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MCPToolCallResponse"
        "400":
          description: Missing or unknown tool
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/mcp/resources/list:
    post:
      operationId: listMCPResources
      summary: List MCP resources
      description: "Returns definitions for all 3 MCP resources: andru://icp/profile, andru://pipeline/runs, andru://accounts."
      tags: [MCP Proxy]
      responses:
        "200":
          description: Resource list
          content:
            application/json:
              schema:
                type: object
                properties:
                  resources:
                    type: array
                    items:
                      type: object
                      properties:
                        uri:
                          type: string
                        name:
                          type: string
                        description:
                          type: string
                        mimeType:
                          type: string

  /api/mcp/resources/read:
    post:
      operationId: readMCPResource
      summary: Read an MCP resource
      description: Read a specific MCP resource by URI.
      tags: [MCP Proxy]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MCPResourceReadRequest"
            examples:
              icp_profile:
                summary: Read ICP profile
                value:
                  uri: "andru://icp/profile"
              pipeline_runs:
                summary: Read pipeline runs
                value:
                  uri: "andru://pipeline/runs"
      responses:
        "200":
          description: Resource content
          content:
            application/json:
              schema:
                type: object
                properties:
                  contents:
                    type: array
                    items:
                      type: object
                      properties:
                        uri:
                          type: string
                        mimeType:
                          type: string
                        text:
                          type: string

  # --- A2A Protocol Endpoints ---
  /api/a2a/tasks:
    post:
      operationId: submitA2ATask
      summary: Submit an A2A task
      description: |
        Submit a task using JSON-RPC 2.0 protocol. The task is routed to the appropriate
        skill based on the message content. Rate limited to 50 calls per 15 minutes.
      tags: [A2A Protocol]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/A2ATaskRequest"
            examples:
              score_company:
                summary: Score a company
                value:
                  jsonrpc: "2.0"
                  method: tasks/send
                  params:
                    id: task-001
                    message:
                      role: user
                      parts:
                        - type: text
                          text: "Score Datadog against our ICP"
                  id: "1"
      responses:
        "200":
          description: Task accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    type: string
                  result:
                    type: object
                    properties:
                      id:
                        type: string
                      status:
                        type: string
                        enum: [submitted, working, completed, failed, canceled]
                  id:
                    type: string

    get:
      operationId: listA2ATasks
      summary: List A2A tasks
      description: List tasks for the authenticated user.
      tags: [A2A Protocol]
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [submitted, working, completed, failed, canceled]
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Task list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  tasks:
                    type: array
                    items:
                      type: object

  /api/a2a/tasks/{taskId}:
    get:
      operationId: getA2ATask
      summary: Get task status
      description: Get the current status and result of a task.
      tags: [A2A Protocol]
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Task details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  task:
                    type: object
        "404":
          description: Task not found

  /api/a2a/tasks/{taskId}/cancel:
    post:
      operationId: cancelA2ATask
      summary: Cancel a task
      description: Cancel a running or submitted task.
      tags: [A2A Protocol]
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Task canceled
        "404":
          description: Task not found

  /api/a2a/tasks/{taskId}/stream:
    get:
      operationId: streamA2ATask
      summary: Stream task updates (SSE)
      description: |
        Server-Sent Events stream for real-time task updates.
        Events: `working` (progress), `complete` (final result), `error` (failure).
      tags: [A2A Protocol]
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: SSE stream
          content:
            text/event-stream:
              schema:
                type: string
        "404":
          description: Task not found

tags:
  - name: MCP Proxy
    description: HTTP proxy for MCP tool execution and resource access
  - name: A2A Protocol
    description: Agent-to-Agent protocol (JSON-RPC 2.0) for inter-agent communication
