> ## 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 patent families

> US patent families. `q` is a patent, publication or application number, or part of a title, owner or FDA-listed drug. `from`/`to` filter on `earliest_priority_date`. `view=full` adds up to 30 members.



## OpenAPI

````yaml /openapi.json get /v1/patents
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/patents:
    get:
      tags:
        - patents
      summary: List patent families
      description: >-
        US patent families. `q` is a patent, publication or application number,
        or part of a title, owner or FDA-listed drug. `from`/`to` filter on
        `earliest_priority_date`. `view=full` adds up to 30 members.
      operationId: list_patents
      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: cpc
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 16
              - type: 'null'
            description: CPC prefix on any member (`A61K38/26`).
            examples:
              - A61K
            title: Cpc
          description: CPC prefix on any member (`A61K38/26`).
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - live
                  - lapsed
                type: string
              - type: 'null'
            description: '`live` (a member pending or in force) or `lapsed`.'
            title: Status
          description: '`live` (a member pending or in force) or `lapsed`.'
        - name: granted
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            description: Whether at least one member is granted.
            title: Granted
          description: Whether at least one member is granted.
        - 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 `latest_status_date`, `earliest_priority_date`,
              `member_count`; prefix `-` to descend. Default
              `-latest_status_date`.
            title: Sort
          description: >-
            One of `latest_status_date`, `earliest_priority_date`,
            `member_count`; prefix `-` to descend. Default
            `-latest_status_date`.
        - name: view
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/View'
            description: '`full` (default) or `slim` for light rows.'
            examples:
              - slim
            default: full
          description: '`full` (default) or `slim` for light rows.'
        - 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/PatentFamilyListResponse'
        '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:
    View:
      type: string
      enum:
        - full
        - slim
      title: View
    PatentFamilyListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/PatentFamily'
          type: array
          title: Data
          description: Page of patent families.
        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: PatentFamilyListResponse
    ErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
          description: Error detail. Present only on 4xx/5xx responses.
      required:
        - error
      title: ErrorEnvelope
      type: object
    PatentFamily:
      properties:
        family_id:
          type: string
          title: Family Id
          description: Pav patent family identifier.
          examples:
            - '62662313'
        representative_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Representative Title
          description: Title of the family's representative member.
          examples:
            - >-
              GLUCAGON LIKE PEPTIDE 1 (GLP-1) FUSION PEPTIDE ... CONJUGATES AND
              USES THEREOF
        member_count:
          type: integer
          title: Member Count
          description: Applications in the family.
          examples:
            - 2
        granted_count:
          type: integer
          title: Granted Count
          description: Granted members.
          examples:
            - 1
        pending_count:
          type: integer
          title: Pending Count
          description: Pending members.
          examples:
            - 0
        earliest_filing_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Earliest Filing Date
          description: Earliest member filing.
        earliest_priority_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Earliest Priority Date
          description: Earliest priority date.
        latest_grant_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Latest Grant Date
          description: Most recent grant.
        latest_status_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Latest Status Date
          description: Most recent status change on any member. Default sort key.
        has_live_member:
          type: boolean
          title: Has Live Member
          description: True when any member is pending or in force.
        owner_names:
          items:
            type: string
          type: array
          title: Owner Names
          description: Recorded owners of the live members. Empty for a lapsed family.
        owner_is_split:
          type: boolean
          title: Owner Is Split
          description: True when live members have different owners.
        companies:
          items:
            $ref: '#/components/schemas/PatentCompany'
          type: array
          title: Companies
          description: >-
            Owners linked to Pav companies. An empty list does not mean no
            company owns it.
        drugs:
          items:
            $ref: '#/components/schemas/PatentDrug'
          type: array
          title: Drugs
          description: >-
            FDA-approved drugs whose Orange Book listing names one of the
            family's patents.
        members:
          anyOf:
            - items:
                $ref: '#/components/schemas/PatentFamilyMember'
              type: array
            - type: 'null'
          title: Members
          description: >-
            Member applications, newest filed first. Present with
            `include_members=true`.
      type: object
      required:
        - family_id
        - member_count
        - granted_count
        - pending_count
        - has_live_member
        - owner_is_split
      title: PatentFamily
    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
    PatentCompany:
      properties:
        company_id:
          type: integer
          title: Company Id
          description: Durable Pav company identifier.
          examples:
            - 137
        short_name:
          type: string
          title: Short Name
          description: Company slug.
          examples:
            - johnson_and_johnson
        name:
          type: string
          title: Name
          description: Company display name.
          examples:
            - Johnson & Johnson
      type: object
      required:
        - company_id
        - short_name
        - name
      title: PatentCompany
    PatentDrug:
      properties:
        trade_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Trade Name
          description: FDA-approved product trade name.
          examples:
            - MOUNJARO
        ingredient:
          anyOf:
            - type: string
            - type: 'null'
          title: Ingredient
          description: Active ingredient(s) as FDA lists them.
          examples:
            - TIRZEPATIDE
        application_key:
          type: string
          title: Application Key
          description: >-
            FDA application: `N:` (NDA) or `A:` (ANDA) plus the number. Pass it
            to `GET /v1/fda?application_key=` for the product, patent and
            exclusivity records.
          examples:
            - N:215866
        patent_numbers:
          items:
            type: string
          type: array
          title: Patent Numbers
          description: Family members' patents listed in the Orange Book for this product.
          examples:
            - - '9474780'
        latest_patent_expiry:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Latest Patent Expiry
          description: >-
            Latest Orange Book expiry among those patents, including pediatric
            exclusivity.
      type: object
      required:
        - application_key
        - patent_numbers
      title: PatentDrug
    PatentFamilyMember:
      properties:
        application_number:
          type: string
          title: Application Number
          description: USPTO application number.
          examples:
            - '17076912'
        patent_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Patent Number
          description: Granted patent number; null until granted.
        publication_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Publication Number
          description: Pre-grant publication number.
        role:
          type: string
          title: Role
          description: Member's place in the family (root, continuation, ...).
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Application title.
        application_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Application Type
          description: USPTO application type.
        filing_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Filing Date
          description: Filing date.
        grant_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Grant Date
          description: Grant date.
        status_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Status Description
          description: Current USPTO status.
        status_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Status Date
          description: Date of the current status.
        is_dead:
          type: boolean
          title: Is Dead
          description: True when the application is abandoned or expired.
        cpc_codes:
          items:
            type: string
          type: array
          title: Cpc Codes
          description: CPC classification codes.
      type: object
      required:
        - application_number
        - role
        - is_dead
      title: PatentFamilyMember
  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

````