openapi: 3.0.3
info:
  title: Kensho Link API
  description: >-
    S&P Global Kensho Link REST API for entity resolution and linking across
    financial instruments, companies, people, and other entities. Provides a
    canonical entity identifier (KEID) layer that links entities across S&P
    Global data assets including Capital IQ, Market Intelligence, and Platts.
    Used for data integration and entity disambiguation in financial analytics.
  version: 1.0.0
  contact:
    name: Kensho Technologies
    url: https://api.link.kensho.com/docs/guides/rest-api/
  termsOfService: https://www.spglobal.com/en/terms-of-use
servers:
  - url: https://api.link.kensho.com
    description: Kensho Link production API
tags:
  - name: Entity Resolution
    description: Entity linking and resolution operations
  - name: Search
    description: Entity search and discovery
paths:
  /link:
    post:
      operationId: linkEntity
      summary: Link Entity to Canonical Identifier
      description: >-
        Resolves one or more entity mentions to their canonical Kensho Entity
        Identifier (KEID). Accepts entity names, aliases, ticker symbols, CUSIP,
        ISIN, or other identifiers and returns the canonical entity record.
      tags:
        - Entity Resolution
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkRequest'
      responses:
        '200':
          description: Entity resolution results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkResponse'
        '400':
          description: Invalid request format
        '401':
          description: Unauthorized - invalid or missing token
        '429':
          description: Rate limit exceeded
  /entity/{keid}:
    get:
      operationId: getEntity
      summary: Get Entity by KEID
      description: >-
        Returns the full canonical entity record for a given Kensho Entity
        Identifier (KEID), including names, aliases, entity type, and
        cross-references to other S&P Global identifiers.
      tags:
        - Entity Resolution
      security:
        - BearerAuth: []
      parameters:
        - name: keid
          in: path
          required: true
          description: Kensho Entity Identifier (KEID) for the entity
          schema:
            type: string
            example: keid_abc12345
      responses:
        '200':
          description: Entity record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '401':
          description: Unauthorized
        '404':
          description: Entity not found
  /search:
    get:
      operationId: searchEntities
      summary: Search Entities
      description: >-
        Search for entities by name, ticker symbol, or other attributes.
        Returns a ranked list of matching entity candidates with confidence
        scores.
      tags:
        - Search
      security:
        - BearerAuth: []
      parameters:
        - name: q
          in: query
          required: true
          description: Search query string (entity name, ticker, or other identifier)
          schema:
            type: string
            example: Apple Inc
        - name: entityType
          in: query
          required: false
          description: Filter results by entity type
          schema:
            type: string
            enum:
              - company
              - person
              - instrument
              - fund
              - index
            example: company
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      responses:
        '200':
          description: Entity search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          description: Unauthorized
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    LinkRequest:
      type: object
      required:
        - mentions
      properties:
        mentions:
          type: array
          description: List of entity mentions to resolve
          items:
            $ref: '#/components/schemas/EntityMention'
        context:
          type: string
          description: Optional surrounding text context to improve resolution accuracy
    EntityMention:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: Entity mention text or identifier
          example: Apple Inc
        identifierType:
          type: string
          description: Type of identifier provided
          enum:
            - name
            - ticker
            - cusip
            - isin
            - cik
            - lei
          example: name
    LinkResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/LinkResult'
    LinkResult:
      type: object
      properties:
        mention:
          $ref: '#/components/schemas/EntityMention'
        candidates:
          type: array
          description: Ranked entity candidates sorted by confidence score
          items:
            $ref: '#/components/schemas/EntityCandidate'
    EntityCandidate:
      type: object
      properties:
        keid:
          type: string
          description: Kensho Entity Identifier
          example: keid_abc12345
        name:
          type: string
          description: Canonical entity name
          example: Apple Inc.
        entityType:
          type: string
          description: Entity type classification
          example: company
        confidence:
          type: number
          format: double
          description: Confidence score for this candidate (0.0 to 1.0)
          minimum: 0
          maximum: 1
          example: 0.98
        crossReferences:
          $ref: '#/components/schemas/CrossReferences'
    Entity:
      type: object
      properties:
        keid:
          type: string
          description: Kensho Entity Identifier
          example: keid_abc12345
        name:
          type: string
          description: Canonical entity name
          example: Apple Inc.
        aliases:
          type: array
          description: Alternative names and aliases
          items:
            type: string
          example:
            - Apple
            - AAPL
        entityType:
          type: string
          description: Entity type classification
          example: company
        description:
          type: string
          description: Brief entity description
        crossReferences:
          $ref: '#/components/schemas/CrossReferences'
    CrossReferences:
      type: object
      description: Cross-references to identifiers in other systems
      properties:
        spglobalCompanyId:
          type: string
          description: S&P Global Company ID (Capital IQ)
          example: '0078552'
        ticker:
          type: string
          description: Primary exchange ticker symbol
          example: AAPL
        cusip:
          type: string
          description: CUSIP identifier
          example: 037833100
        isin:
          type: string
          description: ISIN identifier
          example: US0378331005
        lei:
          type: string
          description: Legal Entity Identifier
          example: HWUPKR0MPOU8FGXBT394
    SearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/EntityCandidate'
        total:
          type: integer
          description: Total number of matching results