openapi: 3.0.1
info:
  title: USPTO Open Data Portal API
  description: >-
    The USPTO Open Data Portal (ODP) API allows public users to discover,
    search, and extract USPTO patent, trademark, PTAB trial, petition decision,
    and bulk dataset data at no cost. An ODP API key is required, passed via
    the X-API-KEY request header.
  version: 1.0.0
  contact:
    name: USPTO
    email: data@uspto.gov
    url: https://data.uspto.gov/apis/getting-started
  x-source-url: https://data.uspto.gov/swagger/swagger.yaml
servers:
  - url: https://api.uspto.gov
security:
  - ApiKeyAuth: []
tags:
  - name: Patent Search
    description: Search and retrieve patent application data
  - name: Bulk Datasets
    description: Access bulk raw public data from the Chief Economist office
  - name: Petition Decisions
    description: Search and retrieve petition decision records
  - name: PTAB Trials Proceedings
    description: All public PTAB Trial proceedings
  - name: PTAB Trials Decisions
    description: All public decisions filed in PTAB Trials
  - name: PTAB Trials Documents
    description: All public documents filed in PTAB Trials
  - name: PTAB Appeals
    description: All public decisions filed in PTAB Appeals
  - name: PTAB Interferences
    description: All public decisions filed in PTAB Interferences
paths:
  /api/v1/patent/applications/search:
    post:
      tags:
        - Patent Search
      operationId: searchPatentApplicationsPost
      summary: Search Patent Applications by JSON Payload
      description: >-
        Search patent applications by supplying a JSON request payload with
        optional query fields, date filters, and pagination options.
      requestBody:
        description: Patent search request payload. All fields are optional.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatentSearchRequest'
      responses:
        '200':
          description: Successful patent search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatentDataResponse'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
    get:
      tags:
        - Patent Search
      operationId: searchPatentApplicationsGet
      summary: Search Patent Applications by Query Parameters
      description: >-
        Search patent applications using query parameters. When no parameters
        are supplied, the top 25 applications are returned.
      parameters:
        - name: q
          in: query
          description: >-
            Search query string supporting boolean operators (AND, OR, NOT),
            wildcards (*), and exact phrases ("").
          schema:
            type: string
        - name: dateRangeData.startDate
          in: query
          description: Start date for date range filter (YYYY-MM-DD)
          schema:
            type: string
            format: date
        - name: dateRangeData.endDate
          in: query
          description: End date for date range filter (YYYY-MM-DD)
          schema:
            type: string
            format: date
        - name: start
          in: query
          description: Pagination start offset
          schema:
            type: integer
            default: 0
        - name: rows
          in: query
          description: Number of rows to return (max 25)
          schema:
            type: integer
            default: 25
            maximum: 25
      responses:
        '200':
          description: Successful patent search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatentDataResponse'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  /api/v1/patent/applications/search/download:
    post:
      tags:
        - Patent Search
      operationId: downloadPatentApplicationsSearch
      summary: Download Patent Application Search Results
      description: Download a bulk export of patent application search results.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatentSearchRequest'
      responses:
        '200':
          description: Download initiated
        '400':
          description: Bad Request
        '403':
          description: Forbidden
  /api/v1/patent/applications/{applicationNumberText}:
    get:
      tags:
        - Patent Search
      operationId: getPatentApplication
      summary: Get Patent Application by Application Number
      description: Retrieve full details for a specific patent application.
      parameters:
        - name: applicationNumberText
          in: path
          required: true
          description: Patent application number (e.g., 14412875)
          schema:
            type: string
      responses:
        '200':
          description: Patent application details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatentApplicationData'
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /api/v1/patent/applications/{applicationNumberText}/meta-data:
    get:
      tags:
        - Patent Search
      operationId: getPatentApplicationMetaData
      summary: Get Patent Application Metadata
      description: Retrieve metadata for a specific patent application.
      parameters:
        - name: applicationNumberText
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Patent application metadata
          content:
            application/json:
              schema:
                type: object
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /api/v1/patent/applications/{applicationNumberText}/adjustment:
    get:
      tags:
        - Patent Search
      operationId: getPatentApplicationAdjustment
      summary: Get Patent Application Patent Term Adjustment
      parameters:
        - name: applicationNumberText
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Patent term adjustment information
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
  /api/v1/patent/applications/{applicationNumberText}/assignment:
    get:
      tags:
        - Patent Search
      operationId: getPatentApplicationAssignment
      summary: Get Patent Application Assignment Data
      parameters:
        - name: applicationNumberText
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Assignment data
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
  /api/v1/patent/applications/{applicationNumberText}/attorney:
    get:
      tags:
        - Patent Search
      operationId: getPatentApplicationAttorney
      summary: Get Patent Application Attorney Information
      parameters:
        - name: applicationNumberText
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Attorney information
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
  /api/v1/patent/applications/{applicationNumberText}/continuity:
    get:
      tags:
        - Patent Search
      operationId: getPatentApplicationContinuity
      summary: Get Patent Application Continuity Data
      parameters:
        - name: applicationNumberText
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Continuity data
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
  /api/v1/patent/applications/{applicationNumberText}/foreign-priority:
    get:
      tags:
        - Patent Search
      operationId: getPatentApplicationForeignPriority
      summary: Get Patent Application Foreign Priority
      parameters:
        - name: applicationNumberText
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Foreign priority data
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
  /api/v1/patent/applications/{applicationNumberText}/transactions:
    get:
      tags:
        - Patent Search
      operationId: getPatentApplicationTransactions
      summary: Get Patent Application Transaction History
      parameters:
        - name: applicationNumberText
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Transaction history
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
  /api/v1/patent/applications/{applicationNumberText}/documents:
    get:
      tags:
        - Patent Search
      operationId: getPatentApplicationDocuments
      summary: Get Patent Application Documents
      parameters:
        - name: applicationNumberText
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Document list
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
  /api/v1/patent/status-codes:
    get:
      tags:
        - Patent Search
      operationId: getPatentStatusCodes
      summary: Get Patent Application Status Codes
      description: Retrieve the list of all patent application status codes and their descriptions.
      responses:
        '200':
          description: Status codes list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
  /api/v1/datasets/products/search:
    get:
      tags:
        - Bulk Datasets
      operationId: searchDatasetProducts
      summary: Search Bulk Dataset Products
      description: Search available USPTO bulk data products.
      parameters:
        - name: q
          in: query
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
            default: 0
        - name: rows
          in: query
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: Dataset products list
          content:
            application/json:
              schema:
                type: object
        '403':
          description: Forbidden
  /api/v1/datasets/products/{productIdentifier}:
    get:
      tags:
        - Bulk Datasets
      operationId: getDatasetProduct
      summary: Get Bulk Dataset Product by Identifier
      parameters:
        - name: productIdentifier
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Dataset product details
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
  /api/v1/petition/decisions/search:
    post:
      tags:
        - Petition Decisions
      operationId: searchPetitionDecisionsPost
      summary: Search Petition Decisions by JSON Payload
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                q:
                  type: string
                  description: Search query string
                dateRangeData:
                  type: object
                  properties:
                    startDate:
                      type: string
                      format: date
                    endDate:
                      type: string
                      format: date
      responses:
        '200':
          description: Petition decision search results
          content:
            application/json:
              schema:
                type: object
        '403':
          description: Forbidden
    get:
      tags:
        - Petition Decisions
      operationId: searchPetitionDecisionsGet
      summary: Search Petition Decisions by Query Parameters
      parameters:
        - name: q
          in: query
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
            default: 0
        - name: rows
          in: query
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: Petition decision search results
          content:
            application/json:
              schema:
                type: object
        '403':
          description: Forbidden
  /api/v1/petition/decisions/{petitionDecisionRecordIdentifier}:
    get:
      tags:
        - Petition Decisions
      operationId: getPetitionDecision
      summary: Get Petition Decision by Identifier
      parameters:
        - name: petitionDecisionRecordIdentifier
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Petition decision details
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
  /api/v1/patent/trials/proceedings/search:
    post:
      tags:
        - PTAB Trials Proceedings
      operationId: searchPtabProceedingsPost
      summary: Search PTAB Trial Proceedings by JSON Payload
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: PTAB proceedings search results
          content:
            application/json:
              schema:
                type: object
        '403':
          description: Forbidden
    get:
      tags:
        - PTAB Trials Proceedings
      operationId: searchPtabProceedingsGet
      summary: Search PTAB Trial Proceedings by Query Parameters
      parameters:
        - name: q
          in: query
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
            default: 0
        - name: rows
          in: query
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: PTAB proceedings search results
          content:
            application/json:
              schema:
                type: object
  /api/v1/patent/trials/proceedings/{trialNumber}:
    get:
      tags:
        - PTAB Trials Proceedings
      operationId: getPtabProceeding
      summary: Get PTAB Trial Proceeding by Trial Number
      parameters:
        - name: trialNumber
          in: path
          required: true
          description: PTAB trial number (e.g., IPR2020-00001)
          schema:
            type: string
      responses:
        '200':
          description: PTAB proceeding details
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
  /api/v1/patent/trials/decisions/search:
    post:
      tags:
        - PTAB Trials Decisions
      operationId: searchPtabDecisionsPost
      summary: Search PTAB Trial Decisions by JSON Payload
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: PTAB decisions search results
          content:
            application/json:
              schema:
                type: object
    get:
      tags:
        - PTAB Trials Decisions
      operationId: searchPtabDecisionsGet
      summary: Search PTAB Trial Decisions by Query Parameters
      parameters:
        - name: q
          in: query
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
            default: 0
        - name: rows
          in: query
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: PTAB decisions search results
          content:
            application/json:
              schema:
                type: object
  /api/v1/patent/trials/decisions/{documentIdentifier}:
    get:
      tags:
        - PTAB Trials Decisions
      operationId: getPtabDecision
      summary: Get PTAB Trial Decision by Document Identifier
      parameters:
        - name: documentIdentifier
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: PTAB decision details
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
  /api/v1/patent/trials/documents/search:
    post:
      tags:
        - PTAB Trials Documents
      operationId: searchPtabDocumentsPost
      summary: Search PTAB Trial Documents by JSON Payload
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: PTAB documents search results
          content:
            application/json:
              schema:
                type: object
    get:
      tags:
        - PTAB Trials Documents
      operationId: searchPtabDocumentsGet
      summary: Search PTAB Trial Documents by Query Parameters
      parameters:
        - name: q
          in: query
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
            default: 0
        - name: rows
          in: query
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: PTAB documents search results
          content:
            application/json:
              schema:
                type: object
  /api/v1/patent/trials/documents/{documentIdentifier}:
    get:
      tags:
        - PTAB Trials Documents
      operationId: getPtabDocument
      summary: Get PTAB Trial Document by Identifier
      parameters:
        - name: documentIdentifier
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: PTAB document details
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
  /api/v1/patent/appeals/decisions/search:
    post:
      tags:
        - PTAB Appeals
      operationId: searchPtabAppealDecisionsPost
      summary: Search PTAB Appeal Decisions by JSON Payload
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: PTAB appeal decisions search results
          content:
            application/json:
              schema:
                type: object
    get:
      tags:
        - PTAB Appeals
      operationId: searchPtabAppealDecisionsGet
      summary: Search PTAB Appeal Decisions by Query Parameters
      parameters:
        - name: q
          in: query
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
            default: 0
        - name: rows
          in: query
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: PTAB appeal decisions search results
          content:
            application/json:
              schema:
                type: object
  /api/v1/patent/appeals/decisions/{documentIdentifier}:
    get:
      tags:
        - PTAB Appeals
      operationId: getPtabAppealDecision
      summary: Get PTAB Appeal Decision by Document Identifier
      parameters:
        - name: documentIdentifier
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: PTAB appeal decision details
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
  /api/v1/patent/interferences/decisions/search:
    post:
      tags:
        - PTAB Interferences
      operationId: searchPtabInterferenceDecisionsPost
      summary: Search PTAB Interference Decisions by JSON Payload
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: PTAB interference decisions search results
          content:
            application/json:
              schema:
                type: object
    get:
      tags:
        - PTAB Interferences
      operationId: searchPtabInterferenceDecisionsGet
      summary: Search PTAB Interference Decisions by Query Parameters
      parameters:
        - name: q
          in: query
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
            default: 0
        - name: rows
          in: query
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: PTAB interference decisions search results
          content:
            application/json:
              schema:
                type: object
  /api/v1/patent/interferences/decisions/{documentIdentifier}:
    get:
      tags:
        - PTAB Interferences
      operationId: getPtabInterferenceDecision
      summary: Get PTAB Interference Decision by Document Identifier
      parameters:
        - name: documentIdentifier
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: PTAB interference decision details
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Not Found
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
  schemas:
    PatentSearchRequest:
      type: object
      description: Request body for patent application search
      properties:
        q:
          type: string
          description: Search query string with boolean operator support
        dateRangeData:
          type: object
          properties:
            startDate:
              type: string
              format: date
              description: Start date for filtering (YYYY-MM-DD)
            endDate:
              type: string
              format: date
              description: End date for filtering (YYYY-MM-DD)
            fieldName:
              type: string
              description: Field to apply the date filter to
        start:
          type: integer
          description: Pagination offset
          default: 0
        rows:
          type: integer
          description: Number of results (max 25)
          default: 25
          maximum: 25
        sort:
          type: string
          description: Sort field and direction (e.g., "applicationFilingDate desc")
        fields:
          type: array
          items:
            type: string
          description: Specific fields to return
    PatentDataResponse:
      type: object
      description: Response from patent application search
      properties:
        count:
          type: integer
          description: Total number of matching records
        patents:
          type: array
          items:
            $ref: '#/components/schemas/PatentApplicationData'
        requestIdentifier:
          type: string
          description: Unique request identifier for support
    PatentApplicationData:
      type: object
      description: Patent application record
      properties:
        applicationNumberText:
          type: string
          description: Patent application number
        applicationTypeLabelName:
          type: string
          description: Type of patent application (Utility, Design, Plant, etc.)
        applicationStatusCode:
          type: string
          description: Current status code
        applicationStatusDate:
          type: string
          format: date
          description: Date of current status
        applicationFilingDate:
          type: string
          format: date
          description: Date application was filed
        grantDate:
          type: string
          format: date
          description: Date patent was granted (if granted)
        patentNumber:
          type: string
          description: Issued patent number
        inventionTitle:
          type: string
          description: Title of the invention
        inventors:
          type: array
          items:
            type: object
            properties:
              inventorNameText:
                type: string
              inventorCity:
                type: string
              inventorStateCode:
                type: string
              inventorCountryCode:
                type: string
        applicants:
          type: array
          items:
            type: object
            properties:
              applicantNameText:
                type: string
              applicantCity:
                type: string
              applicantStateCode:
                type: string
              applicantCountryCode:
                type: string
        attorneys:
          type: array
          items:
            type: object
            properties:
              registrationNumber:
                type: string
              fullName:
                type: string
        classifications:
          type: array
          items:
            type: object
            properties:
              classificationSymbolText:
                type: string
              uspcSymbolText:
                type: string