openapi: 3.0.3
info:
  title: Fundable Companies API
  description: |
    API for accessing company data including search, detailed company information, and filtered company discovery.

    ## Authentication
    All API requests require authentication using an API key in the Authorization header.

    ## Rate Limits
    API usage is tracked and may be subject to monthly limits depending on your API key tier.

    ## Company Identifiers
    Companies can be identified using query parameters with any of the following formats:
    - `id` - UUID format (e.g., "?id=550e8400-e29b-41d4-a716-446655440000")
    - `domain` - Domain or full URL (e.g., "?domain=stripe.com" or "?domain=https://stripe.com")
    - `linkedin` - LinkedIn company URL (e.g., "?linkedin=https://linkedin.com/company/stripe")
    - `crunchbase` - Crunchbase organization URL (e.g., "?crunchbase=https://crunchbase.com/organization/stripe")

    ## Parameter Validation (for /companies endpoint)
    The /companies endpoint (POST) enforces strict validation on the JSON request body:
    - **Unknown Fields**: Any field not in the allowed set will result in a `422 UNKNOWN_PARAMETER` error
    - **Enum Values**: Fields like `financing_types`, `sort_by`, `employee_count`, and `ipo_status` only accept exact enum values
    - **Data Types**: Numeric fields must be valid numbers, dates must be valid ISO 8601 format
    - **Array Fields**: Cannot be empty arrays; provide values or omit the field entirely

    ## Semantic Search
    The /companies endpoint supports AI-powered semantic search via `company.search_query`.
    First use /industry/search and apply a structured taxonomy filter when an appropriate
    industry or super category exists. Use semantic search only for a **niche industry or
    specific product type** the taxonomy cannot express, describing what a company does — its
    product, technology, or business model (e.g. "AI-powered medical imaging diagnostics" or
    "vertical SaaS for dental practices"). It is not a keyword filter: do not put other
    attributes like stage, location, funding, or employee count in `search_query` — apply those
    with the dedicated filter fields instead. Results include a `similarity` score (0-1), are
    sorted by relevance, and are capped at 150 semantic matches.

  version: 1.0.0
  contact:
    name: Fundable API Support
    url: jacob@tryfundable.ai
  license:
    name: Proprietary
    url: https://www.tryfundable.ai/terms/privacy/

servers:
  - url: https://www.tryfundable.ai/api/v1
    description: Production server

security:
  - bearerAuth: []

paths:
  /company:
    get:
      summary: Get company details and recent funding by identifier
      description: |
        Use this endpoint when one company is already identified and its full profile and
        latest funding round are required. Prefer a domain or LinkedIn URL when available;
        they can be passed directly here without calling `/company/search` first.

        Use `/company/search` for fuzzy company-name resolution or an uncertain identifier.
        Use `POST /companies` to discover or batch-retrieve multiple companies.

        Provide ONE of the following query parameters to identify the company:
        - `id` - Company UUID
        - `domain` - Company domain or full URL (e.g., "stripe.com" or "https://stripe.com")
        - `linkedin` - LinkedIn company URL
        - `crunchbase` - Crunchbase organization URL

        The response includes the company's latest funding round details with participating investors.
      operationId: getCompany
      parameters:
        - name: id
          in: query
          description: Company UUID
          required: false
          schema:
            type: string
            format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        - name: domain
          in: query
          description: Company domain or full URL (e.g., "stripe.com" or "https://stripe.com") — URLs are automatically parsed to extract the domain
          required: false
          schema:
            type: string
          example: "stripe.com"
        - name: linkedin
          in: query
          description: LinkedIn company URL
          required: false
          schema:
            type: string
          example: "https://linkedin.com/company/stripe"
        - name: crunchbase
          in: query
          description: Crunchbase organization URL
          required: false
          schema:
            type: string
          example: "https://crunchbase.com/organization/stripe"
      responses:
        '200':
          description: Successful response with company data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      company:
                        $ref: '#/components/schemas/CompanyDetails'
                  meta:
                    type: object
                    properties:
                      page:
                        type: integer
                        example: 0
                      page_size:
                        type: integer
                        example: 1
                      credits_used:
                        type: integer
                        description: Number of credits consumed by this request
                        example: 10
                      credit_source:
                        type: string
                        nullable: true
                        enum: ['monthly', 'purchased']
                        description: Source of credits used (only included for non-API tier keys)
                        example: "monthly"
                      monthly_credits_remaining:
                        type: integer
                        nullable: true
                        description: Remaining monthly credits (only included for non-API tier keys)
                        example: 990
                      purchased_credits_remaining:
                        type: integer
                        nullable: true
                        description: Remaining purchased credits (only included for non-API tier keys)
                        example: 500
                required:
                  - success
                  - data
                  - meta
        '400':
          description: Bad request - missing identifier or invalid format
          content:
            application/json:
              schema:
                type: object
                description: Missing identifier error
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: 'MISSING_IDENTIFIER'
                      message:
                        type: string
                        example: "Company identifier is required"
                      details:
                        type: object
                        properties:
                          help:
                            type: string
                            example: "Provide an identifier using one of the query parameters: id, domain, linkedin, or crunchbase"
                          examples:
                            type: object
                            properties:
                              byDomain:
                                type: string
                                example: "/api/v1/company?domain=stripe.com"
                              byLinkedIn:
                                type: string
                                example: "/api/v1/company?linkedin=https://linkedin.com/company/stripe"
                              byCrunchbase:
                                type: string
                                example: "/api/v1/company?crunchbase=https://crunchbase.com/organization/stripe"
                              byId:
                                type: string
                                example: "/api/v1/company?id=550e8400-e29b-41d4-a716-446655440000"
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
        '404':
          description: Company not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '402':
          description: Insufficient credits to complete request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientCreditsError'
        '429':
          description: Rate limit exceeded (per-minute)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying
              schema:
                type: integer
                example: 60
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'

  /company/deals:
    get:
      summary: Get deals for a company by identifier
      description: |
        Use this endpoint when a company is already identified and its complete funding
        history is required. Prefer a domain or LinkedIn URL when available; it can be
        passed directly without first calling `/company/search`.

        This route retrieves history for one identified company. Use `POST /deals` instead
        to discover rounds across the market with deal, company, or investor filters.

        Provide ONE of the following query parameters to identify the company:
        - `id` - Company UUID
        - `domain` - Company domain or full URL (e.g., "stripe.com" or "https://stripe.com")
        - `linkedin` - LinkedIn company URL
        - `crunchbase` - Crunchbase organization URL

        The response includes the company's deals with pagination. If the identifier matches multiple companies, deals from all matches are returned.
      operationId: getCompanyDeals
      parameters:
        - name: id
          in: query
          description: Company UUID
          required: false
          schema:
            type: string
            format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        - name: domain
          in: query
          description: Company domain or full URL (e.g., "stripe.com" or "https://stripe.com") — URLs are automatically parsed to extract the domain
          required: false
          schema:
            type: string
          example: "stripe.com"
        - name: linkedin
          in: query
          description: LinkedIn company URL
          required: false
          schema:
            type: string
          example: "https://linkedin.com/company/stripe"
        - name: crunchbase
          in: query
          description: Crunchbase organization URL
          required: false
          schema:
            type: string
          example: "https://crunchbase.com/organization/stripe"
        - name: page
          in: query
          description: Page number (0-based)
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 0
        - name: page_size
          in: query
          description: Number of results per page (1-500)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 10
          example: 10
      responses:
        '200':
          description: Successful response with deals for the company
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      deals:
                        type: array
                        items:
                          $ref: '#/components/schemas/CompanyDeal'
                  meta:
                    type: object
                    properties:
                      total_count:
                        type: integer
                        description: Total number of deals for this company
                        example: 11
                      page:
                        type: integer
                        example: 0
                      page_size:
                        type: integer
                        example: 10
                      credits_used:
                        type: integer
                        description: Number of credits consumed by this request
                        example: 10
                      credit_source:
                        type: string
                        nullable: true
                        enum: ['monthly', 'purchased']
                        description: Source of credits used (only included for non-API tier keys)
                        example: "monthly"
                      monthly_credits_remaining:
                        type: integer
                        nullable: true
                        description: Remaining monthly credits (only included for non-API tier keys)
                        example: 990
                      purchased_credits_remaining:
                        type: integer
                        nullable: true
                        description: Remaining purchased credits (only included for non-API tier keys)
                        example: 500
                required:
                  - success
                  - data
                  - meta
        '400':
          description: Validation error (missing, multiple, or invalid identifier)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - MISSING_IDENTIFIER
                          - MULTIPLE_IDENTIFIERS
                          - INVALID_PARAMETER
                          - INVALID_DOMAIN
                          - INVALID_LINKEDIN_URL
                          - INVALID_CRUNCHBASE_URL
                          - INVALID_PAGE
                          - INVALID_PAGE_SIZE
                        example: "MISSING_IDENTIFIER"
                      message:
                        type: string
                        example: "An identifier parameter is required"
                      details:
                        type: object
                        properties:
                          help:
                            type: string
                            example: "Provide one of: domain, linkedin, or crunchbase. Example: ?domain=stripe.com"
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
        '404':
          description: No company found matching the provided identifier
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - NOT_FOUND
                        example: "NOT_FOUND"
                      message:
                        type: string
                        example: "No company found matching the provided identifier"
                      details:
                        type: object
                        properties:
                          identifier_type:
                            type: string
                            example: "domain"
                          identifier_value:
                            type: string
                            example: "nonexistent.com"
        '402':
          description: Insufficient credits to complete request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientCreditsError'
        '429':
          description: Rate limit exceeded (per-minute)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying
              schema:
                type: integer
                example: 60
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'

  /company/search:
    get:
      summary: Search for a company by name, domain, LinkedIn, or Crunchbase
      description: |
        Use this endpoint primarily to resolve a fuzzy company name or an uncertain
        identifier into matching company records. If a reliable domain or LinkedIn URL is
        already available, skip this search and pass it directly to `GET /company` for one
        full profile or to `POST /companies` for a batch lookup.

        Exactly one parameter must be provided.

        **Search types:**
        - `name` — Fuzzy name search with relevance scoring
        - `domain` — Company domain or full URL
        - `linkedin` — LinkedIn company URL
        - `crunchbase` — Crunchbase organization URL

        Examples:
        - `?linkedin=https://linkedin.com/company/stripe`
        - `?crunchbase=https://crunchbase.com/organization/notion`
      operationId: searchCompany
      parameters:
        - name: name
          in: query
          description: Fuzzy search by company name
          required: false
          schema:
            type: string
          example: "stripe"
        - name: domain
          in: query
          description: Company domain or full URL (e.g., "stripe.com" or "https://stripe.com") — URLs are automatically parsed to extract the domain
          required: false
          schema:
            type: string
          example: "stripe.com"
        - name: linkedin
          in: query
          description: LinkedIn company URL
          required: false
          schema:
            type: string
          example: "https://linkedin.com/company/stripe"
        - name: crunchbase
          in: query
          description: Crunchbase organization URL
          required: false
          schema:
            type: string
          example: "https://crunchbase.com/organization/notion"
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      companies:
                        type: array
                        items:
                          $ref: '#/components/schemas/CompanySearchResult'
                  meta:
                    type: object
                    properties:
                      total_count:
                        type: integer
                        description: Number of companies returned
                        example: 1
                      page:
                        type: integer
                        example: 0
                      page_size:
                        type: integer
                        example: 1
                      credits_used:
                        type: integer
                        description: Number of credits consumed by this request
                        example: 0
                      credit_source:
                        type: string
                        nullable: true
                        enum: ['monthly', 'purchased']
                        description: Source of credits used (only included for non-API tier keys)
                        example: "monthly"
                      monthly_credits_remaining:
                        type: integer
                        nullable: true
                        description: Remaining monthly credits (only included for non-API tier keys)
                        example: 990
                      purchased_credits_remaining:
                        type: integer
                        nullable: true
                        description: Remaining purchased credits (only included for non-API tier keys)
                        example: 500
                required:
                  - success
                  - data
                  - meta
        '400':
          description: Validation error (missing, multiple, or invalid parameters)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - MISSING_SEARCH_PARAMS
                          - MULTIPLE_SEARCH_PARAMS
                          - EMPTY_SEARCH_TERM
                          - INVALID_DOMAIN
                          - INVALID_LINKEDIN_URL
                          - INVALID_CRUNCHBASE_URL
                        example: "MULTIPLE_SEARCH_PARAMS"
                      message:
                        type: string
                        example: "Only one search parameter is allowed at a time"
                      details:
                        type: object
                        properties:
                          help:
                            type: string
                            example: "You provided: name, domain. Please use only one of: name, domain, linkedin, or crunchbase"
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
        '402':
          description: Insufficient credits to complete request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientCreditsError'
        '429':
          description: Rate limit exceeded (per-minute)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying
              schema:
                type: integer
                example: 60
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'

  /companies:
    post:
      summary: Discover companies with metadata and full latest-deal details
      description: |
        Use this endpoint by default for company sourcing and discovery. It returns company
        metadata such as name and domain together with the full details of each company's
        latest funding round.

        Filters inside `latest_deal` apply only to the company's most recent round. Use
        `POST /deals` instead when deal criteria must match any round in a company's history.
        For example, `/companies` is appropriate for "find AI companies in San Francisco
        whose latest round was Seed"; `/deals` is appropriate for "analyze all Seed rounds
        announced last year," regardless of whether Seed is now the company's latest round.

        Filters inside `investors` can match investor participation across all rounds.

        ## Request Body Structure
        Send a JSON body with up to 4 filter sections plus pagination/sort at the top level:
        - `identifiers` - Look up specific companies by UUID, domain, LinkedIn, or Crunchbase
        - `company` - Filter by company attributes (search, location, industry, size, etc.)
        - `latest_deal` - Filter by latest funding round attributes (type, size, date, investors)
        - `investors` - Filter by investors (firms or people) across all rounds
      operationId: searchCompanies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                page_size: 10
              properties:
                identifiers:
                  type: object
                  description: Look up specific companies by identifier
                  properties:
                    ids:
                      type: array
                      description: Company UUIDs
                      items:
                        type: string
                        format: uuid
                      example: ["97ae048e-77bc-471b-821a-f9decb373689"]
                    domains:
                      type: array
                      description: Company domains (max 100)
                      items:
                        type: string
                      example: ["stripe.com", "airbnb.com"]
                    linkedin_urls:
                      type: array
                      description: LinkedIn company URLs (max 100)
                      items:
                        type: string
                      example: ["https://linkedin.com/company/stripe", "https://linkedin.com/company/airbnb"]
                    crunchbase_urls:
                      type: array
                      description: Crunchbase organization URLs (max 100)
                      items:
                        type: string
                      example: ["https://crunchbase.com/organization/stripe", "https://crunchbase.com/organization/airbnb"]
                company:
                  type: object
                  description: Company attribute filters
                  properties:
                    search_query:
                      type: string
                      description: >-
                        AI-powered semantic search — a flexible replacement for an
                        industry tag. First use /industry/search and apply an `industries`
                        or `super_categories` filter when the taxonomy contains the intended
                        category. Use semantic search only for a niche industry or specific
                        product type the taxonomy cannot express, describing what the company
                        does — its product, technology, or business model (e.g. "AI-powered
                        medical imaging diagnostics" or "vertical SaaS for dental practices").
                        Do NOT use it for other attributes like stage, location, funding,
                        or employee count — apply those with the dedicated filter fields
                        instead. Results include a similarity score, are sorted by relevance,
                        and are capped at 150 semantic matches.
                      example: "AI-powered medical imaging diagnostics software"
                    min_relevance:
                      type: number
                      minimum: 0
                      maximum: 1
                      description: Minimum similarity threshold (0-1). Only applies with search_query.
                      example: 0.5
                    locations:
                      type: array
                      description: Location permalinks. Use /location/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).
                      items:
                        type: string
                      example: ["san-francisco-california", "california"]
                    industries:
                      type: array
                      description: Industry permalinks. Use /industry/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).
                      items:
                        type: string
                      example: ["artificial-intelligence", "fintech-e067"]
                    super_categories:
                      type: array
                      description: Super category permalinks (automatically includes related industries). Use /industry/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).
                      items:
                        type: string
                      example: ["artificial-intelligence-e551"]
                    employee_count:
                      type: array
                      description: "Employee count ranges. Valid: 1-10, 11-50, 51-100, 101-250, 251-500, 501-1000, 1001-5000, 5001-10000, 10001+"
                      items:
                        type: string
                        enum: ['1-10', '11-50', '51-100', '101-250', '251-500', '501-1000', '1001-5000', '5001-10000', '10001+']
                      example: ["1-10", "11-50"]
                    ipo_status:
                      type: array
                      description: "IPO status filter. Valid: public, private"
                      items:
                        type: string
                        enum: ['public', 'private']
                      example: ["private"]
                    total_raised_min:
                      type: number
                      minimum: 0
                      description: Minimum total raised (USD)
                      example: 10000000
                    total_raised_max:
                      type: number
                      minimum: 0
                      description: Maximum total raised (USD)
                      example: 500000000
                latest_deal:
                  type: object
                  description: Latest funding round filters
                  properties:
                    financing_types:
                      type: array
                      description: "Financing types with optional modifiers (pre, extension)"
                      items:
                        type: object
                        required:
                          - type
                        properties:
                          type:
                            type: string
                            enum: [
                              'SERIES_A', 'SERIES_B', 'SERIES_C', 'SERIES_D', 'SERIES_E', 'SERIES_F',
                              'SERIES_G', 'SERIES_H', 'SERIES_I', 'SERIES_J', 'SERIES_K', 'SERIES_L',
                              'SERIES_M', 'SEED', 'SAFE', 'CONVERTIBLE_NOTE', 'EQUITY', 'PREFERRED',
                              'SECONDARY_MARKET', 'DEBT_FINANCING', 'GRANT', 'NON_EQUITY_ASSISTANCE',
                              'CROWDFUNDING', 'INITIAL_COIN_OFFERING', 'FUNDING_ROUND'
                            ]
                          pre:
                            type: boolean
                            default: false
                            description: "Pre-round modifier (e.g., Pre-Seed, Pre-Series A)"
                          extension:
                            type: boolean
                            default: false
                            description: "Extension round modifier"
                      example:
                        - { "type": "SEED", "pre": true }
                        - { "type": "SERIES_A" }
                    size_min:
                      type: number
                      minimum: 0
                      description: Minimum deal size (USD)
                      example: 1000000
                    size_max:
                      type: number
                      minimum: 0
                      description: Maximum deal size (USD)
                      example: 100000000
                    date_start:
                      type: string
                      format: date
                      description: Latest deal after this date (ISO 8601)
                      example: "2024-01-01"
                    date_end:
                      type: string
                      format: date
                      description: Latest deal before this date (ISO 8601)
                      example: "2024-12-31"
                    created_start:
                      type: string
                      format: date
                      description: >-
                        Latest deal record added to the system on or after this date (ISO 8601).
                        Filters by ingestion date (`created_at`), not the announcement date —
                        useful for finding rounds newly added to Fundable.
                      example: "2024-01-01"
                    created_end:
                      type: string
                      format: date
                      description: >-
                        Latest deal record added to the system on or before this date (ISO 8601).
                        Filters by ingestion date (`created_at`), not the announcement date.
                      example: "2024-12-31"
                    investor_ids:
                      type: array
                      description: Filter by investors who participated in the latest deal only
                      items:
                        type: string
                        format: uuid
                      example: ["c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82"]
                investors:
                  type: object
                  description: Filter by investors (firms or people) across all funding rounds
                  properties:
                    investor_ids:
                      type: array
                      description: Investor UUIDs — matches companies where these investors participated in any round ever
                      items:
                        type: string
                        format: uuid
                      example: ["c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82"]
                    people_ids:
                      type: array
                      description: |
                        Person UUIDs — matches companies where any of these people participated in any round
                        as an **angel investor** OR as a **lead partner** of an investing firm.
                        Resolve via `/people/{id}`.
                      items:
                        type: string
                        format: uuid
                      example: ["b3e9c7d1-2f4a-4d5e-9c1b-7a8f3e2d1c6a"]
                page:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Page number (0-based)
                page_size:
                  type: integer
                  minimum: 1
                  maximum: 500
                  default: 10
                  description: Number of results per page
                sort_by:
                  type: string
                  enum:
                    - 'most_recent_raise'
                    - 'oldest_raise'
                    - 'most_recent_founded'
                    - 'oldest_founded'
                    - 'largest_valuation'
                    - 'smallest_valuation'
                    - 'largest_total_raise'
                    - 'smallest_total_raise'
                    - 'most_funding_rounds'
                    - 'most_investors'
                  default: 'most_recent_raise'
                  description: Sort order. Ignored when search_query is provided (sorted by relevance).
            examples:
              empty:
                summary: Empty request (no filters)
                value:
                  page_size: 5
              filter_only:
                summary: Filter by IPO status and industry
                value:
                  company:
                    ipo_status: ["private"]
                    industries: ["artificial-intelligence"]
                  latest_deal:
                    financing_types:
                      - { "type": "SERIES_A" }
                      - { "type": "SERIES_B" }
                  page_size: 10
              semantic_search:
                summary: AI-powered semantic search
                value:
                  company:
                    search_query: "AI healthcare diagnostics startups"
                  page_size: 5
              batch_lookup:
                summary: Look up specific companies by domain
                value:
                  identifiers:
                    domains: ["stripe.com", "airbnb.com", "notion.so"]

      responses:
        '200':
          description: Successful response with companies data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      companies:
                        type: array
                        items:
                          $ref: '#/components/schemas/CompanyListItem'
                  meta:
                    type: object
                    properties:
                      total_count:
                        type: integer
                        description: Total number of companies matching the filter criteria
                        example: 1547
                      page:
                        type: integer
                        description: Current page number (0-based)
                        example: 0
                      page_size:
                        type: integer
                        description: Number of results per page
                        example: 10
                      credits_used:
                        type: integer
                        description: Number of credits consumed by this request
                        example: 10
                      credit_source:
                        type: string
                        nullable: true
                        enum: ['monthly', 'purchased']
                        description: Source of credits used (only included for non-API tier keys)
                        example: "monthly"
                      monthly_credits_remaining:
                        type: integer
                        nullable: true
                        description: Remaining monthly credits (only included for non-API tier keys)
                        example: 990
                      purchased_credits_remaining:
                        type: integer
                        nullable: true
                        description: Remaining purchased credits (only included for non-API tier keys)
                        example: 500
                required:
                  - success
                  - data
                  - meta
        '400':
          description: Bad Request - Invalid parameter types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
        '422':
          description: Unprocessable Entity - Unknown parameter provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '402':
          description: Insufficient credits to complete request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientCreditsError'
        '429':
          description: Rate limit exceeded (per-minute)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying
              schema:
                type: integer
                example: 60
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |
        API key authentication using Bearer token format.
        Format: `Authorization: Bearer vg_your_api_key_here`

        API keys follow the pattern: `vg_[12_hex_chars]_[32_base64url_chars]`

  schemas:
    CompanyDetails:
      type: object
      description: Full company details returned by the /company endpoint
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the company
          example: "550e8400-e29b-41d4-a716-446655440000"
        name:
          type: string
          nullable: true
          description: Company name
          example: "Acme Corporation"
        legal_name:
          type: string
          nullable: true
          description: Legal name of the company
          example: "Acme Corporation Inc."
        guru_permalink:
          type: string
          nullable: true
          description: Fundable permalink for the company
          example: "acme-corporation"
        domain:
          type: string
          nullable: true
          description: Company website domain
          example: "acme.com"
        region:
          type: string
          nullable: true
          description: Company region
          example: "San Francisco Bay Area"
        operating_status:
          type: string
          nullable: true
          description: Current operating status of the company
          example: "active"
        founded_date:
          type: string
          format: date-time
          nullable: true
          description: Date and time the company was founded
          example: "2010-01-01T00:00:00.000Z"
        acquired:
          type: boolean
          nullable: true
          description: Whether the company has been acquired
          example: false
        short_description:
          type: string
          nullable: true
          description: Brief description of the company
        long_description:
          type: string
          nullable: true
          description: Full description of the company. Available on /company endpoint; may be null on /companies list endpoint.
        num_employees:
          type: string
          nullable: true
          description: Number of employees range
          example: "11-50"
        linkedin:
          type: string
          nullable: true
          format: uri
          description: LinkedIn profile URL
        twitter:
          type: string
          nullable: true
          format: uri
          description: Twitter profile URL
        facebook:
          type: string
          nullable: true
          format: uri
          description: Facebook profile URL
        pitchbook:
          type: string
          nullable: true
          format: uri
          description: PitchBook profile URL
        crunchbase:
          type: string
          nullable: true
          format: uri
          description: Crunchbase profile URL
        address:
          type: string
          nullable: true
          description: Company address
        ipo_status:
          type: string
          nullable: true
          description: IPO status of the company
          enum: ['public', 'private']
          example: "private"
        num_funding_rounds:
          type: integer
          nullable: true
          description: Number of funding rounds
          example: 11
        num_investors:
          type: integer
          nullable: true
          description: Number of investors
          example: 14
        total_raised:
          type: number
          nullable: true
          description: Total amount raised (USD)
          example: 2834940000
        latest_valuation_usd:
          type: number
          nullable: true
          description: Latest valuation (USD)
          example: 31000000000
        latest_valuation_date:
          type: string
          format: date-time
          nullable: true
          description: Date of latest valuation
          example: "2017-03-09T00:00:00.000Z"
        industries:
          type: array
          description: Industries the company operates in
          items:
            type: object
            properties:
              permalink:
                type: string
                description: Industry permalink
                example: "artificial-intelligence"
              name:
                type: string
                description: Industry name
                example: "Artificial Intelligence"
        location:
          type: object
          description: Company location hierarchy
          properties:
            region:
              type: object
              nullable: true
              properties:
                name:
                  type: string
                  description: Region name
                  example: "San Francisco Bay Area"
                permalink:
                  type: string
                  description: Region permalink
                  example: "san-francisco-bay-area"
            country:
              type: object
              nullable: true
              properties:
                name:
                  type: string
                  description: Country name
                  example: "United States"
                permalink:
                  type: string
                  description: Country permalink
                  example: "united-states"
            state:
              type: object
              nullable: true
              properties:
                name:
                  type: string
                  description: State name
                  example: "California"
                permalink:
                  type: string
                  description: State permalink
                  example: "california"
            city:
              type: object
              nullable: true
              properties:
                name:
                  type: string
                  description: City name
                  example: "San Francisco"
                permalink:
                  type: string
                  description: City permalink
                  example: "san-francisco-california"
        latest_deal:
          $ref: '#/components/schemas/LatestDeal'
        all_investor_ids:
          type: array
          nullable: true
          description: UUIDs of all parent investors across all funding rounds for this company
          items:
            type: string
            format: uuid
          example: ["c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82", "c6bc63af-cb37-453d-9c20-35f56fb87ee9"]
        similarity:
          type: number
          nullable: true
          description: Semantic similarity score (0-1). Only present when using search_query parameter.
          example: null

    CompanyListItem:
      type: object
      description: Company object returned by the /companies list endpoint. Same shape as CompanyDetails.
      allOf:
        - $ref: '#/components/schemas/CompanyDetails'

    LatestDeal:
      type: object
      nullable: true
      description: Details of the company's most recent funding round
      properties:
        id:
          type: string
          format: uuid
          nullable: true
          description: Unique identifier for the deal
        type:
          type: string
          nullable: true
          description: Type of funding round
          enum: [
            'SERIES_A', 'SERIES_B', 'SERIES_C', 'SERIES_D', 'SERIES_E', 'SERIES_F',
            'SERIES_G', 'SERIES_H', 'SERIES_I', 'SERIES_J', 'SERIES_K', 'SERIES_M',
            'SEED', 'SAFE', 'CONVERTIBLE_NOTE', 'EQUITY', 'PREFERRED', 'SECONDARY_MARKET',
            'DEBT_FINANCING', 'GRANT', 'NON_EQUITY_ASSISTANCE', 'CROWDFUNDING',
            'INITIAL_COIN_OFFERING', 'FUNDING_ROUND', 'HYBRID', 'HYBRID_SEED',
            'HYBRID_SERIES_A', 'HYBRID_SERIES_B', 'HYBRID_SERIES_C', 'HYBRID_SERIES_D',
            'HYBRID_SERIES_E', 'HYBRID_SERIES_F', 'HYBRID_SERIES_G', 'HYBRID_SERIES_H',
            'HYBRID_SERIES_I', 'HYBRID_SERIES_J', 'HYBRID_SERIES_K', 'HYBRID_SERIES_M'
          ]
          example: "SERIES_B"
        total_round_raised:
          type: number
          nullable: true
          description: Total amount raised in the round (USD)
          example: 25000000
        date:
          type: string
          format: date-time
          nullable: true
          description: Date of the funding round
          example: "2024-01-15T00:00:00Z"
        extension:
          type: boolean
          nullable: true
          description: Whether this is an extension round
          example: false
        pre:
          type: boolean
          nullable: true
          description: Whether this is a pre-round (e.g., Pre-Series A)
          example: false
        intermediate:
          type: string
          nullable: true
          description: Intermediate round designation
          enum: ['PLUS', 'NONE', 'ONE', 'TWO', 'THREE', 'FOUR', 'FIVE', 'SIX', 'SEVEN', 'EIGHT']
          example: "NONE"
        description:
          type: object
          nullable: true
          properties:
            short_description:
              type: string
              nullable: true
              description: Brief description of the deal
            long_description:
              type: string
              nullable: true
              description: Detailed description of the deal
        investors:
          type: array
          description: UUIDs of firm investors participating in this deal. Angels are surfaced separately in `angel_investor_ids`.
          items:
            type: string
            format: uuid
          example: ["c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82", "c6bc63af-cb37-453d-9c20-35f56fb87ee9"]
        angel_investor_ids:
          type: array
          description: UUIDs of angel investors (people) on this latest deal. Resolve via `/people/{id}`. Empty array when no angels.
          items:
            type: string
            format: uuid
          example: ["b3e9c7d1-2f4a-4d5e-9c1b-7a8f3e2d1c6a"]
        financings:
          type: array
          description: Individual financing tranches in this deal
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: Unique identifier for the financing
              type:
                type: string
                description: Type of financing
              size_usd:
                type: number
                nullable: true
                description: Financing amount in USD
                example: 25000000
              size_native:
                type: number
                nullable: true
                description: Financing amount in native currency
                example: 25000000
              currency:
                type: string
                nullable: true
                description: Currency code for size_native
                example: "USD"
        articles:
          type: array
          description: Related articles/sources for the latest deal. Always included; empty when no sources exist.
          items:
            $ref: '#/components/schemas/DealArticle'
      required:
        - id
        - type
        - total_round_raised
        - date
        - extension
        - pre
        - intermediate
        - description
        - investors
        - angel_investor_ids
        - financings
        - articles

    LocationInfo:
      type: object
      nullable: true
      properties:
        name:
          type: string
          description: Location name
        permalink:
          type: string
          description: Location permalink

    CompanySearchResult:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the company
          example: "550e8400-e29b-41d4-a716-446655440000"
        guru_permalink:
          type: string
          nullable: true
          description: Fundable permalink for the company
          example: "acme-corporation"
        name:
          type: string
          description: Company name
          example: "Acme Corporation"
        short_description:
          type: string
          nullable: true
          description: Brief description of the company
          example: "AI-powered solutions for modern enterprises"
        relevance_score:
          type: number
          description: Search relevance score (0-1)
          example: 0.95
        domain:
          type: string
          nullable: true
          description: Company website domain
          example: "acme.com"
        linkedin:
          type: string
          nullable: true
          description: LinkedIn profile URL
        crunchbase:
          type: string
          nullable: true
          description: Crunchbase profile URL

    CompanyDeal:
      type: object
      description: Deal returned by the /company/deals endpoint. Same shape as the Deal schema in the Deals API.
      properties:
        id:
          type: string
          format: uuid
        round_type:
          type: string
          nullable: true
        extension:
          type: boolean
          nullable: true
        intermediate:
          type: string
          nullable: true
        pre:
          type: boolean
          nullable: true
        date:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true
        total_round_raised:
          type: number
          nullable: true
        deal_descriptions:
          type: object
          nullable: true
          properties:
            short_description:
              type: string
              nullable: true
            long_description:
              type: string
              nullable: true
        company_id:
          type: string
          format: uuid
        investor_ids:
          type: array
          description: UUIDs of firm investors participating in this deal. Angels are surfaced separately in `angel_investor_ids`.
          items:
            type: string
            format: uuid
        angel_investor_ids:
          type: array
          description: UUIDs of angel investors (people) on this deal. Resolve via `/people/{id}`. Empty array when no angels.
          items:
            type: string
            format: uuid
        financings:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              type:
                type: string
              size_usd:
                type: number
                nullable: true
              size_native:
                type: number
                nullable: true
              currency:
                type: string
                nullable: true
        valuation:
          type: object
          nullable: true
          properties:
            valuation_currency:
              type: string
              nullable: true
            valuation_usd:
              type: number
              nullable: true
            valuation_native:
              type: number
              nullable: true
            type:
              type: string
        articles:
          type: array
          description: Related articles/sources for this deal. Always included; empty when no sources exist.
          items:
            $ref: '#/components/schemas/DealArticle'
      required:
        - id
        - round_type
        - extension
        - intermediate
        - pre
        - date
        - created_at
        - total_round_raised
        - deal_descriptions
        - company_id
        - investor_ids
        - angel_investor_ids
        - financings
        - valuation
        - articles

    DealArticle:
      type: object
      description: An article or source related to a deal
      properties:
        link:
          type: string
          nullable: true
          description: URL of the article
          example: "https://techcrunch.com/2024/01/15/company-raises-series-a"
        date:
          type: string
          nullable: true
          description: Date of the article
          example: "2024-01-15"
        is_primary:
          type: boolean
          description: Whether this is the primary source article for the deal
          example: true
      required:
        - is_primary

    ValidationError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum: ['VALIDATION_ERROR']
              example: 'VALIDATION_ERROR'
            message:
              type: string
              example: "Invalid request parameters"
            details:
              type: object
              properties:
                errors:
                  type: array
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                        description: The parameter name that failed validation
                        example: "financing_types"
                      value:
                        type: string
                        description: The invalid value provided
                        example: "series-a"
                      message:
                        type: string
                        description: Human-readable error message
                        example: "Invalid financing type(s): series-a. Valid options are: SERIES_A, SERIES_B, SEED, ..."
                      code:
                        type: string
                        description: Machine-readable error code
                        example: "INVALID_FINANCING_TYPE"
                      validOptions:
                        type: array
                        items:
                          type: string
                        description: List of valid values for enum parameters
                        example: ["SERIES_A", "SERIES_B", "SEED"]
                help:
                  type: string
                  example: "Please check your request parameters and ensure they meet the required format and constraints."
      required:
        - error

    AuthError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum: ['AUTH_ERROR', 'INVALID_API_KEY', 'INACTIVE_API_KEY']
              example: 'AUTH_ERROR'
            message:
              type: string
              example: "API key not provided"
            details:
              type: object
              properties:
                help:
                  type: string
                  example: "Please provide your API key in the Authorization header"
                format:
                  type: string
                  example: "Bearer vg_your_api_key_here"
      required:
        - error

    RateLimitError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: 'RATE_LIMIT_EXCEEDED'
            message:
              type: string
              example: "Rate limit exceeded. Maximum 200 requests per minute."
            details:
              type: object
              properties:
                limit:
                  type: integer
                  description: Maximum requests allowed per window
                  example: 200
                window:
                  type: string
                  description: Rate limit window duration
                  example: "60 seconds"
                help:
                  type: string
                  example: "Please reduce your request frequency and try again."
      required:
        - error

    InsufficientCreditsError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: 'INSUFFICIENT_CREDITS'
            message:
              type: string
              example: "Not enough credits to complete this request. Visit https://www.tryfundable.ai/api-access to purchase more."
            details:
              type: object
              properties:
                credits_needed:
                  type: integer
                  nullable: true
                  description: Number of credits required (included when known post-execution)
                  example: 25
                monthly_credits_remaining:
                  type: integer
                  description: Remaining monthly credits
                  example: 0
                purchased_credits_remaining:
                  type: integer
                  description: Remaining purchased credits
                  example: 0
                help:
                  type: string
                  example: "Purchase additional credits at https://www.tryfundable.ai/api-access or upgrade your plan."
      required:
        - error

    ServerError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: 'INTERNAL_SERVER_ERROR'
            message:
              type: string
              example: "An unexpected error occurred"
            details:
              type: string
              nullable: true
              description: Error details (only in development mode)
      required:
        - error

    NotFoundError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum: ['COMPANY_NOT_FOUND']
              example: 'COMPANY_NOT_FOUND'
            message:
              type: string
              example: "Company not found"
            details:
              type: object
              properties:
                help:
                  type: string
                  example: "Please check the company identifier (ID, domain, LinkedIn URL, or Crunchbase URL) and try again"
      required:
        - error

tags:
  - name: companies
    description: Company data, search, and discovery operations