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

# Get a deal by id

> One deal with its full terms (headline value, upfront, equity, milestones, royalties, territories, rights), its lifecycle events, and the source documents behind it. Returns `404 not_found` for an unknown id.



## OpenAPI

````yaml /openapi.json get /v1/deals/{deal_id}
openapi: 3.1.0
info:
  title: Pav Enterprise API
  description: >-
    Read-only `/v1` API over Pav's biopharma dataset: drug programs, companies,
    clinical trials, deals, patent families, FDA records, a change feed, and
    dataset stats.


    Authenticate every request with a Pav API key as a bearer token:
    `Authorization: Bearer <api_key>`. Mint a key in [Pav developer
    settings](https://app.pav.bio/settings/developer).


    All endpoints are `GET` and return JSON. List endpoints return a `{ data,
    pagination }` envelope. Pass `q=` to run relevance-ranked search that
    matches meaning as well as exact words; omit it for a filtered, paginated
    listing. Errors return `{ error: { code, message, request_id } }`.
  version: 1.2.0
servers:
  - url: https://api.pav.bio
    description: Production
  - url: /
    description: This server
security: []
tags:
  - name: programs
    description: >-
      Search and filter drug pipeline assets by company, indication, target,
      modality, phase, or free text. Includes get-by-id, similar-programs, and
      facet autocomplete.
  - name: companies
    description: >-
      Tracked biopharma companies and their pipeline ownership. List a company's
      programs and change history.
  - name: trials
    description: >-
      Search clinical trials — ClinicalTrials.gov records plus Pav
      program/company links. Relevance-ranked search when `q=` is set; filtered
      browse otherwise.
  - name: deals
    description: >-
      Biopharma deals (M&A, licensing, collaborations, options, joint ventures)
      from SEC filings and press releases, with lifecycle state, headline
      economics, and source documents.
  - name: patents
    description: >-
      US patent families from USPTO with owners linked to Pav companies, member
      applications, ownership history, and statutory term.
  - name: fda
    description: >-
      FDA records with applicants linked to Pav companies: Orange Book products,
      patents and exclusivities, Purple Book biologics, orphan designations,
      warning letters, and recalls.
  - name: changes
    description: >-
      Detected pipeline movement events per company — added and removed assets
      and phase changes — with before/after phase and detection time.
  - name: stats
    description: High-level dataset counts and facet coverage.
paths:
  /v1/deals/{deal_id}:
    get:
      tags:
        - deals
      summary: Get a deal by id
      description: >-
        One deal with its full terms (headline value, upfront, equity,
        milestones, royalties, territories, rights), its lifecycle events, and
        the source documents behind it. Returns `404 not_found` for an unknown
        id.
      operationId: get_deal
      parameters:
        - name: deal_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Stable Pav deal id.
            examples:
              - ec0bcf74-fdc0-4ffa-ad04-fe25ed8d6210
            title: Deal Id
          description: Stable Pav deal id.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DealDetail'
        '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'
        '422':
          description: Invalid parameter (`validation_error`).
          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:
    DealDetail:
      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 lifecycle state. `update` means the latest mention changed
            no lifecycle state.
          examples:
            - completed
        latest_event_name:
          type: string
          title: Latest Event Name
          description: Headline of the latest lifecycle event.
        latest_event_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Latest Event At
          description: Date of the latest lifecycle event, when stated (UTC).
        activity_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Activity Date
          description: >-
            Latest activity: the latest event's date, else its 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, when stated.
        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.
        terms:
          $ref: '#/components/schemas/DealTerms'
          description: Economics and rights across all source documents.
        events:
          items:
            $ref: '#/components/schemas/DealEvent'
          type: array
          title: Events
          description: Lifecycle events, oldest first.
        source_documents:
          items:
            $ref: '#/components/schemas/DealSourceDocument'
          type: array
          title: Source Documents
          description: Source documents behind the deal, oldest first.
      type: object
      required:
        - deal_id
        - deal_name
        - deal_type
        - latest_event_type
        - latest_event_name
        - summary
        - source_document_count
        - event_count
        - terms
      title: DealDetail
    ErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
          description: Error detail. Present only on 4xx/5xx responses.
      required:
        - error
      title: ErrorEnvelope
      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: >-
            Roles the source documents give this party (e.g. acquirer,
            licensor).
          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
    DealTerms:
      properties:
        headline_value:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Total deal value.
        upfront:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Upfront consideration.
        equity:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Equity stake or investment.
        milestones:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Milestone economics.
        royalties:
          anyOf:
            - $ref: '#/components/schemas/DealValue'
            - type: 'null'
          description: Royalty economics.
        territories:
          items:
            type: string
          type: array
          title: Territories
          description: Territories covered.
        rights_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Rights Summary
          description: Rights granted, in brief.
      type: object
      title: DealTerms
    DealEvent:
      properties:
        event_type:
          type: string
          enum:
            - proposed
            - announced
            - completed
            - amended
            - terminated
            - update
          title: Event Type
          description: Lifecycle event type.
        event_name:
          type: string
          title: Event Name
          description: Event headline.
        effective_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Effective At
          description: >-
            Event date (UTC day): the source's stated date, else its publication
            date.
        source_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Url
          description: URL of the document that reported this event.
      type: object
      required:
        - event_type
        - event_name
      title: DealEvent
    DealSourceDocument:
      properties:
        source_vendor:
          type: string
          title: Source Vendor
          description: Publisher of the source document.
          examples:
            - sec
        source_kind:
          type: string
          title: Source Kind
          description: Document kind.
          examples:
            - sec_filing
        source_id:
          type: string
          title: Source Id
          description: Source-native document id.
          examples:
            - 0001999371-26-013429/ex99-1.htm
        source_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Url
          description: Public URL of the document.
        published_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Published At
          description: Publication time (UTC).
        observed_at:
          type: string
          format: date-time
          title: Observed At
          description: When Pav first saw the document (UTC).
      type: object
      required:
        - source_vendor
        - source_kind
        - source_id
        - observed_at
      title: DealSourceDocument
    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
  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

````