naftiko: 1.0.0-alpha2
info:
  label: USPTO Intellectual Property Research
  description: Unified capability for intellectual property research, combining patent application search, PTAB trial proceedings,
    and trademark status retrieval. Supports IP attorneys, researchers, portfolio managers, and compliance teams.
  tags:
  - Patents
  - Trademarks
  - Intellectual Property
  - Federal Government
  - Open Data
  - Legal Research
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    USPTO_ODP_API_KEY: USPTO_ODP_API_KEY
    USPTO_TSDR_API_KEY: USPTO_TSDR_API_KEY
capability:
  consumes:
  - type: http
    namespace: uspto-odp
    baseUri: https://api.uspto.gov
    description: USPTO Open Data Portal REST API for patent and PTAB data.
    authentication:
      type: apikey
      key: X-API-KEY
      value: '{{USPTO_ODP_API_KEY}}'
      placement: header
    resources:
    - name: patent-applications
      path: /api/v1/patent/applications
      description: Search and retrieve patent application data
      operations:
      - name: search-patent-applications
        method: POST
        description: Search patent applications by JSON payload
        body:
          type: json
          data:
            q: '{{tools.query}}'
            start: '{{tools.start}}'
            rows: '{{tools.rows}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: list-patent-applications
        method: GET
        description: Search patent applications by query parameters
        inputParameters:
        - name: q
          in: query
          type: string
          required: false
          description: Search query string
        - name: start
          in: query
          type: integer
          required: false
          description: Pagination offset
        - name: rows
          in: query
          type: integer
          required: false
          description: Number of results
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: patent-application-detail
      path: /api/v1/patent/applications/{applicationNumberText}
      description: Retrieve specific patent application details
      operations:
      - name: get-patent-application
        method: GET
        description: Get full patent application record
        inputParameters:
        - name: applicationNumberText
          in: path
          type: string
          required: true
          description: Patent application number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-patent-application-documents
        method: GET
        description: Get documents for a patent application
        inputParameters:
        - name: applicationNumberText
          in: path
          type: string
          required: true
          description: Patent application number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: patent-status-codes
      path: /api/v1/patent/status-codes
      description: Patent application status codes
      operations:
      - name: list-patent-status-codes
        method: GET
        description: Get all patent application status codes
        outputRawFormat: json
        outputParameters:
        - name: result
          type: array
          value: $.
    - name: ptab-proceedings
      path: /api/v1/patent/trials/proceedings
      description: PTAB trial proceedings
      operations:
      - name: search-ptab-proceedings
        method: GET
        description: Search PTAB trial proceedings
        inputParameters:
        - name: q
          in: query
          type: string
          required: false
          description: Search query
        - name: start
          in: query
          type: integer
          required: false
          description: Pagination offset
        - name: rows
          in: query
          type: integer
          required: false
          description: Number of results
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-ptab-proceeding
        method: GET
        description: Get PTAB trial proceeding by trial number
        inputParameters:
        - name: trialNumber
          in: path
          type: string
          required: true
          description: PTAB trial number (e.g., IPR2023-00001)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: ptab-decisions
      path: /api/v1/patent/trials/decisions
      description: PTAB trial decisions
      operations:
      - name: search-ptab-decisions
        method: GET
        description: Search PTAB trial decisions
        inputParameters:
        - name: q
          in: query
          type: string
          required: false
          description: Search query
        - name: start
          in: query
          type: integer
          required: false
          description: Pagination offset
        - name: rows
          in: query
          type: integer
          required: false
          description: Number of results
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: bulk-datasets
      path: /api/v1/datasets/products
      description: Bulk dataset products
      operations:
      - name: search-dataset-products
        method: GET
        description: Search available bulk datasets
        inputParameters:
        - name: q
          in: query
          type: string
          required: false
          description: Search query
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: uspto-tsdr
    baseUri: https://tsdrapi.uspto.gov
    description: USPTO TSDR REST API for trademark case status and documents.
    authentication:
      type: apikey
      key: USPTO-API-KEY
      value: '{{USPTO_TSDR_API_KEY}}'
      placement: header
    resources:
    - name: case-status
      path: /ts/cd/caseMultiStatus/{type}
      description: Retrieve status for multiple trademark cases
      operations:
      - name: get-trademark-case-status
        method: GET
        description: Get status for one or more trademark cases by serial or registration number
        inputParameters:
        - name: type
          in: path
          type: string
          required: true
          description: Response format (json or xml)
        - name: sn
          in: query
          type: string
          required: false
          description: Serial numbers (comma-separated)
        - name: rn
          in: query
          type: string
          required: false
          description: Registration numbers (comma-separated)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: case-documents
      path: /ts/cd/casedocs/{caseid}
      description: Trademark case document access
      operations:
      - name: get-case-document-list
        method: GET
        description: Get list of documents for a trademark case
        inputParameters:
        - name: caseid
          in: path
          type: string
          required: true
          description: Trademark serial or registration number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: ip-research-api
    description: Unified REST API for USPTO intellectual property research.
    resources:
    - path: /v1/patents
      name: patents
      description: Patent application search and retrieval
      operations:
      - method: GET
        name: search-patents
        description: Search patent applications by query and filters
        call: uspto-odp.list-patent-applications
        with:
          q: rest.q
          start: rest.start
          rows: rest.rows
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/patents/{applicationNumberText}
      name: patent-detail
      description: Patent application detail
      operations:
      - method: GET
        name: get-patent
        description: Get full patent application record
        call: uspto-odp.get-patent-application
        with:
          applicationNumberText: rest.applicationNumberText
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/patents/{applicationNumberText}/documents
      name: patent-documents
      description: Patent application documents
      operations:
      - method: GET
        name: list-patent-documents
        description: List documents for a patent application
        call: uspto-odp.get-patent-application-documents
        with:
          applicationNumberText: rest.applicationNumberText
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ptab/proceedings
      name: ptab-proceedings
      description: PTAB inter partes review and post-grant review proceedings
      operations:
      - method: GET
        name: search-ptab-proceedings
        description: Search PTAB trial proceedings
        call: uspto-odp.search-ptab-proceedings
        with:
          q: rest.q
          start: rest.start
          rows: rest.rows
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ptab/proceedings/{trialNumber}
      name: ptab-proceeding
      description: PTAB proceeding detail
      operations:
      - method: GET
        name: get-ptab-proceeding
        description: Get PTAB proceeding by trial number
        call: uspto-odp.get-ptab-proceeding
        with:
          trialNumber: rest.trialNumber
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/ptab/decisions
      name: ptab-decisions
      description: PTAB trial final written decisions
      operations:
      - method: GET
        name: search-ptab-decisions
        description: Search PTAB trial decisions
        call: uspto-odp.search-ptab-decisions
        with:
          q: rest.q
          start: rest.start
          rows: rest.rows
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/trademarks/{caseId}/status
      name: trademark-status
      description: Trademark case status
      operations:
      - method: GET
        name: get-trademark-status
        description: Get trademark case status by serial or registration number
        call: uspto-tsdr.get-trademark-case-status
        with:
          type: json
          sn: rest.caseId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/trademarks/{caseId}/documents
      name: trademark-documents
      description: Trademark case documents
      operations:
      - method: GET
        name: list-trademark-documents
        description: List documents for a trademark case
        call: uspto-tsdr.get-case-document-list
        with:
          caseid: rest.caseId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/datasets
      name: datasets
      description: Bulk data products
      operations:
      - method: GET
        name: list-datasets
        description: Browse available USPTO bulk data products
        call: uspto-odp.search-dataset-products
        with:
          q: rest.q
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: ip-research-mcp
    transport: http
    description: MCP server for AI-assisted USPTO intellectual property research.
    tools:
    - name: search-patent-applications
      description: Search USPTO patent applications by keyword, inventor, assignee, or classification
      hints:
        readOnly: true
        openWorld: true
      call: uspto-odp.list-patent-applications
      with:
        q: tools.q
        start: tools.start
        rows: tools.rows
      outputParameters:
      - type: object
        mapping: $.
    - name: get-patent-application
      description: Get complete details for a specific patent application including inventors, assignees, and status
      hints:
        readOnly: true
        openWorld: false
      call: uspto-odp.get-patent-application
      with:
        applicationNumberText: tools.applicationNumberText
      outputParameters:
      - type: object
        mapping: $.
    - name: get-patent-documents
      description: List all office actions, responses, and other documents filed in a patent application
      hints:
        readOnly: true
        openWorld: false
      call: uspto-odp.get-patent-application-documents
      with:
        applicationNumberText: tools.applicationNumberText
      outputParameters:
      - type: object
        mapping: $.
    - name: search-ptab-proceedings
      description: Search PTAB inter partes review (IPR), post-grant review (PGR), and covered business method (CBM) proceedings
      hints:
        readOnly: true
        openWorld: true
      call: uspto-odp.search-ptab-proceedings
      with:
        q: tools.q
        start: tools.start
        rows: tools.rows
      outputParameters:
      - type: object
        mapping: $.
    - name: get-ptab-proceeding
      description: Get full details of a PTAB trial including petitioner, respondent, and claim dispositions
      hints:
        readOnly: true
        openWorld: false
      call: uspto-odp.get-ptab-proceeding
      with:
        trialNumber: tools.trialNumber
      outputParameters:
      - type: object
        mapping: $.
    - name: search-ptab-decisions
      description: Search PTAB final written decisions and institution decisions
      hints:
        readOnly: true
        openWorld: true
      call: uspto-odp.search-ptab-decisions
      with:
        q: tools.q
        start: tools.start
        rows: tools.rows
      outputParameters:
      - type: object
        mapping: $.
    - name: get-trademark-status
      description: Get the current prosecution status and owner information for a trademark application or registration
      hints:
        readOnly: true
        openWorld: false
      call: uspto-tsdr.get-trademark-case-status
      with:
        type: json
        sn: tools.serialNumber
      outputParameters:
      - type: object
        mapping: $.
    - name: list-trademark-documents
      description: List all documents filed in a trademark case including office actions and responses
      hints:
        readOnly: true
        openWorld: false
      call: uspto-tsdr.get-case-document-list
      with:
        caseid: tools.caseId
      outputParameters:
      - type: object
        mapping: $.
    - name: list-patent-status-codes
      description: Get the full list of USPTO patent application status codes and their meanings
      hints:
        readOnly: true
        openWorld: false
      call: uspto-odp.list-patent-status-codes
      outputParameters:
      - type: array
        mapping: $.
    - name: browse-bulk-datasets
      description: Browse available USPTO bulk data products for economic research and analysis
      hints:
        readOnly: true
        openWorld: true
      call: uspto-odp.search-dataset-products
      with:
        q: tools.q
      outputParameters:
      - type: object
        mapping: $.