openapi: 3.0.1
info:
  title: USPTO Open Data Portal Bulk Datasets Case Documents 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: Case Documents
  description: Retrieve trademark case documents and images
paths:
  /ts/cd/casedocs/{caseid}/info:
    get:
      tags:
      - Case Documents
      operationId: getCaseDocumentsInfo
      summary: Get Trademark Case Document List
      description: Retrieve the list of documents associated with a trademark case.
      parameters:
      - name: caseid
        in: path
        required: true
        description: Trademark serial or registration number
        schema:
          type: string
      responses:
        '200':
          description: Case document list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseDocumentListResponse'
        '404':
          description: Not Found
  /ts/cd/casedocs/{caseid}/bundle:
    get:
      tags:
      - Case Documents
      operationId: getCaseDocumentsBundle
      summary: Get Trademark Case Documents Bundle
      description: Download all documents for a trademark case as a bundle.
      parameters:
      - name: caseid
        in: path
        required: true
        description: Trademark serial or registration number
        schema:
          type: string
      responses:
        '200':
          description: Bundle of case documents
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '404':
          description: Not Found
  /ts/cd/casedoc/{caseid}/{docid}/info:
    get:
      tags:
      - Case Documents
      operationId: getCaseDocumentInfo
      summary: Get Trademark Case Document Metadata
      description: Retrieve metadata for a specific trademark case document.
      parameters:
      - name: caseid
        in: path
        required: true
        schema:
          type: string
      - name: docid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Document metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseDocumentInfo'
        '404':
          description: Not Found
  /ts/cd/casedoc/{caseid}/{docid}/content.pdf:
    get:
      tags:
      - Case Documents
      operationId: getCaseDocumentPdf
      summary: Get Trademark Case Document as PDF
      parameters:
      - name: caseid
        in: path
        required: true
        schema:
          type: string
      - name: docid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Document as PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          description: Not Found
  /ts/cd/casedoc/{caseid}/{docid}/{pageid}/media:
    get:
      tags:
      - Case Documents
      operationId: getCaseDocumentPageMedia
      summary: Get Trademark Case Document Page Image
      parameters:
      - name: caseid
        in: path
        required: true
        schema:
          type: string
      - name: docid
        in: path
        required: true
        schema:
          type: string
      - name: pageid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Document page image
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        '404':
          description: Not Found
components:
  schemas:
    CaseDocumentInfo:
      type: object
      description: Metadata for a trademark case document
      properties:
        documentId:
          type: string
        documentDescription:
          type: string
        mailDate:
          type: string
          format: date
        numberOfPages:
          type: integer
        documentUrl:
          type: string
          format: uri
    CaseDocumentListResponse:
      type: object
      description: List of documents for a trademark case
      properties:
        serialNumber:
          type: string
        documentList:
          type: array
          items:
            $ref: '#/components/schemas/CaseDocumentInfo'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY