openapi: 3.1.0
info:
  title: Credit Benchmark analytics API
  description: 'Authentication, entity resolution, data, analytics, and metadata endpoints.

    '
  version: 1.0.0
  contact:
    name: Credit Benchmark API Support
    email: api-support@creditbenchmark.com
    url: https://creditbenchmark.com/support
  license:
    name: Proprietary
    url: https://creditbenchmark.com/terms
servers:
- url: https://gateway.creditbenchmark.com
  description: Production gateway
security:
- BearerAuth: []
tags:
- name: analytics
  description: Analytics endpoints.
  x-group: Analytics
paths:
  /analytics/v2/data/aggregatetrend:
    post:
      tags:
      - analytics
      summary: Aggregate Trend
      description: Time series of aggregate credit metrics for a scoped entity universe. Use to track how consensus credit quality moves over time.
      operationId: aggregateTrend
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AggregateTrendRequest'
            example:
              metric: CCR
              rating_scale: CB21
              effective_date: 20250930
              lookback_period: 24
              lookback_unit: months
              scope:
                portfolio:
                  CB_ID:
                  - CB0000022706
                  - CB0000022177
      responses:
        '200':
          description: Aggregate trend retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregateTrendResponse'
              example:
                CB_Effective_Date_ID:
                - 20240731
                - 20240831
                AGG_EntityCount:
                - 2
                - 2
                AGG_CCRPD_log:
                - -5.82
                - -5.79
                AGG_CCRPD:
                - 0.00297
                - 0.00306
                AGG_CCRPD_index:
                - 0.0
                - 0.03
                AGG_CCR:
                - bbb-
                - bbb-
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/FrameworkValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /analytics/v2/data/entityratingchange:
    post:
      tags:
      - analytics
      summary: Entity Rating Change
      description: Entity-level rating changes over a lookback window. Use to identify upgrades and downgrades across a portfolio.
      operationId: entityRatingChange
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityRatingChangeRequest'
            example:
              metric: CCR
              rating_scale: CB21
              effective_date: 20250930
              lookback_period: 6
              lookback_unit: months
              scope:
                portfolio:
                  CB_ID:
                  - CB0000022706
                  - CB0000022177
              result_filter:
                sort:
                - field: CB_CCR_Change
                  direction: asc
                limit: 25
      responses:
        '200':
          description: Entity rating changes retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityRatingChangeResponse'
              example:
                CB_ID:
                - CB0000075935
                - CB0000035484
                CB_Legal_Name:
                - VANGUARD MARKETING CORP
                - NATIONAL BANK FINANCIAL INC
                CB_CCR:
                - bbb-
                - a-
                CB_CCR_6M:
                - bbb
                - a-
                CB_CCR_PD:
                - 0.00322
                - 0.00119
                CB_CCR_PD_6M:
                - 0.00212
                - 0.00119
                CB_CCR_Change:
                - -1
                - 0
                CB_CCR_PD_Change:
                - 0.0011
                - 0.0
                CB_CCR_Change_With_OCI:
                - 0
                - 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/FrameworkValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /analytics/v2/data/creditbreakdown:
    post:
      tags:
      - analytics
      summary: Credit Breakdown
      description: Credit quality snapshot broken down by a facet column — sector, country, industry, or any facetable field.
      operationId: creditBreakdown
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditBreakdownRequest'
            example:
              metric: CCR
              rating_scale: CB21
              effective_date: 20250930
              lookback_period: 24
              lookback_unit: months
              scope:
                filters:
                - key: CB_Sector
                  operator: ==
                  values: Banks
              facet_column: CB_Country
      responses:
        '200':
          description: Credit breakdown retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditBreakdownResponse'
              example:
                CB_Country:
                - United States
                - United Kingdom
                AGG_EntityCount:
                - 14
                - 9
                AGG_CCR:
                - bbb
                - bbb-
                AGG_CCRPD:
                - 0.00264
                - 0.00314
                AGG_Upgrades:
                - 1
                - 0
                AGG_Downgrades:
                - 0
                - 2
                AGG_NetUpMinusDown:
                - 1
                - -2
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/FrameworkValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /analytics/v2/data/ratingdistribution:
    post:
      tags:
      - analytics
      summary: Rating Distribution
      description: Share of entities in each rating bucket over time for a scoped universe.
      operationId: ratingDistribution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RatingDistributionRequest'
            example:
              metric: CCR
              rating_scale: CB21
              effective_date: 20250930
              lookback_period: 12
              lookback_unit: months
              scope:
                filters:
                - key: CB_Country
                  operator: ==
                  values: United States
              facet_column: CB_Sector
      responses:
        '200':
          description: Rating distribution retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatingDistributionResponse'
              example:
                CB_Sector:
                - Banks
                - Financial Services
                CB_Effective_Date_ID:
                - 20250831
                - 20250731
                AGG_EntityCount:
                - 14
                - 9
                a:
                - 0.18
                - 0.16
                a-:
                - 0.27
                - 0.29
                bbb+:
                - 0.23
                - 0.22
                bbb:
                - 0.19
                - 0.2
                bbb-:
                - 0.13
                - 0.13
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/FrameworkValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
          example:
            error: Client-backed analytics inputs require contributor entitlement.
    TooManyRequests:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            error: Rate limit exceeded
            detail: 60 per 1 minute
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
          example:
            detail: Unauthorized request
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
          example:
            error: 'Invalid request parameters: scope requires at least ''portfolio'' or ''filters''.'
    InternalServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
          example:
            error: An error occurred while processing your request. Please try again later.
    FrameworkValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FastApiValidationErrorResponse'
          example:
            detail:
            - loc:
              - body
              - effective_date
              msg: Input should be a valid integer
              type: int_parsing
  schemas:
    EntityRatingChangeResponse:
      type: object
      description: Entity rating change results.
      properties:
        CB_ID:
          $ref: '#/components/schemas/StringArray'
        CB_Legal_Name:
          $ref: '#/components/schemas/StringArray'
        CB_CCR:
          $ref: '#/components/schemas/ColumnArray'
        CB_CCR_PD:
          $ref: '#/components/schemas/NumberArray'
        CB_CCR_Change:
          $ref: '#/components/schemas/NumberArray'
        CB_CCR_PD_Change:
          $ref: '#/components/schemas/NumberArray'
        CB_CCR_Change_With_OCI:
          $ref: '#/components/schemas/NumberArray'
        ClientRating:
          $ref: '#/components/schemas/ColumnArray'
        ClientPD:
          $ref: '#/components/schemas/NumberArray'
        client_change:
          $ref: '#/components/schemas/NumberArray'
        client_change_w_oci:
          $ref: '#/components/schemas/NumberArray'
      patternProperties:
        ^CB_CCR_\d+M$:
          $ref: '#/components/schemas/ColumnArray'
        ^CB_CCR_PD_\d+M$:
          $ref: '#/components/schemas/NumberArray'
        ^ClientRating_\d+M$:
          $ref: '#/components/schemas/ColumnArray'
        ^ClientPD_\d+M$:
          $ref: '#/components/schemas/NumberArray'
      additionalProperties:
        $ref: '#/components/schemas/ColumnArray'
    ColumnArray:
      type: array
      items:
        $ref: '#/components/schemas/ScalarValue'
    RatingDistributionRequest:
      type: object
      required:
      - scope
      properties:
        metric:
          type: string
          enum:
          - CCR
          - MyRating
          default: CCR
          description: Metric to compute. Use `CCR` for consensus analytics or `MyRating` for client-specific analytics.
        rating_scale:
          type: string
          enum:
          - CB21
          - CB7
          - MyScale
          default: CB21
          description: Rating scale used to name the distribution buckets. Use `CB21`, `CB7`, or `MyScale`.
        effective_date:
          type: integer
          description: As-of date in YYYYMMDD format. If omitted, the latest available date is used.
        lookback_period:
          type: integer
          minimum: 0
          default: 0
          description: Number of `lookback_unit` intervals before `effective_date`.
        lookback_unit:
          type: string
          enum:
          - months
          - quarters
          - years
          default: months
        scope:
          $ref: '#/components/schemas/Scope'
        facet_column:
          type: string
          description: Optional facetable column to group the distribution by. Built-in facetable columns and custom `scope.portfolio` columns are supported.
        result_filter:
          $ref: '#/components/schemas/ResultFilter'
    ScalarValue:
      anyOf:
      - type: string
      - type: integer
      - type: number
      - type: boolean
      - type: 'null'
    ResultFilterSort:
      type: object
      additionalProperties: false
      required:
      - field
      properties:
        field:
          type: string
          description: Supported result field name to sort by for this route. Valid values come from returned analytic fields or documented route aliases, not arbitrary source columns.
        direction:
          type: string
          enum:
          - asc
          - desc
          default: desc
          description: Sort direction.
    FilterValue:
      anyOf:
      - $ref: '#/components/schemas/ScalarValue'
      - $ref: '#/components/schemas/ColumnArray'
    FastApiValidationErrorResponse:
      type: object
      required:
      - detail
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/FastApiValidationErrorDetail'
    Scope:
      type: object
      additionalProperties: false
      description: Defines the input universe. Use `portfolio`, `filters`, or both.
      properties:
        portfolio:
          $ref: '#/components/schemas/ScopePortfolio'
        filters:
          type: array
          items:
            $ref: '#/components/schemas/ScopeFilter'
          description: Universe filters. Use them alone to build the universe from public columns, or with `portfolio` to subset the supplied portfolio. Only built-in scopeable columns are allowed in `filters[].key`; custom `scope.portfolio` columns are not valid scope filters.
        filters_join:
          type: array
          items:
            type: string
          description: Optional logic used to join `filters`. Only `&`, `|`, and `~` are supported. Length must be `len(filters)+1`.
    FastApiValidationErrorDetail:
      type: object
      properties:
        loc:
          type: array
          items:
            oneOf:
            - type: string
            - type: integer
        msg:
          type: string
        type:
          type: string
    SimpleError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    NumberArray:
      type: array
      items:
        type: number
    UnauthorizedError:
      type: object
      required:
      - detail
      properties:
        detail:
          type: string
    ScopePortfolio:
      type: object
      description: Explicit entity universe. `CB_ID` is required. Any extra keys are treated as custom portfolio columns.
      required:
      - CB_ID
      properties:
        CB_ID:
          type: array
          items:
            type: string
          description: List of Credit Benchmark entity identifiers.
      additionalProperties: true
    RateLimitError:
      type: object
      required:
      - error
      - detail
      properties:
        error:
          type: string
        detail:
          type: string
    IntegerArray:
      type: array
      items:
        type: integer
    AggregateTrendRequest:
      type: object
      required:
      - scope
      properties:
        metric:
          type: string
          enum:
          - CCR
          - MyRating
          default: CCR
          description: Metric to compute. Use `CCR` for consensus analytics or `MyRating` for client-specific analytics.
        rating_scale:
          type: string
          enum:
          - CB21
          - CB7
          - MyScale
          default: CB21
          description: Rating scale to map results onto. Use `CB21`, `CB7`, or `MyScale` for the requesting bank's master scale.
        effective_date:
          type: integer
          description: As-of date in YYYYMMDD format. If omitted, the latest available date is used.
        lookback_period:
          type: integer
          minimum: 0
          default: 24
          description: Number of `lookback_unit` intervals before `effective_date`.
        lookback_unit:
          type: string
          enum:
          - months
          - quarters
          - years
          default: months
        scope:
          $ref: '#/components/schemas/Scope'
        facet_column:
          type: string
          description: Optional facetable column to segment the aggregate. Built-in facetable columns and custom `scope.portfolio` columns are supported.
        result_filter:
          $ref: '#/components/schemas/ResultFilter'
    ResultFilter:
      type: object
      additionalProperties: false
      description: Filtering, sorting, and limiting applied after an analytic has computed its results. `filters[].key` and `sort.field` must reference supported result fields for the selected route. Some routes also accept documented alias names that map to returned fields.
      properties:
        limit:
          type: integer
          minimum: 1
          description: Return only the first N rows after `filters` and `sort` are applied.
        filters:
          type: array
          description: Filters applied to computed result rows. These do not change the analytic itself.
          items:
            $ref: '#/components/schemas/ResultFilterCondition'
        filters_join:
          type: array
          items:
            type: string
          description: Optional logic used to join `filters`. Length must be `len(filters)+1`. If omitted, conditions are AND-joined.
        sort:
          type: array
          items:
            $ref: '#/components/schemas/ResultFilterSort'
          description: Priority-ordered sort rules.
    ResultFilterCondition:
      type: object
      additionalProperties: false
      required:
      - key
      - operator
      properties:
        key:
          type: string
          description: Supported result field name to filter after the analytic has been computed. Valid values come from returned analytic fields or documented route aliases, not arbitrary source columns.
        operator:
          type: string
          enum:
          - ==
          - '!='
          - '>'
          - <
          - '>='
          - <=
          - in
          - not in
          - contains
          - starts with
          - ends with
          - does not contain
          - does not start with
          - does not end with
          - is null
          - is not null
          description: Comparison operator.
        values:
          allOf:
          - $ref: '#/components/schemas/FilterValue'
          description: Single value or list of values for the filter. Not used for `is null` or `is not null`.
    RatingDistributionResponse:
      type: object
      description: Rating distribution results.
      properties:
        CB_Effective_Date_ID:
          $ref: '#/components/schemas/IntegerArray'
        AGG_EntityCount:
          $ref: '#/components/schemas/IntegerArray'
      patternProperties:
        ? ^(aaa|aa\+|aa|aa-|a\+|a|a-|bbb\+|bbb|bbb-|bb\+|bb|bb-|b\+|b|b-|ccc\+|ccc|ccc-|cc|c|0\.1|1\.1|1\.2|2\.1|2\.2|3\.1|3\.2|3\.3|4\.1|4\.2|4\.3|5\.1|5\.2|5\.3|6\.1|6\.2|7\.1|7\.2|8\.1|8\.2|8\.3)$
        : $ref: '#/components/schemas/NumberArray'
      additionalProperties:
        $ref: '#/components/schemas/ColumnArray'
    AggregateTrendResponse:
      type: object
      description: Aggregate trend results.
      properties:
        CB_Effective_Date_ID:
          $ref: '#/components/schemas/IntegerArray'
        AGG_EntityCount:
          $ref: '#/components/schemas/IntegerArray'
        AGG_CCRPD_log:
          $ref: '#/components/schemas/NumberArray'
        AGG_CCRPD:
          $ref: '#/components/schemas/NumberArray'
        AGG_CCRPD_index:
          $ref: '#/components/schemas/NumberArray'
        AGG_CCR:
          $ref: '#/components/schemas/ColumnArray'
        AGG_ClientPD_log:
          $ref: '#/components/schemas/NumberArray'
        AGG_ClientPD:
          $ref: '#/components/schemas/NumberArray'
        AGG_ClientPD_index:
          $ref: '#/components/schemas/NumberArray'
        AGG_ClientRating:
          $ref: '#/components/schemas/ColumnArray'
        AGG_ClientRatingNotch:
          $ref: '#/components/schemas/NumberArray'
        AGG_ExMePD_log:
          $ref: '#/components/schemas/NumberArray'
        AGG_ExMePD:
          $ref: '#/components/schemas/NumberArray'
        AGG_ExMePD_index:
          $ref: '#/components/schemas/NumberArray'
        AGG_ExMeRating:
          $ref: '#/components/schemas/ColumnArray'
        AGG_ExMeRatingNotch:
          $ref: '#/components/schemas/NumberArray'
      additionalProperties:
        $ref: '#/components/schemas/ColumnArray'
    ScopeFilter:
      type: object
      additionalProperties: false
      required:
      - key
      - operator
      properties:
        key:
          type: string
          description: Public input column used to build or filter the universe. Only supported scopeable columns are allowed; see `/v2/metadata/columns`.
        operator:
          type: string
          enum:
          - ==
          - '!='
          - '>'
          - <
          - '>='
          - <=
          - in
          - not in
          - is null
          - is not null
          description: Comparison operator.
        values:
          $ref: '#/components/schemas/FilterValue'
          description: Single value or list of values for the filter. Use an empty string for `is null` or `is not null`.
    StringArray:
      type: array
      items:
        type: string
    EntityRatingChangeRequest:
      type: object
      required:
      - scope
      properties:
        metric:
          type: string
          enum:
          - CCR
          - MyRating
          default: CCR
          description: Metric to compute. Use `CCR` for consensus analytics or `MyRating` for client-specific analytics.
        rating_scale:
          type: string
          enum:
          - CB21
          - CB7
          - MyScale
          default: CB21
          description: Rating scale to map results onto. Use `CB21`, `CB7`, or `MyScale` for the requesting bank's master scale.
        effective_date:
          type: integer
          description: As-of date in YYYYMMDD format. If omitted, the latest available date is used.
        lookback_period:
          type: integer
          minimum: 0
          default: 6
          description: Number of `lookback_unit` intervals used for the rating-change window.
        lookback_unit:
          type: string
          enum:
          - months
          - quarters
          - years
          default: months
        scope:
          $ref: '#/components/schemas/Scope'
        result_filter:
          allOf:
          - $ref: '#/components/schemas/ResultFilter'
          description: Optional result shaping applied after rating-change rows are computed. This route accepts final response fields such as `CB_ID`, `CB_CCR_PD_Change`, and `ClientRating_Change`, and stable aliases such as `entity.*`, `metrics.*`, and `client.*` when those fields are present.
    CreditBreakdownResponse:
      type: object
      description: Credit breakdown results.
      properties:
        AGG_EntityCount:
          $ref: '#/components/schemas/IntegerArray'
        AGG_CCR:
          $ref: '#/components/schemas/ColumnArray'
        AGG_CCRPD:
          $ref: '#/components/schemas/NumberArray'
        AGG_Upgrades:
          $ref: '#/components/schemas/IntegerArray'
        AGG_Downgrades:
          $ref: '#/components/schemas/IntegerArray'
        AGG_NetUpMinusDown:
          $ref: '#/components/schemas/NumberArray'
        AGG_ClientRating:
          $ref: '#/components/schemas/ColumnArray'
        AGG_ClientPD:
          $ref: '#/components/schemas/NumberArray'
        AGG_ExMeRating:
          $ref: '#/components/schemas/ColumnArray'
        AGG_ExMePD:
          $ref: '#/components/schemas/NumberArray'
        AGG_NotchDifference:
          $ref: '#/components/schemas/NumberArray'
        AGG_NotchDiffAggressive:
          $ref: '#/components/schemas/IntegerArray'
        AGG_NotchDiffConsistent:
          $ref: '#/components/schemas/IntegerArray'
        AGG_NotchDiffConservative:
          $ref: '#/components/schemas/IntegerArray'
      additionalProperties:
        $ref: '#/components/schemas/ColumnArray'
    CreditBreakdownRequest:
      type: object
      required:
      - scope
      - facet_column
      properties:
        metric:
          type: string
          enum:
          - CCR
          - MyRating
          default: CCR
          description: Metric to compute. Use `CCR` for consensus analytics or `MyRating` for client-specific analytics.
        rating_scale:
          type: string
          enum:
          - CB21
          - CB7
          - MyScale
          default: CB21
          description: Rating scale to map results onto. Use `CB21`, `CB7`, or `MyScale` for the requesting bank's master scale.
        effective_date:
          type: integer
          description: As-of date in YYYYMMDD format. If omitted, the latest available date is used.
        lookback_period:
          type: integer
          minimum: 0
          default: 24
          description: Number of `lookback_unit` intervals before `effective_date`.
        lookback_unit:
          type: string
          enum:
          - months
          - quarters
          - years
          default: months
        scope:
          $ref: '#/components/schemas/Scope'
        facet_column:
          type: string
          description: Column to summarize by. Built-in facetable columns and custom `scope.portfolio` columns are supported.
        result_filter:
          $ref: '#/components/schemas/ResultFilter'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT bearer token.