openapi: 3.0.3
info:
  title: S&P Capital IQ API
  description: >-
    The S&P Capital IQ API provides programmatic access to comprehensive
    global financial data including fundamental financials, valuations,
    pricing, credit ratings, capital structure, and reference data. All
    requests use Bearer token authentication with tokens valid for 3600
    seconds. Communication uses HTTPS on port 443 with 256-bit encryption.
  version: v3
  contact:
    name: S&P Global Market Intelligence Support
    url: https://www.marketplace.spglobal.com
  license:
    name: Commercial
    url: https://www.spglobal.com/marketintelligence/en/campaigns/terms-of-use
servers:
  - url: https://api-ciq.marketintelligence.spglobal.com/gdsapi/rest
    description: S&P Capital IQ REST API

security:
  - BearerAuth: []

tags:
  - name: Authentication
    description: Token generation and refresh operations
  - name: Financial Data
    description: Retrieve fundamental financial data for companies
  - name: Credit Ratings
    description: Access S&P Global credit ratings and research

paths:
  /authenticate/api/v1/token:
    post:
      operationId: generateAuthToken
      summary: Generate Authentication Token
      description: >-
        Generates a Bearer access token using S&P Global Single Sign-On
        credentials. The token is valid for 3600 seconds (60 minutes).
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  description: S&P Global SSO email address
                password:
                  type: string
                  format: password
                  description: S&P Global SSO password
      responses:
        '200':
          description: Authentication token generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: Invalid credentials

  /authenticate/api/v1/tokenRefresh:
    post:
      operationId: refreshAuthToken
      summary: Refresh Authentication Token
      description: >-
        Refreshes an existing Bearer access token before it expires.
        Must be called before the 3600 second expiration window.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                refreshToken:
                  type: string
                  description: Refresh token received during initial authentication
      responses:
        '200':
          description: Token refreshed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'

  /v3/clientservice.json:
    post:
      operationId: getFinancialData
      summary: Get Financial Data
      description: >-
        Primary endpoint for retrieving financial and market intelligence data.
        Submit a JSON request body specifying the data set, entity identifiers,
        mnemonic fields, and time parameters to retrieve financial data.
      tags:
        - Financial Data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinancialDataRequest'
      responses:
        '200':
          description: Financial data response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialDataResponse'
        '400':
          description: Invalid request parameters
        '401':
          description: Unauthorized - invalid or expired token

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from the /authenticate/api/v1/token endpoint

  schemas:
    TokenResponse:
      type: object
      properties:
        accessToken:
          type: string
          description: Bearer access token for subsequent API requests
        expiresIn:
          type: integer
          description: Token validity period in seconds (3600)
        tokenType:
          type: string
          description: Token type (Bearer)
        refreshToken:
          type: string
          description: Token for refreshing the access token

    FinancialDataRequest:
      type: object
      required:
        - inputRequests
      properties:
        inputRequests:
          type: array
          items:
            type: object
            required:
              - function
              - identifier
              - mnemonic
            properties:
              function:
                type: string
                description: Data retrieval function (e.g., GDSP, GDST, GDSHE)
                example: GDSP
              identifier:
                type: string
                description: Company or security identifier (ticker, GVKEY, CUSIP, ISIN)
                example: IQ303931
              mnemonic:
                type: string
                description: Data point mnemonic code representing the specific financial metric
                example: IQ_TOTAL_REV
              properties:
                type: object
                description: Additional request properties such as date range and periodicity
                properties:
                  startDate:
                    type: string
                    description: Start date for time series (YYYY-MM-DD)
                  endDate:
                    type: string
                    description: End date for time series (YYYY-MM-DD)
                  periodType:
                    type: string
                    description: Period type (Annual, Quarterly, LTM, YTD)

    FinancialDataResponse:
      type: object
      properties:
        GDSSDKResponse:
          type: array
          items:
            type: object
            properties:
              Rows:
                type: array
                items:
                  type: object
                  properties:
                    Row:
                      type: array
                      items:
                        type: string
              Headers:
                type: array
                items:
                  type: object
                  properties:
                    Name:
                      type: string
              ErrMsg:
                type: string
              Type:
                type: string
              RequestId:
                type: string