openapi: 3.1.0
info:
  title: USPTO Trademark Search API
  description: >-
    The USPTO Trademark Search API provides access to United States Patent and
    Trademark Office trademark data via RapidAPI. It enables developers to search
    active trademarks by keyword, check trademark availability, perform serial number
    lookups, search by owner, and retrieve database status information. The API is
    maintained by MartonKodok and updated daily from USPTO data. Supports batch
    processing and pagination for high-volume trademark research.
  version: "1.0"
  contact:
    name: MartonKodok
    email: android482-one@yahoo.com
    x-twitter: martonkodok
  x-rapidapi-collection: https://rapidapi.com/pentium10/api/uspto-trademark
servers:
  - url: https://uspto-trademark.p.rapidapi.com
    description: USPTO Trademark Search API via RapidAPI

security:
  - RapidAPIKey: []

tags:
  - name: Trademark Search
    description: Search trademarks by keyword or phrase
  - name: Trademark Availability
    description: Check if a trademark is available for registration
  - name: Trademark Lookup
    description: Retrieve trademark details by serial number
  - name: Owner Search
    description: Search trademarks by owner name
  - name: Database Status
    description: Database freshness and update information

paths:
  /v1/trademarkSearch/{keyword}/{searchType}:
    get:
      operationId: searchTrademarks
      summary: Search Trademarks by Keyword
      description: >-
        Searches active and inactive trademarks in the USPTO database by keyword.
        Returns matching trademarks with their current status, registration numbers,
        owner details, and goods/services classifications. Supports pagination for
        large result sets.
      tags:
        - Trademark Search
      parameters:
        - name: keyword
          in: path
          required: true
          description: The trademark keyword or phrase to search for
          schema:
            type: string
          example: "apple"
        - name: searchType
          in: path
          required: true
          description: >-
            Type of search to perform. Use 'active' for active trademarks only,
            or 'all' for both active and inactive marks.
          schema:
            type: string
            enum: [active, all]
          example: "active"
      responses:
        '200':
          description: Trademark search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrademarkSearchResponse'
        '400':
          description: Invalid search parameters
        '401':
          description: Invalid or missing RapidAPI key
        '429':
          description: Rate limit exceeded

  /v1/trademarkAvailable/{keyword}:
    get:
      operationId: checkTrademarkAvailability
      summary: Check Trademark Availability
      description: >-
        Checks whether a trademark keyword is available for registration by
        searching for identical or confusingly similar marks in the USPTO database.
        Returns availability status and any conflicting marks found.
      tags:
        - Trademark Availability
      parameters:
        - name: keyword
          in: path
          required: true
          description: The trademark keyword to check for availability
          schema:
            type: string
          example: "novabrand"
      responses:
        '200':
          description: Trademark availability check result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrademarkAvailabilityResponse'
        '400':
          description: Invalid keyword
        '401':
          description: Invalid or missing RapidAPI key

  /v1/trademarkBySerial/{serialNumber}:
    get:
      operationId: getTrademarkBySerialNumber
      summary: Get Trademark by Serial Number
      description: >-
        Retrieves complete trademark information for a specific trademark using
        its USPTO serial number. Returns all filing details, status history,
        owner information, goods/services classifications, and prosecution history.
      tags:
        - Trademark Lookup
      parameters:
        - name: serialNumber
          in: path
          required: true
          description: The USPTO trademark serial number (8 digits)
          schema:
            type: string
            pattern: '^\d{8}$'
          example: "88123456"
      responses:
        '200':
          description: Trademark details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrademarkDetail'
        '404':
          description: Serial number not found

  /v1/trademarkOwner/{owner}:
    get:
      operationId: searchTrademarksByOwner
      summary: Search Trademarks by Owner
      description: >-
        Searches the USPTO trademark database for all trademarks owned by a
        specific individual or organization. Useful for brand portfolio analysis,
        competitive intelligence, and due diligence research.
      tags:
        - Owner Search
      parameters:
        - name: owner
          in: path
          required: true
          description: The trademark owner name (individual or company)
          schema:
            type: string
          example: "Apple Inc."
        - name: page
          in: query
          required: false
          description: Page number for pagination (1-based)
          schema:
            type: integer
            default: 1
            minimum: 1
      responses:
        '200':
          description: Trademarks owned by the specified owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrademarkOwnerResponse'
        '404':
          description: No trademarks found for owner

  /v1/databaseStatus:
    get:
      operationId: getDatabaseStatus
      summary: Get Database Status
      description: >-
        Returns the current status of the USPTO trademark database including
        the last update date, record count, and database health information.
        Use this endpoint to verify data freshness before performing trademark searches.
      tags:
        - Database Status
      responses:
        '200':
          description: Database status information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseStatus'

components:
  securitySchemes:
    RapidAPIKey:
      type: apiKey
      in: header
      name: X-RapidAPI-Key
      description: RapidAPI subscription key

  schemas:
    TrademarkSearchResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of results found
        items:
          type: array
          items:
            $ref: '#/components/schemas/TrademarkSummary'
        page:
          type: integer
          description: Current page number

    TrademarkSummary:
      type: object
      properties:
        serialNumber:
          type: string
          description: USPTO trademark serial number
        registrationNumber:
          type: string
          nullable: true
          description: USPTO registration number (if registered)
        wordMark:
          type: string
          description: The text of the trademark
        status:
          type: string
          description: Current status of the trademark
        statusCode:
          type: string
          description: USPTO status code
        filingDate:
          type: string
          format: date
          description: Date the application was filed
        registrationDate:
          type: string
          format: date
          nullable: true
          description: Date the trademark was registered
        ownerName:
          type: string
          description: Name of the trademark owner
        goodsAndServices:
          type: string
          description: Description of goods and services
        internationalClasses:
          type: array
          items:
            type: integer
          description: International Nice Classification class numbers

    TrademarkDetail:
      allOf:
        - $ref: '#/components/schemas/TrademarkSummary'
        - type: object
          properties:
            description:
              type: string
              description: Full goods and services description
            ownerAddress:
              type: string
              description: Owner mailing address
            ownerCity:
              type: string
            ownerState:
              type: string
            ownerCountry:
              type: string
            ownerPostalCode:
              type: string
            correspondentName:
              type: string
              description: Correspondent attorney name
            correspondentAddress:
              type: string
            markType:
              type: string
              description: Type of mark (STANDARD_CHARACTER, DESIGN, etc.)
            distinctivenessClaim:
              type: string
              nullable: true
            firstUsedDate:
              type: string
              format: date
              nullable: true
            firstUsedInCommerceDate:
              type: string
              format: date
              nullable: true
            prosecutionHistory:
              type: array
              items:
                type: object
                properties:
                  date:
                    type: string
                    format: date
                  code:
                    type: string
                  description:
                    type: string

    TrademarkAvailabilityResponse:
      type: object
      properties:
        keyword:
          type: string
          description: The keyword that was checked
        available:
          type: boolean
          description: Whether the keyword appears to be available for trademark registration
        conflictingMarks:
          type: array
          items:
            $ref: '#/components/schemas/TrademarkSummary'
          description: List of existing marks that may conflict with the keyword

    TrademarkOwnerResponse:
      type: object
      properties:
        owner:
          type: string
          description: The owner name that was searched
        count:
          type: integer
          description: Total number of trademarks found
        items:
          type: array
          items:
            $ref: '#/components/schemas/TrademarkSummary'
        page:
          type: integer

    DatabaseStatus:
      type: object
      properties:
        lastUpdated:
          type: string
          format: date-time
          description: Timestamp of the last database update
        recordCount:
          type: integer
          description: Total number of trademark records in the database
        status:
          type: string
          enum: [ONLINE, MAINTENANCE, DEGRADED]
          description: Current database operational status
        version:
          type: string
          description: Database version identifier