> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pav.bio/llms.txt
> Use this file to discover all available pages before exploring further.

# List deals

> M&A, licensing, collaborations, options, joint ventures and distribution deals, one row per deal. `q` matches every word of the deal text or part of a party name. `from`/`to` filter on `announced_at`.



## OpenAPI

````yaml /openapi.json get /v1/deals
openapi: 3.1.0
info:
  title: Pav Enterprise API
  description: >-
    Read-only API over Pav's biopharma data: programs, drugs, companies, trials,
    deals, patents, FDA records and changes. Send `Authorization: Bearer
    <api_key>`. Lists return `{data, next_cursor, total}`; errors return
    `{error: {code, message, request_id}}`. Parameter rules:
    [Conventions](https://docs.pav.bio/conventions).
  version: 2.0.0
servers:
  - url: https://api.pav.bio
    description: Production
security: []
tags:
  - name: search
    description: Find the id of a company, drug, program, target or indication.
    x-group: Search
  - name: programs
    description: 'Drug programs: one drug in one indication at one company.'
    x-group: Programs
  - name: drugs
    description: >-
      One drug product across every company that develops it, under all its
      names, with its programs.
    x-group: Drugs
  - name: companies
    description: Biopharma companies, their owners and their trials.
    x-group: Companies
  - name: trials
    description: ClinicalTrials.gov trials linked to programs and companies.
    x-group: Trials
  - name: deals
    description: M&A, licensing and collaboration deals with terms and sources.
    x-group: Deals
  - name: patents
    description: US patent families with owners, members and term.
    x-group: Patents
  - name: fda
    description: FDA records, one endpoint per record type.
    x-group: FDA
  - name: changes
    description: Program and trial changes, newest first.
    x-group: Changes
  - name: stats
    description: Dataset counts.
    x-group: Stats
paths:
  /v1/deals:
    get:
      tags:
        - deals
      summary: List deals
      description: >-
        M&A, licensing, collaborations, options, joint ventures and distribution
        deals, one row per deal. `q` matches every word of the deal text or part
        of a party name. `from`/`to` filter on `announced_at`.
      operationId: list_deals
      parameters:
        - name: q
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 300
              - type: 'null'
            description: Free text.
            title: Q
          description: Free text.
        - name: company_id
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Company ids, comma-separated. Includes the companies each one
              owns.
            examples:
              - '412'
            title: Company Id
          description: Company ids, comma-separated. Includes the companies each one owns.
        - name: drug_id
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Drug ids, comma-separated.
            examples:
              - '5120'
            title: Drug Id
          description: Drug ids, comma-separated.
        - name: deal_type
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Deal types, comma-separated: `acquisition`, `merger`,
              `asset_purchase`, `licensing`, `collaboration`, `option`,
              `joint_venture`, `distribution`, `other`.
            examples:
              - licensing
            title: Deal Type
          description: >-
            Deal types, comma-separated: `acquisition`, `merger`,
            `asset_purchase`, `licensing`, `collaboration`, `option`,
            `joint_venture`, `distribution`, `other`.
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Current lifecycle state (`latest_event_type`), comma-separated:
              `proposed`, `announced`, `completed`, `amended`, `terminated`,
              `update`.
            examples:
              - completed
            title: Status
          description: >-
            Current lifecycle state (`latest_event_type`), comma-separated:
            `proposed`, `announced`, `completed`, `amended`, `terminated`,
            `update`.
        - name: target
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Target name, gene symbol or term id; comma-separated.
            examples:
              - TL1A
            title: Target
          description: Target name, gene symbol or term id; comma-separated.
        - name: modality
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Modality, subclass or format; comma-separated.
            examples:
              - adc
            title: Modality
          description: Modality, subclass or format; comma-separated.
        - name: therapeutic_area
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Areas, comma-separated: `cardiovascular`, `dermatology`,
              `endocrine_metabolic`, `gastroenterology`, `hematology`,
              `hepatology`, `immunology`, `infectious_disease`,
              `musculoskeletal`, `nephrology`, `neurology`, `oncology`,
              `ophthalmology`, `otolaryngology`, `psychiatry`,
              `reproductive_womens_health`, `respiratory`,
              `urology_mens_health`.
            examples:
              - oncology
            title: Therapeutic Area
          description: >-
            Areas, comma-separated: `cardiovascular`, `dermatology`,
            `endocrine_metabolic`, `gastroenterology`, `hematology`,
            `hepatology`, `immunology`, `infectious_disease`, `musculoskeletal`,
            `nephrology`, `neurology`, `oncology`, `ophthalmology`,
            `otolaryngology`, `psychiatry`, `reproductive_womens_health`,
            `respiratory`, `urology_mens_health`.
        - name: min_value_usd
          in: query
          required: false
          schema:
            anyOf:
              - type: number
                minimum: 0
              - type: 'null'
            description: Minimum `total_potential_value` in USD.
            examples:
              - 1000000000
            title: Min Value Usd
          description: Minimum `total_potential_value` in USD.
        - name: from
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date
              - type: 'null'
            description: On or after this date.
            title: From
          description: On or after this date.
        - name: to
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date
              - type: 'null'
            description: On or before this date.
            title: To
          description: On or before this date.
        - name: sort
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              One of `activity_date`, `announced_at`, `completed_at`,
              `total_value`, `total_potential_value`; prefix `-` to descend.
              Default `-activity_date`.
            title: Sort
          description: >-
            One of `activity_date`, `announced_at`, `completed_at`,
            `total_value`, `total_potential_value`; prefix `-` to descend.
            Default `-activity_date`.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 200
            minimum: 1
            description: Rows per page (1-200).
            examples:
              - 50
            default: 50
            title: Limit
          description: Rows per page (1-200).
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 2000
              - type: 'null'
            description: '`next_cursor` from the previous page.'
            title: Cursor
          description: '`next_cursor` from the previous page.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DealListResponse'
        '400':
          description: Invalid parameter (`validation_error`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid API key (`unauthorized`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Unknown id or route (`not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded (`rate_limited`); honor `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - EnterpriseApiKey: []
components:
  schemas:
    DealListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Deal'
          type: array
          title: Data
          description: Page of deals.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: >-
            Pass as `cursor` to get the next page. Null on the last page. See
            [Conventions](https://docs.pav.bio/conventions).
          examples:
            - eyJyIjoicHJvZ3JhbXMiLCJzIjoiY29tcGFueSJ9
        total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total
          description: Rows matching the filters. Null for relevance-ranked `q` results.
          examples:
            - 1284
      type: object
      required:
        - data
      title: DealListResponse
    ErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
          description: Error detail. Present only on 4xx/5xx responses.
      required:
        - error
      title: ErrorEnvelope
      type: object
    Deal:
      properties:
        deal_id:
          type: string
          format: uuid
          title: Deal Id
          description: Stable Pav deal identifier.
          examples:
            - ec0bcf74-fdc0-4ffa-ad04-fe25ed8d6210
        deal_name:
          type: string
          title: Deal Name
          description: Deal headline.
          examples:
            - Merck KGaA acquisition of Bio-Techne Corporation
        deal_type:
          type: string
          enum:
            - acquisition
            - merger
            - asset_purchase
            - licensing
            - collaboration
            - option
            - joint_venture
            - distribution
            - other
          title: Deal Type
          description: Deal classification.
          examples:
            - acquisition
        latest_event_type:
          type: string
          enum:
            - proposed
            - announced
            - completed
            - amended
            - terminated
            - update
          title: Latest Event Type
          description: >-
            Current state: `proposed`, `announced`, `amended`, `completed` or
            `terminated`. Never moves backwards.
          examples:
            - completed
        latest_event_name:
          type: string
          title: Latest Event Name
          description: Headline of the event that set the current state.
        latest_event_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Latest Event At
          description: When the current state took effect (UTC), when stated.
        activity_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Activity Date
          description: >-
            Latest activity: the later of `latest_event_at` and
            `latest_update_at`, else the latest source's publish date. Default
            sort key.
        announced_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Announced At
          description: Announcement date (UTC).
        latest_update_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Latest Update At
          description: Most recent update mention (UTC).
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
          description: Completion date (UTC).
        summary:
          type: string
          title: Summary
          description: One-paragraph deal summary.
        companies:
          items:
            $ref: '#/components/schemas/DealCompany'
          type: array
          title: Companies
          description: Parties linked to Pav companies.
        total_value:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: >-
            Headline (total) deal value as the announcement states it, updated
            when an acquisition price is amended. Never a per-share price.
        total_potential_value:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: >-
            `total_value` when stated, else upfront plus milestones in one
            currency.
        upfront:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Upfront consideration.
        development_milestones:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Development milestone economics.
        regulatory_milestones:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Regulatory milestone economics.
        commercial_milestones:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Commercial / sales milestone economics.
        source_document_count:
          type: integer
          title: Source Document Count
          description: Distinct source documents behind the deal.
        event_count:
          type: integer
          title: Event Count
          description: Lifecycle events recorded for the deal.
        assets:
          items:
            $ref: '#/components/schemas/DealAsset'
          type: array
          title: Assets
          description: Drugs the deal covers. Empty when it names no specific drug.
        targets:
          items:
            $ref: '#/components/schemas/DealTarget'
          type: array
          title: Targets
          description: Molecular targets of the deal's drugs, as ontology terms.
        modalities:
          items:
            type: string
          type: array
          title: Modalities
          description: Modalities of the deal's drugs, in Pav's modality vocabulary.
          examples:
            - - antibody
        therapeutic_areas:
          items:
            type: string
          type: array
          title: Therapeutic Areas
          description: >-
            Therapeutic areas of the diseases the deal's drugs are developed
            for, as area slugs (for example `oncology`, `immunology`,
            `endocrine_metabolic`).
          examples:
            - - immunology
              - gastroenterology
      type: object
      required:
        - deal_id
        - deal_name
        - deal_type
        - latest_event_type
        - latest_event_name
        - summary
        - source_document_count
        - event_count
      title: Deal
    ErrorBody:
      properties:
        code:
          description: >-
            Stable, machine-readable error code (e.g. `unauthorized`,
            `not_found`, `validation_error`, `error`).
          examples:
            - not_found
          title: Code
          type: string
        message:
          description: Human-readable explanation of the error.
          examples:
            - program 999999 not found
          title: Message
          type: string
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Correlation id echoed in the `X-Request-ID` response header. Quote
            it when contacting Pav support about a failed request.
          examples:
            - 3f2b9c1d8a7e4f6b9c0d1e2f3a4b5c6d
          title: Request Id
      required:
        - code
        - message
      title: ErrorBody
      type: object
    DealCompany:
      properties:
        company_id:
          type: integer
          title: Company Id
          description: Durable Pav company identifier.
          examples:
            - 239
        short_name:
          type: string
          title: Short Name
          description: Company slug.
          examples:
            - merck_kgaa
        name:
          type: string
          title: Name
          description: Company display name.
          examples:
            - Merck KGaA
        roles:
          items:
            type: string
          type: array
          title: Roles
          description: >-
            The company's roles: acquirer, target, seller, licensor, licensee,
            collaborator, investor, issuer, other.
          examples:
            - - acquirer
      type: object
      required:
        - company_id
        - short_name
        - name
      title: DealCompany
    DealValue:
      properties:
        raw_text:
          type: string
          title: Raw Text
          description: The term as the source states it.
          examples:
            - total enterprise value of approximately US$11.3 billion
        amount:
          anyOf:
            - type: number
            - type: 'null'
          title: Amount
          description: >-
            Monetary amount in base currency units. Null for percentages or
            unstated values.
          examples:
            - 11300000000
        currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency
          description: ISO 4217 code for `amount`.
          examples:
            - USD
        percentage:
          anyOf:
            - type: number
            - type: 'null'
          title: Percentage
          description: Percentage value (royalties, equity).
          examples:
            - null
        not_disclosed:
          type: boolean
          title: Not Disclosed
          description: True when the source explicitly withholds this term.
          default: false
        evidence:
          anyOf:
            - type: string
            - type: 'null'
          title: Evidence
          description: Source sentence supporting the value.
      type: object
      required:
        - raw_text
      title: DealValue
    DealAsset:
      properties:
        drug_id:
          type: integer
          title: Drug Id
          description: >-
            Pav drug id: one drug product across every company that develops it
            (`GET /v1/drugs/{drug_id}`).
          examples:
            - 8880
        name:
          type: string
          title: Name
          description: Drug display name.
          examples:
            - tulisokibart
        modality:
          anyOf:
            - type: string
            - type: 'null'
          title: Modality
          description: The drug's modality, normalized to Pav's modality vocabulary.
          examples:
            - antibody
        program_ids:
          items:
            type: integer
          type: array
          title: Program Ids
          description: >-
            The deal parties' programs of this drug (`GET
            /v1/programs/{program_id}`).
          examples:
            - - 3497
              - 3498
      type: object
      required:
        - drug_id
        - name
      title: DealAsset
    DealTarget:
      properties:
        term_id:
          type: string
          title: Term Id
          description: Ontology term identifier.
          examples:
            - NCIT:C18289
        term_label:
          type: string
          title: Term Label
          description: Human-readable ontology term label.
          examples:
            - Tumor Necrosis Factor Ligand Superfamily Member 15
        gene_symbol:
          anyOf:
            - type: string
            - type: 'null'
          title: Gene Symbol
          description: HGNC symbol; null for a target with no single gene.
          examples:
            - TNFSF15
      type: object
      required:
        - term_id
        - term_label
      title: DealTarget
  securitySchemes:
    EnterpriseApiKey:
      type: http
      description: >-
        Use a personal or organization Pav API key from Pav developer settings.
        Send it as Authorization: Bearer <api_key>.
      scheme: bearer
      bearerFormat: Pav API key

````