openapi: 3.2.0
info:
  title: Partners CRM Reporting API
  description: Partners Hub API documentation
  version: 1.0.0
servers:
- url: https://agency-partner-hub-web.global-aws-use1-p.app-us1.com/
  description: Production
tags:
- name: CRM Reporting
  description: Read-only CRM pipeline reporting and metrics.
paths:
  /api/crm-reporting/v1/pipelines:
    get:
      tags:
      - CRM Reporting
      summary: List sync-enabled pipelines with deal counts, conversion %, revenue, and top account.
      operationId: get_crm_reporting_list_pipelines
      parameters:
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date
          example: '2026-03-01'
        example: '2026-03-01'
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date
          example: '2026-03-31'
        example: '2026-03-31'
      - name: timezone
        in: query
        required: false
        schema:
          type: string
          default: UTC
          example: America/New_York
        example: America/New_York
      - name: search
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          default: null
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
          maximum: 100
          minimum: 1
      responses:
        '200':
          description: 'Top Deals: per-pipeline counts, conversion, revenue, and top child account.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelinesListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                type: https://tools.ietf.org/html/rfc2616#section-10
                title: An error occurred
                status: 400
                detail: Bad Request
        '401':
          description: Authorization error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                type: https://tools.ietf.org/html/rfc2616#section-10
                title: An error occurred
                status: 404
                detail: Not Found
      security:
      - PartnerApiKey: []
      - PartnerJwtBearerAuth: []
  /api/crm-reporting/v1/pipelines/summary:
    get:
      tags:
      - CRM Reporting
      summary: 'Aggregate summary metric cards: deal counts, revenue, conversion %, average deal revenue.'
      operationId: get_crm_reporting_pipelines_summary
      parameters:
      - name: start_date
        in: query
        required: true
        schema:
          type: string
          format: date
          example: '2026-03-01'
        example: '2026-03-01'
      - name: end_date
        in: query
        required: true
        schema:
          type: string
          format: date
          example: '2026-03-31'
        example: '2026-03-31'
      - name: timezone
        in: query
        required: false
        schema:
          type: string
          default: UTC
          example: America/New_York
        example: America/New_York
      - name: search
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          default: null
      responses:
        '200':
          description: 'Top Deals: aggregate summary rolled up across all sync-enabled pipelines.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelinesSummaryResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                type: https://tools.ietf.org/html/rfc2616#section-10
                title: An error occurred
                status: 400
                detail: Bad Request
        '401':
          description: Authorization error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                type: https://tools.ietf.org/html/rfc2616#section-10
                title: An error occurred
                status: 404
                detail: Not Found
      security:
      - PartnerApiKey: []
      - PartnerJwtBearerAuth: []
components:
  schemas:
    ApiViolation:
      required:
      - propertyPath
      - title
      - template
      - parameters
      properties:
        propertyPath:
          type: string
        title:
          type: string
        template:
          type: string
        parameters:
          oneOf:
          - oneOf:
            - type: array
              items: {}
            - type: object
              additionalProperties: {}
          - type: object
            additionalProperties:
              type: string
      type: object
      additionalProperties: true
    ApiErrorResponse:
      required:
      - type
      - title
      - status
      - detail
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        violations:
          default: null
          oneOf:
          - type:
            - array
            - 'null'
            items:
              $ref: '#/components/schemas/ApiViolation'
          - type:
            - object
            - 'null'
            additionalProperties:
              $ref: '#/components/schemas/ApiViolation'
      type: object
      additionalProperties: true
    RangeInfo:
      required:
      - start_date
      - end_date
      - timezone
      properties:
        start_date:
          type: string
          format: date
          example: '2026-03-01'
        end_date:
          type: string
          format: date
          example: '2026-03-31'
        timezone:
          type: string
          example: America/New_York
      type: object
      additionalProperties: false
    DealsBucket:
      required:
      - count
      - revenue_cents
      properties:
        count:
          type: integer
          example: 40
        revenue_cents:
          type: integer
          example: 20340000
      type: object
      additionalProperties: false
    TopAccount:
      required:
      - id
      - name
      properties:
        id:
          type: integer
          example: 101
        name:
          type: string
          example: Labor Finders - Chicago
      type: object
      additionalProperties: false
    Pagination:
      required:
      - total
      - page
      - limit
      - total_pages
      properties:
        total:
          type: integer
          example: 42
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 10
        total_pages:
          type: integer
          example: 5
      type: object
      additionalProperties: false
    PipelineSummary:
      required:
      - id
      - name
      - deals_open
      - deals_won
      - deals_lost
      - conversion_rate_percent
      - total_revenue_cents
      properties:
        id:
          type: integer
          example: 42
        name:
          type: string
          example: Dog Bday Party
        deals_open:
          type: integer
          example: 10
        deals_won:
          type: integer
          example: 2
        deals_lost:
          type: integer
          example: 1
        conversion_rate_percent:
          type: number
          format: float
          example: 66.67
        total_revenue_cents:
          type: integer
          example: 64000
        top_account:
          oneOf:
          - $ref: '#/components/schemas/TopAccount'
          type:
          - object
          - 'null'
      type: object
      additionalProperties: false
    PipelinesSummary:
      required:
      - average_deal_revenue_cents
      - deals_open
      - deals_won
      - deals_lost
      - conversion_rate_percent
      properties:
        average_deal_revenue_cents:
          type: integer
          example: 423500
        deals_open:
          $ref: '#/components/schemas/DealsBucket'
        deals_won:
          $ref: '#/components/schemas/DealsBucket'
        deals_lost:
          $ref: '#/components/schemas/DealsBucket'
        conversion_rate_percent:
          type: number
          format: float
          example: 60
      type: object
      additionalProperties: false
    PipelinesSummaryResponse:
      required:
      - range
      - currency
      - summary
      properties:
        range:
          $ref: '#/components/schemas/RangeInfo'
        currency:
          type: string
          example: USD
        summary:
          $ref: '#/components/schemas/PipelinesSummary'
      type: object
      additionalProperties: false
    PipelinesListResponse:
      required:
      - range
      - currency
      - pipelines
      - pagination
      properties:
        range:
          $ref: '#/components/schemas/RangeInfo'
        currency:
          type: string
          example: USD
        pipelines:
          type: array
          items:
            $ref: '#/components/schemas/PipelineSummary'
        pagination:
          $ref: '#/components/schemas/Pagination'
      type: object
      additionalProperties: false
    UnauthorizedResponse:
      description: Unauthorized
      example:
        error: Unauthorized
        message: Invalid credentials
  securitySchemes:
    PartnerApiKey:
      type: apiKey
      description: API Token Authorization from Partner Portal
      name: api-key
      in: header
    PartnerJwtBearerAuth:
      type: http
      description: JWT Authorization header using the Partner JWT token.
      bearerFormat: JWT
      scheme: bearer