openapi: 3.1.0
info:
  title: USPTO Patent & Trademark Assignments Trademarks API
  description: The United States Patent and Trademark Office (USPTO) provides REST APIs for patent search, PTAB trial proceedings, trademark status lookup, and patent citation data. APIs are hosted at developer.uspto.gov and data.uspto.gov. An ODP API key is required for most endpoints.
  version: '3.0'
  contact:
    name: USPTO Open Data Portal
    url: https://developer.uspto.gov/
  license:
    name: Public Domain (U.S. Government Work)
    url: https://www.usa.gov/government-works
servers:
- url: https://data.uspto.gov/api/v1
  description: USPTO Open Data Portal API v1
- url: https://developer.uspto.gov/ds-api
  description: USPTO Data Set API (legacy)
security:
- ApiKeyHeader: []
tags:
- name: Trademarks
  description: Trademark status and documents
paths:
  /trademark/status/{serialNumber}:
    get:
      operationId: getTrademarkStatus
      summary: Get trademark application status
      description: Returns the current status, prosecution history, and filing information for a trademark application or registration by serial number.
      tags:
      - Trademarks
      parameters:
      - name: serialNumber
        in: path
        required: true
        description: Trademark serial number (8 digits)
        schema:
          type: string
          pattern: ^\d{8}$
        example: '88123456'
      responses:
        '200':
          description: Trademark status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrademarkStatus'
        '404':
          description: Trademark not found
components:
  schemas:
    TrademarkStatus:
      type: object
      properties:
        serialNumber:
          type: string
        registrationNumber:
          type: string
          nullable: true
        markLiteralElements:
          type: string
          description: Text elements of the mark
        status:
          type: string
        statusCode:
          type: string
        statusDate:
          type: string
          format: date
        filingDate:
          type: string
          format: date
        registrationDate:
          type: string
          format: date
          nullable: true
        expirationDate:
          type: string
          format: date
          nullable: true
        applicantName:
          type: string
        goodsAndServices:
          type: string
        internationalClasses:
          type: array
          items:
            type: integer
        prosecutionHistory:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              code:
                type: string
              description:
                type: string
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
      description: USPTO Open Data Portal API key