Caplight Comps API

openapi: 3.2.0
info:
  version: 2.0.0
  title: Caplight REST Comps API
  description: 'This page provides documentation for the Caplight API, a paid add-on product of [Caplight Data](https://www.data.caplight.com). To request API access, please contact us at contact@caplight.com.


    # Production server

    https://us-central1-caplight-prod.cloudfunctions.net/api/public


    # Staging/sandbox server

    https://us-central1-caplight-staging.cloudfunctions.net/api/public


    # API versions

    Endpoints are versioned via path prefix: `/v1/` for company, market price, and order book; `/v2/` for company lookup, funding rounds, investors, company details, and comps.


    # Company IDs

    Companies have two ID formats: a **v1 company ID** (used in v1 endpoints) and a **v2 company ID** (used in v2 endpoints). Both v1 and v2 company responses include both in `caplightIds` for cross-referencing. Path params that accept company identifiers support either format, plus PitchBook ID and company domain where applicable.


    If you have a domain, a v1 company ID or a PitchBook ID and need the v2 company ID, call `GET /v2/companies` — it resolves up to 50 identifiers per request and covers companies added recently.


    # V2 Access & Permissions


    **Company access:** v2 company-scoped endpoints (funding rounds, investors, company details, and comps) enforce per-account access control. Your account may have (1) a whitelist of permitted companies, (2) an annual limit on distinct companies you can access, or both. Accessing the same company multiple times counts once toward the limit. The `/funding-rounds/updates` endpoint returns only rounds for companies you have access to.


    **Restricted fields:** Some accounts have field-level restrictions. When a field is restricted, it is omitted from the response and its name appears in `restricted.fields` on the funding round object. Restricted fields may include: `amounts`, `valuation`, `pps`, `participants`, `citations`. Check for a `restricted` object and handle omitted fields in your integration.


    # Widget Embed

    In addition to this API, Caplight also provides an embeddable widget for customers who would like an easy way of integrating Caplight Data into their platform. [See example](https://storage.googleapis.com/caplight-prod.appspot.com/images/embed-example-3.png). For inquiries, please contact us directly.


    # Authentication


    <SecurityDefinitions />

    '
  termsOfService: https://platform.caplight.com/terms
  contact:
    name: 'Contact: Caplight Engineering'
    email: engineering@caplight.com
  x-logo:
    url: https://storage.googleapis.com/caplight-prod.appspot.com/caplight-logos/api-logo.png
    altText: Caplight logo
servers:
- url: //us-central1-caplight-prod.cloudfunctions.net/api/public
  description: Production
- url: //us-central1-caplight-staging.cloudfunctions.net/api/public
  description: Staging/Sandbox
tags:
- name: Comps
  description: LLM-discovered comparable companies with an overall similarity score, a per-dimension breakdown, a classification, and a short rationale.
paths:
  /v2/companies/{companyId}/comps:
    get:
      tags:
      - Comps
      summary: Get company comps
      description: Returns the LLM-discovered comparable companies ("comps") for a company, each with an overall similarity score (0-1), a per-dimension similarity breakdown, a classification, and a short rationale. Comps are ordered by similarity in descending order. Requires comps API access.
      parameters:
      - name: companyId
        in: path
        description: 'Company identifier: v2 company ID, v1 company ID, PitchBook ID (e.g. 41339-53), or company domain (e.g. clickhouse.com). A domain can match more than one company, in which case the best match is used; call `GET /v2/companies` to see every candidate. Access control and the annual distinct-company limit apply the same way however the company is identified.'
        required: true
        schema:
          type: string
      - name: pageNumber
        in: query
        description: Page number (1-based). First page is 1.
        required: false
        schema:
          type: integer
          default: 1
        example: 1
      - name: pageSize
        in: query
        description: Number of results per page (default 50, max 200). Most companies return all comparables in a single page.
        required: false
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 200
        example: 50
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComparablesResponse'
              example:
                company:
                  id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                  name: Acme Inc
                  domain: acme.com
                  pitchbookId: 41339-53
                  caplightIds:
                    v2Id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                    v1Id: abc123xyz
                comparables:
                - name: Globex Corp
                  domain: globex.com
                  caplightIds:
                    v2Id: c3d4e5f6-a7b8-9012-cdef-234567890123
                    v1Id: def456uvw
                  ticker: null
                  isPublic: false
                  productName: null
                  subsidiaryName: null
                  classification: pure_play
                  similarity: 0.82
                  similarityExplanation: Same product category, overlapping customers.
                  similarityBreakdown:
                  - key: product
                    label: Product overlap
                    score: 0.9
                    reasoning: Both operate two-sided payment networks.
                  - key: customer
                    label: Customer overlap
                    score: 0.8
                    reasoning: Shared enterprise customer base.
                  description: A close competitor in the enterprise widget space.
                  generatedAt: '2026-01-15T12:00:00.000Z'
                pagination:
                  pageNumber: 1
                  numPages: 1
                  totalRecords: 1
components:
  schemas:
    PublicCompanySummary:
      type: object
      description: Company summary. Companies have two IDs — v1 and v2 — both provided in caplightIds for cross-referencing across API versions.
      properties:
        id:
          type: string
          description: v2 company ID
        name:
          type: string
          description: Company name
        domain:
          type: string
          nullable: true
          description: Company website domain
        pitchbookId:
          type: string
          nullable: true
          description: Pitchbook company ID
        caplightIds:
          type: object
          description: Both company ID formats for cross-referencing v1 and v2 endpoints
          properties:
            v2Id:
              type: string
              description: v2 company ID (same as id)
            v1Id:
              type: string
              nullable: true
              description: v1 company ID (for v1 API endpoints)
    Pagination:
      type: object
      properties:
        pageNumber:
          type: integer
          description: Page number (1-based). First page is 1.
          example: 1
        numPages:
          type: integer
          description: Total number of pages for the result set
          example: 10
        totalRecords:
          type: integer
          description: Total number of records for the result set
          example: 250
    ComparableDimension:
      type: object
      description: 'One similarity sub-dimension: a stable key, a human-readable label, a 0-1 score, and a short rationale.'
      properties:
        key:
          type: string
          example: product
        label:
          type: string
          example: Product overlap
        score:
          type: number
          format: double
          minimum: 0
          maximum: 1
          example: 0.9
        reasoning:
          type: string
          nullable: true
          description: Short LLM rationale for this dimension's score; null when not available.
          example: Both operate two-sided payment networks with overlapping enterprise customers.
    Comparable:
      type: object
      properties:
        name:
          type: string
          example: Globex Corp
        domain:
          type: string
          nullable: true
          example: globex.com
        caplightIds:
          type: object
          nullable: true
          description: The comparable's Caplight ids (v2 + v1) for cross-referencing into other v2/v1 endpoints; null when the comp isn't resolved to a Caplight company.
          properties:
            v2Id:
              type: string
            v1Id:
              type: string
              nullable: true
        ticker:
          type: string
          nullable: true
          description: Stock ticker for public comparables; null for private companies.
          example: ACME
        isPublic:
          type: boolean
          description: Whether the comparable is a publicly traded company.
        productName:
          type: string
          nullable: true
          description: Set when the comparable is scoped to a specific product.
        subsidiaryName:
          type: string
          nullable: true
          description: Set when the comparable is a subsidiary rather than the parent company.
        classification:
          type: string
          enum:
          - pure_play
          - incumbent
          - challenger
          description: How the comparable relates to the target company.
        similarity:
          type: number
          format: double
          minimum: 0
          maximum: 1
          description: Overall weighted similarity score.
          example: 0.82
        similarityExplanation:
          type: string
          description: Short rationale for why this company is a comparable.
          example: Same product category, overlapping customers.
        similarityBreakdown:
          type: array
          items:
            $ref: '#/components/schemas/ComparableDimension'
        description:
          type: string
          description: Description of the comparable company.
        generatedAt:
          type: string
          format: date-time
          description: When this comparable set was generated for the target company.
    ComparablesResponse:
      type: object
      properties:
        company:
          $ref: '#/components/schemas/PublicCompanySummary'
        comparables:
          type: array
          items:
            $ref: '#/components/schemas/Comparable'
        pagination:
          $ref: '#/components/schemas/Pagination'
  securitySchemes:
    api_key:
      description: Caplight API authentication is managed through an api_key header value. Please contact us if you do not yet have an API key.
      type: apiKey
      name: api_key
      in: header
x-tagGroups:
- name: V1
  tags:
  - Company
  - Companies
  - MarketPrice
  - Live Orderbook
  - Trade History
  - Order History
  - Company Filings
  - Stock Splits
  - Fund Marks
  - News
  - company_model
  - order_model
  - market_price_model
  - trade_model
  - 409a_valuation_model
  - fund_mark_model
  - comp_model
  - stock_split_model
  - coi_model
- name: V2
  tags:
  - Funding Rounds
  - Investors
  - Company Lookup
  - Company Details
  - Comps