openapi: 3.1.0 info: title: Credit Benchmark Analytics Portfolio Analytics API description: 'Authentication, matching, and analytics. ' 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://api.creditbenchmark.com description: Production server security: - BearerAuth: [] tags: - name: Portfolio Analytics description: Portfolio-level analytics and summaries paths: /api/analytics/portfolio-data: post: tags: - Portfolio Analytics summary: Portfolio Data description: 'Return portfolio time-series data. ' operationId: portfolioData requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RequestEnvelope_PortfolioDataRequest' example: Parameters: portfolio: name: Example Portfolio entities: CBId: - CB000000123 - CB000000456 CustomField1: - Value1 - Value2 - Value3 CustomField2: - 100 - 200 - 300 EffectiveDateId: 20241201 effectivedateid_min: 20240101 effectivedateid_min_lag_months: 0 columns: - CBEntityId - CBId - CBEntityName - EffectiveDateId - CCR - CCR21Notch - CCR100PDMid - CustomField1 - CustomField2 responses: '200': description: Portfolio data retrieved successfully content: application/json: schema: $ref: '#/components/schemas/PortfolioDataResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' /api/analytics/portfolio-summary: post: tags: - Portfolio Analytics summary: Portfolio Summary description: 'Return grouped portfolio metrics. ' operationId: portfolioSummary requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RequestEnvelope_PortfolioSummaryRequest' example: Parameters: portfolio: name: Example Portfolio entities: CBId: - CB000000123 - CB000000456 facet_column: Sector EffectiveDateId: 20241201 rating_change_months: 24 use_client_scale: false use_oci: false responses: '200': description: Portfolio summary retrieved successfully content: application/json: schema: $ref: '#/components/schemas/PortfolioSummaryResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/InternalServerError' components: schemas: RequestEnvelope_PortfolioSummaryRequest: properties: Parameters: $ref: '#/components/schemas/PortfolioSummaryRequest' type: object required: - Parameters title: RequestEnvelope_PortfolioSummaryRequest PortfolioDataResponse: type: object description: Response containing detailed portfolio data with requested columns required: - CBId - EffectiveDateId - CBEntityName - CCR - CCR100PDMid properties: CBId: type: array items: type: string description: Credit Benchmark entity identifiers example: - CB0000002619 - CB0000009484 - CB0000009810 - CB0000010249 - CB0000010457 EffectiveDateId: type: array items: type: integer description: Effective date identifiers example: - 20250131 - 20250131 - 20250131 - 20250131 - 20250131 CBEntityName: type: array items: type: string description: Entity names example: - BMO CAPITAL MARKETS CORP - HILLTOP SECURITIES INC - VIRTU AMERICAS LLC - OPPENHEIMER & CO INC, BROKER - TD AMERITRADE CLEARING INC CCR: type: array items: type: string description: Aggregate credit ratings example: - a- - bb+ - bb- - bb - a- CCR100PDMid: type: array items: type: number format: float description: Probability of default (mid) example: - 0.0009 - 0.0051 - 0.012 - 0.0086 - 0.0011 PortfolioSummaryResponse: type: object description: Response containing portfolio summary statistics by facet required: - CBSector - entity_count - benchmark_entity_count - CCR - CCRPD100Mid - upgrades - downgrades - rating_change properties: CBSector: type: array items: type: string description: Values of the grouping column (matches facet_column parameter) example: - Financial Services entity_count: type: array items: type: integer description: Total number of entities in each group example: - 10 benchmark_entity_count: type: array items: type: integer description: Number of entities with credit ratings (benchmark coverage) example: - 10 CCR: type: array items: type: string description: Aggregate credit ratings example: - bbb- CCRPD100Mid: type: array items: type: number format: float description: Aggregate probability of default (mid) example: - 0.0036 upgrades: type: array items: type: integer description: Number of upgrades in period example: - 1 downgrades: type: array items: type: integer description: Number of downgrades in period example: - 2 rating_change: type: array items: type: integer description: Net rating change (upgrades - downgrades) example: - -1 Portfolio: properties: name: type: string title: Name example: Example Portfolio entities: $ref: '#/components/schemas/FlexibleCBPortfolio' example: CBId: - CB000000123 - CB000000456 type: object required: - name - entities title: Portfolio Error: type: object description: Standard error envelope used by the API required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code example: BAD_REQUEST message: type: string description: Human-readable error message example: Invalid request parameters details: description: Optional structured details about the error oneOf: - type: array items: $ref: '#/components/schemas/ValidationErrorDetail' - type: object - type: string PortfolioSummaryRequest: properties: portfolio: $ref: '#/components/schemas/Portfolio' facet_column: type: string title: Facet Column description: Column to group by (e.g., ClientType, Sector, Industry) EffectiveDateId: type: integer title: Effectivedateid rating_change_months: type: integer title: Rating Change Months description: Number of months to look back for rating changes (e.g., 24 for 2-year changes) default: 24 use_client_scale: type: boolean title: Use Client Scale default: false use_oci: type: boolean title: Use Oci default: false type: object required: - portfolio - facet_column title: PortfolioSummaryRequest RequestEnvelope_PortfolioDataRequest: properties: Parameters: $ref: '#/components/schemas/PortfolioDataRequest' type: object required: - Parameters title: RequestEnvelope_PortfolioDataRequest FlexibleCBPortfolio: properties: CBId: items: type: string type: array title: Cbid additionalProperties: true type: object title: FlexibleCBPortfolio PortfolioDataRequest: properties: portfolio: $ref: '#/components/schemas/Portfolio' EffectiveDateId: type: integer title: Effectivedateid effectivedateid_min: type: integer title: Effectivedateid Min effectivedateid_min_lag_months: type: integer title: Effectivedateid Min Lag Months default: 0 columns: items: type: string type: array title: Columns description: 'List of columns to retrieve. Available columns: CBCountryOfDomicile, CBCountryOfRisk, CBCountryOfRiskISO, CBEntityId, CBEntityName, CBEntitySize, CBEntitySubType, CBEntityType, CBGroupSize, CBId, CBIndustry, CBRegion, CBRegionGroup, CBSector, CBSubSector, CBSubdivision, CBSubdivisionISO, CBSubdivisionRegion, CBSuperSector, CCR, CCR100Notch, CCR100PDMid, CCR100PDMidLog, CCR21Notch, CCR21PDMid, CCRAgreementIndicator, CCRContributorCount, CCRMax, CCRMaxNotch, CCRMin, CCRMinNotch, CCRNotchDifferenceCBScale, CCRNotchDifferenceClientScale, CCROpinionChangeIndicator, CCROpinionChangeIndicatorNumeric, CCROutlierIndicator, CCRRSD, CCRRatingChange12M, CCRRatingChange1M, CCRRatingChange3M, CCRRatingChange6M, CCRRatingChange9M, CCRSkew, CCRSource, CRARated, CUSIP, ClientId, ClientLogTTCPDChange, ClientLogTTCPDChangePublish, ClientOpinionChangeIndicatorNumeric, ClientRatingCBScale, ClientRatingCBScale21Notch, ClientRatingClientScale, ClientRatingClientScaleName, ClientRatingClientScaleNormalisedNotch, ClientRatingClientScaleNotch, ClientScaleNormalisedRating, ClientTTCPD, ClientTTCPDLog, EffectiveDate, EffectiveDateId, EntityStructure, ExClientOpinionChangeIndicatorNumeric, ExClientPDAvg, ExClientPDAvgLog, ExClientRatingCBScale, ExClientRatingClientScale, ExClientRatingClientScaleNotch, FitchLTIDRating, IGHY, ISIN, ImmediateParentEntityId, IsHistoricalQuorate, IsHistoricalQuorateCCR, IsPublicCompany, LEI, LatestWatchlist, Ownership, ParticipationId, RealExClientPDAvg, RealExClientPDAvgLog, SME, SMEFlag, SPFCLTNotch, SPFCLTRating, TTCPDAverage, Ticker, UltimateParentCBCountryOfRisk, UltimateParentCBEntityName, UltimateParentEntityId, isQuorate. Some columns require specific entitlements (S&P, Fitch, client data).' type: object required: - portfolio title: PortfolioDataRequest ValidationErrorDetail: type: object description: Single field validation error properties: field: type: string description: Location of the validation error (e.g. body.Parameters.portfolio) example: body.Parameters.portfolio message: type: string description: Human-readable error message example: field required type: type: string description: Machine-readable error type example: value_error.missing responses: ValidationError: description: Validation error - request parameters are invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: VALIDATION_ERROR message: Request validation failed details: - field: body.Parameters.portfolio message: field required type: value_error.missing Unauthorized: description: Unauthorized - invalid or missing JWT token content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Invalid or missing JWT token BadRequest: description: Bad request - invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: BAD_REQUEST message: Invalid request parameters details: invalid_columns: - BadColumn allowed_columns: Please check documentation for valid column names Forbidden: description: Forbidden - insufficient permissions or access denied content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: PERMISSION_DENIED message: Insufficient permissions for this resource InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT bearer token.