openapi: 3.0.3
info:
  title: Fundable Deals API
  description: |
    API for accessing venture capital deals data with advanced filtering capabilities.

    ## 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.

    ## Request Body Structure
    Send a JSON body with up to 4 filter sections plus pagination/sort at the top level:
    - `identifiers` - Look up specific deals by UUID
    - `deal` - Filter by deal attributes (financing type with pre/extension modifiers, size, date)
    - `company` - Filter by company attributes (location, industry, size, IPO status)
    - `investors` - Filter by investor participation (firms or people, by UUID)

    ## Parameter Validation
    This API enforces strict parameter validation:
    - **Unknown Fields**: Any field not in the allowed list will result in a `422 UNKNOWN_PARAMETER` error
    - **Enum Values**: Parameters like `financing_types`, `sort_by`, `employee_count`, and `ipo_status` only accept exact enum values
    - **Data Types**: Numeric parameters must be valid numbers, dates must be valid ISO 8601 format
    - **Array Parameters**: Cannot be empty arrays; provide values or omit entirely

    ## Validation Errors
    Invalid parameters return detailed error responses with:
    - Specific error codes (e.g., `INVALID_FINANCING_TYPE`, `UNKNOWN_PARAMETER`)
    - Clear error messages explaining what's wrong
    - Valid options for enum parameters
    - Help text and documentation links

  version: 2.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:
  /deals:
    post:
      summary: Find funding rounds across complete company histories
      description: |
        Use this endpoint when the requested result is a set of funding rounds, or when
        deal criteria must match any historical round rather than only each company's
        latest round. It supports round-level analysis across the full deal history.

        For most company-sourcing requests, prefer `POST /companies`: it returns company
        metadata together with the full latest deal. Its `latest_deal` filters apply only
        to each company's most recent round. For example, use `/companies` for "find AI
        companies in San Francisco whose latest round was Seed," but use `/deals` for
        "analyze every Seed round announced last year."

        Deal records contain full round details, but related companies and investors are
        identified by IDs instead of full entity profiles. Use `GET /company?id=...` to
        retrieve company metadata and `GET /deals/{id}/investors` to retrieve the full
        investor lineup for a returned deal.

        ## Request Body Structure
        Send a JSON body with up to 4 filter sections plus pagination/sort at the top level:
        - `identifiers` - Look up specific deals by UUID
        - `deal` - Filter by deal attributes (financing type, size, date)
        - `company` - Filter by company attributes (location, industry, size)
        - `investors` - Filter by investor participation (firms or people, by UUID)
      operationId: searchDeals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                page_size: 10
              properties:
                identifiers:
                  type: object
                  description: Look up specific deals by identifier
                  properties:
                    deal_ids:
                      type: array
                      description: Deal UUIDs
                      items:
                        type: string
                        format: uuid
                      example: ["550e8400-e29b-41d4-a716-446655440000"]
                deal:
                  type: object
                  description: Deal attribute 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: Filter deals announced after this date (ISO 8601)
                      example: "2024-01-01"
                    date_end:
                      type: string
                      format: date
                      description: Filter deals announced before this date (ISO 8601)
                      example: "2024-12-31"
                    created_start:
                      type: string
                      format: date
                      description: Filter deals added to the system after this date (ISO 8601)
                      example: "2024-01-01"
                    created_end:
                      type: string
                      format: date
                      description: Filter deals added to the system before this date (ISO 8601)
                      example: "2024-12-31"
                company:
                  type: object
                  description: Company attribute filters
                  properties:
                    company_ids:
                      type: array
                      description: Company UUIDs - filter deals by specific companies
                      items:
                        type: string
                        format: uuid
                      example: ["550e8400-e29b-41d4-a716-446655440001"]
                    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
                investors:
                  type: object
                  description: Filter by investor participation (firms or people)
                  properties:
                    investor_ids:
                      type: array
                      description: Investor UUIDs (firms)
                      items:
                        type: string
                        format: uuid
                      example: ["c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82"]
                    people_ids:
                      type: array
                      description: |
                        Person UUIDs — matches deals where any of these people participated 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_deal'
                    - 'oldest_deal'
                    - 'largest_raise'
                    - 'smallest_raise'
                  default: 'most_recent_deal'
                  description: Sort order for results
            examples:
              empty:
                summary: Empty request (no filters)
                value:
                  page_size: 5
              filter_by_financing:
                summary: Filter by financing type
                value:
                  deal:
                    financing_types:
                      - { "type": "SERIES_A" }
                      - { "type": "SERIES_B" }
                  page_size: 10
              filter_pre_seed:
                summary: Filter for pre-seed deals
                value:
                  deal:
                    financing_types:
                      - { "type": "SEED", "pre": true }
                  page_size: 10
              filter_by_company:
                summary: Filter by company attributes
                value:
                  company:
                    industries: ["artificial-intelligence"]
                    ipo_status: ["private"]
                  deal:
                    size_min: 5000000
                    size_max: 100000000
                  page_size: 10
              lookup_by_ids:
                summary: Look up specific deals
                value:
                  identifiers:
                    deal_ids: ["550e8400-e29b-41d4-a716-446655440000"]

      responses:
        '200':
          description: Successful response with deals data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      deals:
                        type: array
                        items:
                          $ref: '#/components/schemas/Deal'
                  meta:
                    type: object
                    properties:
                      total_count:
                        type: integer
                        description: Total number of deals 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 or malformed JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
        '422':
          description: Unprocessable Entity - Parameter validation failed
          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'

  /deals/{id}:
    get:
      summary: Get a specific deal by ID
      description: |
        Use this endpoint when a deal UUID is already known and full details for that one
        funding round are required. The response identifies related entities by ID rather
        than embedding their full profiles. Use `GET /company?id=...` for company metadata
        and `GET /deals/{id}/investors` for the complete investor lineup.
      operationId: getDealById
      parameters:
        - name: id
          in: path
          description: Unique identifier for the deal (UUID format)
          required: true
          schema:
            type: string
            format: uuid
            example: "4b20cafe-c22b-441a-8378-53436e1d9edf"
      responses:
        '200':
          description: Successful response with deal data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      deal:
                        $ref: '#/components/schemas/Deal'
                  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: 1
                      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 deal ID format or unsupported query parameters
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                        example: false
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: "INVALID_DEAL_ID"
                          message:
                            type: string
                            example: "Deal ID must be a valid UUID"
                          details:
                            type: object
                            properties:
                              help:
                                type: string
                                example: "Please provide a valid UUID format for the deal ID"
                      statusCode:
                        type: integer
                        example: 400
                  - type: object
                    properties:
                      success:
                        type: boolean
                        example: false
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: "INVALID_PARAMETERS"
                          message:
                            type: string
                            example: "Query parameters are not supported for this endpoint"
                          details:
                            type: object
                            properties:
                              providedParameters:
                                type: array
                                items:
                                  type: string
                                example: ["page", "sort_by"]
                              help:
                                type: string
                                example: "This endpoint only accepts a deal ID in the path. Remove all query parameters."
                      statusCode:
                        type: integer
                        example: 400
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
        '404':
          description: Deal not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: "DEAL_NOT_FOUND"
                      message:
                        type: string
                        example: "Deal not found"
                      details:
                        type: object
                        properties:
                          help:
                            type: string
                            example: "Please check the deal ID and try again"
                  statusCode:
                    type: integer
                    example: 404
        '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'

  /deals/{id}/investors:
    get:
      summary: Get investors for a specific deal
      description: |
        Use this endpoint after identifying a deal when investor IDs in the deal record
        need to be resolved into the complete investor lineup. It returns firm investors,
        associated people, angel investors, lead status, and profile links for one deal.

        Do not use this endpoint to discover investors across many deals. Use
        `POST /investors` when the desired result is a list of firms, or `POST /people`
        with investor filters when the desired result is individual investors.
      operationId: getDealInvestors
      parameters:
        - name: id
          in: path
          description: Unique identifier for the deal (UUID format)
          required: true
          schema:
            type: string
            format: uuid
            example: "4b20cafe-c22b-441a-8378-53436e1d9edf"
      responses:
        '200':
          description: Successful response with deal investors
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      investors:
                        type: array
                        description: Firm investors on this deal. Angels are surfaced separately in `angel_investors`.
                        items:
                          $ref: '#/components/schemas/DealInvestor'
                      angel_investors:
                        type: array
                        description: Angel investors (individuals) on this deal. Empty array when no angels.
                        items:
                          $ref: '#/components/schemas/AngelInvestor'
                    required:
                      - investors
                      - angel_investors
                  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: 1
                      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 deal ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
        '404':
          description: Deal not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: "DEAL_NOT_FOUND"
                      message:
                        type: string
                        example: "Deal not found"
        '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:
    Deal:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the deal
          example: "550e8400-e29b-41d4-a716-446655440000"
        round_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_L',
            'SERIES_M', 'SEED', 'SAFE', 'CONVERTIBLE_NOTE', 'EQUITY', 'PREFERRED',
            'SECONDARY_MARKET', 'DEBT_FINANCING', 'GRANT', 'NON_EQUITY_ASSISTANCE',
            'CROWDFUNDING', 'INITIAL_COIN_OFFERING', 'FUNDING_ROUND'
          ]
          example: "SERIES_A"
        extension:
          type: boolean
          nullable: true
          description: Whether this is an extension round
          example: false
        intermediate:
          type: string
          nullable: true
          description: Intermediate round designation
          enum: ['PLUS', 'NONE', 'ONE', 'TWO', 'THREE', 'FOUR', 'FIVE', 'SIX', 'SEVEN', 'EIGHT']
          example: "NONE"
        pre:
          type: boolean
          nullable: true
          description: Whether this is a pre-round (e.g., Pre-Series A)
          example: false
        date:
          type: string
          format: date-time
          nullable: true
          description: Announcement date of the funding round
          example: "2024-01-15T00:00:00Z"
        created_at:
          type: string
          format: date-time
          nullable: true
          description: Date the deal was added to the system
          example: "2024-01-16T12:30:00Z"
        total_round_raised:
          type: number
          nullable: true
          description: Total amount raised in the round (USD)
          example: 25000000
        deal_descriptions:
          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
        company_id:
          type: string
          format: uuid
          description: Unique identifier for the company
          example: "550e8400-e29b-41d4-a716-446655440001"
        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
          example: ["c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82"]
        angel_investor_ids:
          type: array
          description: UUIDs of angel investors (people) who participated in this 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: Detailed financing information for deals that have multiple financing types
          items:
            $ref: '#/components/schemas/Financing'
        valuation:
          nullable: true
          description: Valuation information for this deal
          $ref: '#/components/schemas/Valuation'
        articles:
          type: array
          description: |
            Related articles/sources for this deal.
            Always included for every API tier. Empty when the deal has no related sources.
          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

    DealInvestor:
      type: object
      description: A firm investor on a deal. Angels are returned separately in the `angel_investors` array on /deals/{id}/investors.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the firm investor (parent_investor UUID)
          example: "c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82"
        name:
          type: string
          description: Investor name
          example: "Sequoia Capital"
        lead_investor:
          type: boolean
          nullable: true
          description: Whether this investor led the round
          example: true
        personnel:
          type: array
          description: Key personnel (partners) at this firm involved in this deal. Each entry is a person record joinable to /people/{id}.
          items:
            $ref: '#/components/schemas/PersonnelMember'
          example:
            - id: "f1a2b3c4-d5e6-7890-abcd-ef1234567890"
              name: "John Smith"
              linkedin: "https://linkedin.com/in/johnsmith"
              crunchbase: "https://crunchbase.com/person/john-smith"
              twitter: "https://x.com/johnsmith"
        financing_type:
          type: string
          nullable: true
          description: The financing type this investor participated in
          example: "SERIES_A"
        domain:
          type: string
          nullable: true
          description: Investor's website domain
          example: "sequoiacap.com"
        linkedin:
          type: string
          nullable: true
          description: Investor's LinkedIn URL
          example: "https://linkedin.com/company/sequoia-capital"
        crunchbase:
          type: string
          nullable: true
          description: Investor's Crunchbase URL
          example: "https://crunchbase.com/organization/sequoia-capital"
      required:
        - id
        - name

    PersonnelMember:
      type: object
      description: A person (partner) at a firm investor associated with a deal.
      properties:
        id:
          type: string
          format: uuid
          description: Person UUID. Resolves via /people/{id}.
        name:
          type: string
          nullable: true
        linkedin:
          type: string
          nullable: true
          description: LinkedIn URL.
        crunchbase:
          type: string
          nullable: true
          description: Crunchbase URL.
        twitter:
          type: string
          nullable: true
          description: Twitter/X URL.
      required:
        - id

    AngelInvestor:
      type: object
      description: An angel (individual) investor on a deal. Returned in the `angel_investors` array on /deals/{id}/investors.
      properties:
        id:
          type: string
          format: uuid
          description: Person UUID for the angel. Resolves via /people/{id}.
        name:
          type: string
          nullable: true
        financing_type:
          type: string
          nullable: true
          description: The financing type this angel participated in.
          example: "SEED"
        linkedin:
          type: string
          nullable: true
        crunchbase:
          type: string
          nullable: true
        twitter:
          type: string
          nullable: true
      required:
        - id

    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

    Financing:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the financing
        type:
          type: string
          description: Type of financing
          enum: [
            'SEED', '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', 'CONVERTIBLE_NOTE', 'CROWDFUNDING', 'DEBT_FINANCING',
            'EQUITY', 'FUNDING_ROUND', 'GRANT', 'INITIAL_COIN_OFFERING',
            'NON_EQUITY_ASSISTANCE', 'PREFERRED', 'SAFE', 'SECONDARY_MARKET'
          ]
          example: "SERIES_A"
        size_usd:
          type: number
          nullable: true
          description: Financing amount (USD)
          example: 25000000
        size_native:
          type: number
          nullable: true
          description: Financing amount in native currency
          example: 25000000
        currency:
          type: string
          nullable: true
          description: Currency of the original financing amount
          example: "USD"
      required:
        - id
        - type

    Valuation:
      type: object
      nullable: true
      properties:
        valuation_currency:
          type: string
          nullable: true
          description: Currency of the valuation
          example: "USD"
        valuation_usd:
          type: number
          nullable: true
          description: Valuation amount (USD)
          example: 100000000
        valuation_native:
          type: number
          nullable: true
          description: Valuation amount in native currency
          example: 100000000
        type:
          type: string
          description: Type of valuation
          enum: ['DEFAULT', 'POST_MONEY', 'PRE_MONEY']
          example: "POST_MONEY"
      required:
        - type

    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

    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: "deal.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

    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

tags:
  - name: deals
    description: Venture capital deals data