openapi: 3.0.3
info:
  title: CEORater API
  description: |
    Institutional-grade CEO performance analytics for S&P 500 and major U.S. public companies.
    
    Provides proprietary metrics including:
    - **CEORaterScore** (0-100): Composite CEO effectiveness rating
    - **AlphaScore** (0-100): Performance vs. market benchmark
    - **CompScore** (A-F): Compensation efficiency grade
    
    ## Authentication
    All endpoints require Bearer token authentication.
    API keys begin with `zpka_` and are available after subscribing at the Developer Portal.
    
    ## Response Formats
    Most endpoints support two formats via the `format` query parameter:
    - `ui` (default): Human-readable strings with formatting ("2,223%", "$74.6M")
    - `raw`: Numeric values with camelCase keys (22.23, 74.6)
    
    ## Data Updates
    Dataset refreshes daily on weekdays after U.S. market close.
    
    ## Versioning Policy
    - Major changes use a new base path (for example, `/v2`)
    - Non-breaking additions may appear in the current version
    - Breaking changes include at least 90 days advance notice
  version: 1.1.0
  contact:
    name: CEORater Support
    email: support@ceorater.com
    url: https://www.ceorater.com/support.html
  license:
    name: Proprietary
    url: https://www.ceorater.com/terms.html
  x-logo:
    url: https://www.ceorater.com/android-chrome-512x512.png

externalDocs:
  description: Full API Documentation
  url: https://www.ceorater.com/api-docs.html

servers:
  - url: https://api.ceorater.com
    description: Production API

tags:
  - name: Companies
    description: Retrieve CEO performance data for companies
  - name: Search
    description: Search and filter companies
  - name: Metadata
    description: Dataset information and health checks

security:
  - BearerAuth: []

paths:
  /v1/ceo/{ticker}:
    get:
      tags:
        - Companies
      summary: Get CEO by Ticker
      description: |
        Retrieve detailed CEO performance data for a specific company by stock ticker symbol.
        Returns CEORaterScore, AlphaScore, CompScore, TSR metrics, compensation data, and tenure information.
      operationId: getCeoByTicker
      parameters:
        - name: ticker
          in: path
          required: true
          description: Stock ticker symbol (case-insensitive)
          schema:
            type: string
          examples:
            apple:
              value: AAPL
              summary: Apple Inc.
            microsoft:
              value: MSFT
              summary: Microsoft Corporation
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Successful response with company CEO data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRaw'
              examples:
                raw:
                  summary: Raw format response
                  value:
                    companyName: Apple Inc.
                    ticker: AAPL
                    sector: Technology
                    industry: Computer Manufacturing
                    ceo: Tim Cook
                    founderCEO: false
                    ceoraterScore: 87
                    alphaScore: 93.5
                    compScore: C
                    compensationMM: 74.6
                    tsrMultiple: 22.23
                    tenureYears: 14.4
                    avgAnnualTsrRatio: 1.55
                    compPer1PctTsrMM: 0.482
                    tsrVsSpyRatio: 15.64
                    avgAnnualVsSpyRatio: 1.09
        '401':
          $ref: '#/components/responses/Unauthorized'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'

  /v1/ceos:
    get:
      tags:
        - Companies
      summary: List All CEOs
      description: |
        Retrieve a paginated list of all companies with CEO performance data.
        Supports up to 2000 records per request. Ideal for bulk analysis or building datasets.
      operationId: listCeos
      parameters:
        - name: limit
          in: query
          description: Number of results to return
          schema:
            type: integer
            minimum: 1
            maximum: 2000
            default: 50
        - name: offset
          in: query
          description: Starting position for pagination
          schema:
            type: integer
            minimum: 0
            default: 0
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Paginated list of companies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyListResponse'
              example:
                items:
                  - companyName: Apple Inc.
                    ticker: AAPL
                    sector: Technology
                    industry: Computer Manufacturing
                    ceo: Tim Cook
                    founderCEO: false
                    ceoraterScore: 87
                    alphaScore: 93.5
                    compScore: C
                    compensationMM: 74.6
                    tsrMultiple: 22.23
                    tenureYears: 14.4
                    avgAnnualTsrRatio: 1.55
                    compPer1PctTsrMM: 0.482
                    tsrVsSpyRatio: 15.64
                    avgAnnualVsSpyRatio: 1.09
                total: 517
                offset: 0
                limit: 50
        '401':
          $ref: '#/components/responses/Unauthorized'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'

  /v1/search:
    get:
      tags:
        - Search
      summary: Search CEOs
      description: |
        Search for CEOs by company name, ticker, CEO name, sector, or industry.
        Returns all matching companies with full CEO performance data.
      operationId: searchCeos
      parameters:
        - name: q
          in: query
          required: true
          description: Search query - matches against company name, ticker, CEO name, sector, or industry (case-insensitive)
          schema:
            type: string
          examples:
            sector:
              value: technology
              summary: Search by sector
            ceo:
              value: Tim Cook
              summary: Search by CEO name
            ticker:
              value: AAPL
              summary: Search by ticker
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              example:
                q: technology
                count: 45
                items:
                  - companyName: Apple Inc.
                    ticker: AAPL
                    ceoraterScore: 87
                    alphaScore: 93.5
                    compScore: C
                  - companyName: Microsoft Corp.
                    ticker: MSFT
                    ceoraterScore: 91
                    alphaScore: 89.2
                    compScore: B
        '401':
          $ref: '#/components/responses/Unauthorized'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'

  /v1/meta:
    get:
      tags:
        - Metadata
      summary: Get Dataset Statistics
      description: |
        Retrieve metadata about the CEORater dataset including total company count and last update timestamp.
        Use to verify data freshness before analysis.
      operationId: getDatasetStats
      responses:
        '200':
          description: Dataset metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaResponse'
              example:
                count: 517
                last_loaded: "2026-01-17T08:00:00.000Z"
                base_url: "https://api.ceorater.com"
                docs_url: "https://www.ceorater.com/api-docs.html"
                api_version: "1.1.0"
                request_id: "2f9c2870f486d294"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'


components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        API key authentication. Keys begin with `zpka_` prefix.
        
        Obtain your API key by subscribing at https://www.ceorater.com/api-docs.html
        then accessing the Developer Portal at https://ceorater-api-main-7ef1acf.zuplo.site

  parameters:
    format:
      name: format
      in: query
      description: |
        Response format:
        - `ui`: Human-readable labels and formatted values ("2,223%", "$74.6M")
        - `raw`: Machine-readable camelCase keys and numeric values (22.23, 74.6)
      schema:
        type: string
        enum:
          - ui
          - raw
        default: ui

  schemas:
    CompanyRaw:
      type: object
      description: Company CEO performance data (raw format)
      properties:
        companyName:
          type: string
          description: Full legal company name
          example: Apple Inc.
        ticker:
          type: string
          description: Stock ticker symbol
          example: AAPL
        sector:
          type: string
          description: GICS sector classification
          example: Technology
        industry:
          type: string
          description: Industry classification
          example: Computer Manufacturing
        ceo:
          type: string
          description: Current CEO full name
          example: Tim Cook
        founderCEO:
          type: boolean
          description: Whether CEO is a company founder
          example: false
        ceoraterScore:
          type: integer
          minimum: 0
          maximum: 100
          description: Proprietary composite CEO effectiveness rating
          example: 87
        alphaScore:
          type: number
          minimum: 0
          maximum: 100
          description: Performance vs. market benchmark score
          example: 93.5
        compScore:
          type: string
          enum: [A, B, C, D, F]
          description: Compensation efficiency grade
          example: C
        tsrMultiple:
          type: number
          description: Total Shareholder Return during tenure as a multiple (22.23 = 2,223%)
          example: 22.23
        avgAnnualTsrRatio:
          type: number
          description: Average annual TSR as a ratio (1.55 = 155%)
          example: 1.55
        tsrVsSpyRatio:
          type: number
          description: TSR vs SPY benchmark as a ratio (15.64 = 1,564% outperformance)
          example: 15.64
        avgAnnualVsSpyRatio:
          type: number
          description: Average annual TSR vs SPY as a ratio (1.09 = 109%)
          example: 1.09
        compensationMM:
          type: number
          description: Total CEO compensation in millions USD
          example: 74.6
        compPer1PctTsrMM:
          type: number
          description: CEO compensation cost per 1% TSR in millions USD
          example: 0.482
        tenureYears:
          type: number
          description: CEO tenure in years
          example: 14.4

    CompanyListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CompanyRaw'
        total:
          type: integer
          description: Total number of companies in database
          example: 517
        offset:
          type: integer
          description: Current offset position
          example: 0
        limit:
          type: integer
          description: Number of results returned
          example: 50

    SearchResponse:
      type: object
      properties:
        q:
          type: string
          description: The search query that was executed
          example: technology
        count:
          type: integer
          description: Number of matching companies
          example: 45
        items:
          type: array
          items:
            $ref: '#/components/schemas/CompanyRaw'

    MetaResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of companies in database
          example: 517
        last_loaded:
          type: string
          format: date-time
          description: ISO 8601 timestamp of last data refresh
          example: "2026-01-17T08:00:00.000Z"
        base_url:
          type: string
          format: uri
          description: API base URL
          example: "https://api.ceorater.com"
        docs_url:
          type: string
          format: uri
          description: Public API documentation URL
          example: "https://www.ceorater.com/api-docs.html"
        api_version:
          type: string
          description: Deployed API version
          example: "1.1.0"
        request_id:
          type: string
          description: Request identifier for support and audit troubleshooting
          example: "2f9c2870f486d294"

    Error:
      type: object
      properties:
        ok:
          type: boolean
          example: false
        code:
          type: string
          description: Stable machine-readable error code
          example: BAD_REQUEST
        error:
          type: string
          description: Human-readable error message
          example: Query parameter q is required.
        request_id:
          type: string
          description: Request identifier for support and audit troubleshooting
          example: 2f9c2870f486d294

  responses:
    Unauthorized:
      description: Missing, invalid, or expired API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            ok: false
            code: UNAUTHORIZED
            error: Missing or invalid API key
            request_id: 2f9c2870f486d294

    NotFound:
      description: Ticker not found in database
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            ok: false
            code: NOT_FOUND
            error: Not found
            request_id: 2f9c2870f486d294

    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            ok: false
            code: BAD_REQUEST
            error: Query parameter q is required.
            request_id: 2f9c2870f486d294

    RateLimited:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            ok: false
            code: RATE_LIMITED
            error: Rate limit exceeded. Please retry later.
            request_id: 2f9c2870f486d294
