USPTO Open Data Portal API — Patent Search

naftiko: 1.0.0-alpha2
info:
  label: USPTO Open Data Portal API — Patent Search
  description: 'USPTO Open Data Portal API — Patent Search. 13 operations. Lead operation: Search Patent Applications by JSON
    Payload. Self-contained Naftiko capability covering one Us Patent And Trademark Office business surface.'
  tags:
  - Us Patent And Trademark Office
  - Patent Search
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    US_PATENT_AND_TRADEMARK_OFFICE_API_KEY: US_PATENT_AND_TRADEMARK_OFFICE_API_KEY
capability:
  consumes:
  - type: http
    namespace: uspto-open-data-portal-patent-search
    baseUri: https://api.uspto.gov
    description: USPTO Open Data Portal API — Patent Search business capability. Self-contained, no shared references.
    resources:
    - name: api-v1-patent-applications-search
      path: /api/v1/patent/applications/search
      operations:
      - name: searchpatentapplicationspost
        method: POST
        description: Search Patent Applications by JSON Payload
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: searchpatentapplicationsget
        method: GET
        description: Search Patent Applications by Query Parameters
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: q
          in: query
          type: string
          description: Search query string supporting boolean operators (AND, OR, NOT), wildcards (*), and exact phrases ("").
        - name: dateRangeData.startDate
          in: query
          type: string
          description: Start date for date range filter (YYYY-MM-DD)
        - name: dateRangeData.endDate
          in: query
          type: string
          description: End date for date range filter (YYYY-MM-DD)
        - name: start
          in: query
          type: integer
          description: Pagination start offset
        - name: rows
          in: query
          type: integer
          description: Number of rows to return (max 25)
    - name: api-v1-patent-applications-search-download
      path: /api/v1/patent/applications/search/download
      operations:
      - name: downloadpatentapplicationssearch
        method: POST
        description: Download Patent Application Search Results
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-v1-patent-applications-applicationNumberText
      path: /api/v1/patent/applications/{applicationNumberText}
      operations:
      - name: getpatentapplication
        method: GET
        description: Get Patent Application by Application Number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: applicationNumberText
          in: path
          type: string
          description: Patent application number (e.g., 14412875)
          required: true
    - name: api-v1-patent-applications-applicationNumberText-adjustment
      path: /api/v1/patent/applications/{applicationNumberText}/adjustment
      operations:
      - name: getpatentapplicationadjustment
        method: GET
        description: Get Patent Application Patent Term Adjustment
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: applicationNumberText
          in: path
          type: string
          required: true
    - name: api-v1-patent-applications-applicationNumberText-assignment
      path: /api/v1/patent/applications/{applicationNumberText}/assignment
      operations:
      - name: getpatentapplicationassignment
        method: GET
        description: Get Patent Application Assignment Data
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: applicationNumberText
          in: path
          type: string
          required: true
    - name: api-v1-patent-applications-applicationNumberText-attorney
      path: /api/v1/patent/applications/{applicationNumberText}/attorney
      operations:
      - name: getpatentapplicationattorney
        method: GET
        description: Get Patent Application Attorney Information
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: applicationNumberText
          in: path
          type: string
          required: true
    - name: api-v1-patent-applications-applicationNumberText-continuity
      path: /api/v1/patent/applications/{applicationNumberText}/continuity
      operations:
      - name: getpatentapplicationcontinuity
        method: GET
        description: Get Patent Application Continuity Data
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: applicationNumberText
          in: path
          type: string
          required: true
    - name: api-v1-patent-applications-applicationNumberText-documents
      path: /api/v1/patent/applications/{applicationNumberText}/documents
      operations:
      - name: getpatentapplicationdocuments
        method: GET
        description: Get Patent Application Documents
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: applicationNumberText
          in: path
          type: string
          required: true
    - name: api-v1-patent-applications-applicationNumberText-foreign-priority
      path: /api/v1/patent/applications/{applicationNumberText}/foreign-priority
      operations:
      - name: getpatentapplicationforeignpriority
        method: GET
        description: Get Patent Application Foreign Priority
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: applicationNumberText
          in: path
          type: string
          required: true
    - name: api-v1-patent-applications-applicationNumberText-meta-data
      path: /api/v1/patent/applications/{applicationNumberText}/meta-data
      operations:
      - name: getpatentapplicationmetadata
        method: GET
        description: Get Patent Application Metadata
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: applicationNumberText
          in: path
          type: string
          required: true
    - name: api-v1-patent-applications-applicationNumberText-transactions
      path: /api/v1/patent/applications/{applicationNumberText}/transactions
      operations:
      - name: getpatentapplicationtransactions
        method: GET
        description: Get Patent Application Transaction History
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: applicationNumberText
          in: path
          type: string
          required: true
    - name: api-v1-patent-status-codes
      path: /api/v1/patent/status-codes
      operations:
      - name: getpatentstatuscodes
        method: GET
        description: Get Patent Application Status Codes
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    authentication:
      type: apikey
      key: X-API-KEY
      value: '{{env.US_PATENT_AND_TRADEMARK_OFFICE_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: uspto-open-data-portal-patent-search-rest
    port: 8080
    description: REST adapter for USPTO Open Data Portal API — Patent Search. One Spectral-compliant resource per consumed
      operation, prefixed with /v1.
    resources:
    - path: /v1/api/v1/patent/applications/search
      name: api-v1-patent-applications-search
      description: REST surface for api-v1-patent-applications-search.
      operations:
      - method: POST
        name: searchpatentapplicationspost
        description: Search Patent Applications by JSON Payload
        call: uspto-open-data-portal-patent-search.searchpatentapplicationspost
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: searchpatentapplicationsget
        description: Search Patent Applications by Query Parameters
        call: uspto-open-data-portal-patent-search.searchpatentapplicationsget
        with:
          q: rest.q
          dateRangeData.startDate: rest.dateRangeData.startDate
          dateRangeData.endDate: rest.dateRangeData.endDate
          start: rest.start
          rows: rest.rows
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/patent/applications/search/download
      name: api-v1-patent-applications-search-download
      description: REST surface for api-v1-patent-applications-search-download.
      operations:
      - method: POST
        name: downloadpatentapplicationssearch
        description: Download Patent Application Search Results
        call: uspto-open-data-portal-patent-search.downloadpatentapplicationssearch
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/patent/applications/{applicationnumbertext}
      name: api-v1-patent-applications-applicationnumbertext
      description: REST surface for api-v1-patent-applications-applicationNumberText.
      operations:
      - method: GET
        name: getpatentapplication
        description: Get Patent Application by Application Number
        call: uspto-open-data-portal-patent-search.getpatentapplication
        with:
          applicationNumberText: rest.applicationNumberText
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/patent/applications/{applicationnumbertext}/adjustment
      name: api-v1-patent-applications-applicationnumbertext-adjustment
      description: REST surface for api-v1-patent-applications-applicationNumberText-adjustment.
      operations:
      - method: GET
        name: getpatentapplicationadjustment
        description: Get Patent Application Patent Term Adjustment
        call: uspto-open-data-portal-patent-search.getpatentapplicationadjustment
        with:
          applicationNumberText: rest.applicationNumberText
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/patent/applications/{applicationnumbertext}/assignment
      name: api-v1-patent-applications-applicationnumbertext-assignment
      description: REST surface for api-v1-patent-applications-applicationNumberText-assignment.
      operations:
      - method: GET
        name: getpatentapplicationassignment
        description: Get Patent Application Assignment Data
        call: uspto-open-data-portal-patent-search.getpatentapplicationassignment
        with:
          applicationNumberText: rest.applicationNumberText
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/patent/applications/{applicationnumbertext}/attorney
      name: api-v1-patent-applications-applicationnumbertext-attorney
      description: REST surface for api-v1-patent-applications-applicationNumberText-attorney.
      operations:
      - method: GET
        name: getpatentapplicationattorney
        description: Get Patent Application Attorney Information
        call: uspto-open-data-portal-patent-search.getpatentapplicationattorney
        with:
          applicationNumberText: rest.applicationNumberText
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/patent/applications/{applicationnumbertext}/continuity
      name: api-v1-patent-applications-applicationnumbertext-continuity
      description: REST surface for api-v1-patent-applications-applicationNumberText-continuity.
      operations:
      - method: GET
        name: getpatentapplicationcontinuity
        description: Get Patent Application Continuity Data
        call: uspto-open-data-portal-patent-search.getpatentapplicationcontinuity
        with:
          applicationNumberText: rest.applicationNumberText
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/patent/applications/{applicationnumbertext}/documents
      name: api-v1-patent-applications-applicationnumbertext-documents
      description: REST surface for api-v1-patent-applications-applicationNumberText-documents.
      operations:
      - method: GET
        name: getpatentapplicationdocuments
        description: Get Patent Application Documents
        call: uspto-open-data-portal-patent-search.getpatentapplicationdocuments
        with:
          applicationNumberText: rest.applicationNumberText
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/patent/applications/{applicationnumbertext}/foreign-priority
      name: api-v1-patent-applications-applicationnumbertext-foreign-priority
      description: REST surface for api-v1-patent-applications-applicationNumberText-foreign-priority.
      operations:
      - method: GET
        name: getpatentapplicationforeignpriority
        description: Get Patent Application Foreign Priority
        call: uspto-open-data-portal-patent-search.getpatentapplicationforeignpriority
        with:
          applicationNumberText: rest.applicationNumberText
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/patent/applications/{applicationnumbertext}/meta-data
      name: api-v1-patent-applications-applicationnumbertext-meta-data
      description: REST surface for api-v1-patent-applications-applicationNumberText-meta-data.
      operations:
      - method: GET
        name: getpatentapplicationmetadata
        description: Get Patent Application Metadata
        call: uspto-open-data-portal-patent-search.getpatentapplicationmetadata
        with:
          applicationNumberText: rest.applicationNumberText
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/patent/applications/{applicationnumbertext}/transactions
      name: api-v1-patent-applications-applicationnumbertext-transactions
      description: REST surface for api-v1-patent-applications-applicationNumberText-transactions.
      operations:
      - method: GET
        name: getpatentapplicationtransactions
        description: Get Patent Application Transaction History
        call: uspto-open-data-portal-patent-search.getpatentapplicationtransactions
        with:
          applicationNumberText: rest.applicationNumberText
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/patent/status-codes
      name: api-v1-patent-status-codes
      description: REST surface for api-v1-patent-status-codes.
      operations:
      - method: GET
        name: getpatentstatuscodes
        description: Get Patent Application Status Codes
        call: uspto-open-data-portal-patent-search.getpatentstatuscodes
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: uspto-open-data-portal-patent-search-mcp
    port: 9090
    transport: http
    description: MCP adapter for USPTO Open Data Portal API — Patent Search. One tool per consumed operation, routed inline
      through this capability's consumes block.
    tools:
    - name: search-patent-applications-json-payload
      description: Search Patent Applications by JSON Payload
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: uspto-open-data-portal-patent-search.searchpatentapplicationspost
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: search-patent-applications-query-parameters
      description: Search Patent Applications by Query Parameters
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: uspto-open-data-portal-patent-search.searchpatentapplicationsget
      with:
        q: tools.q
        dateRangeData.startDate: tools.dateRangeData.startDate
        dateRangeData.endDate: tools.dateRangeData.endDate
        start: tools.start
        rows: tools.rows
      outputParameters:
      - type: object
        mapping: $.
    - name: download-patent-application-search-results
      description: Download Patent Application Search Results
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: uspto-open-data-portal-patent-search.downloadpatentapplicationssearch
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-patent-application-application-number
      description: Get Patent Application by Application Number
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: uspto-open-data-portal-patent-search.getpatentapplication
      with:
        applicationNumberText: tools.applicationNumberText
      outputParameters:
      - type: object
        mapping: $.
    - name: get-patent-application-patent-term
      description: Get Patent Application Patent Term Adjustment
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: uspto-open-data-portal-patent-search.getpatentapplicationadjustment
      with:
        applicationNumberText: tools.applicationNumberText
      outputParameters:
      - type: object
        mapping: $.
    - name: get-patent-application-assignment-data
      description: Get Patent Application Assignment Data
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: uspto-open-data-portal-patent-search.getpatentapplicationassignment
      with:
        applicationNumberText: tools.applicationNumberText
      outputParameters:
      - type: object
        mapping: $.
    - name: get-patent-application-attorney-information
      description: Get Patent Application Attorney Information
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: uspto-open-data-portal-patent-search.getpatentapplicationattorney
      with:
        applicationNumberText: tools.applicationNumberText
      outputParameters:
      - type: object
        mapping: $.
    - name: get-patent-application-continuity-data
      description: Get Patent Application Continuity Data
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: uspto-open-data-portal-patent-search.getpatentapplicationcontinuity
      with:
        applicationNumberText: tools.applicationNumberText
      outputParameters:
      - type: object
        mapping: $.
    - name: get-patent-application-documents
      description: Get Patent Application Documents
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: uspto-open-data-portal-patent-search.getpatentapplicationdocuments
      with:
        applicationNumberText: tools.applicationNumberText
      outputParameters:
      - type: object
        mapping: $.
    - name: get-patent-application-foreign-priority
      description: Get Patent Application Foreign Priority
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: uspto-open-data-portal-patent-search.getpatentapplicationforeignpriority
      with:
        applicationNumberText: tools.applicationNumberText
      outputParameters:
      - type: object
        mapping: $.
    - name: get-patent-application-metadata
      description: Get Patent Application Metadata
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: uspto-open-data-portal-patent-search.getpatentapplicationmetadata
      with:
        applicationNumberText: tools.applicationNumberText
      outputParameters:
      - type: object
        mapping: $.
    - name: get-patent-application-transaction-history
      description: Get Patent Application Transaction History
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: uspto-open-data-portal-patent-search.getpatentapplicationtransactions
      with:
        applicationNumberText: tools.applicationNumberText
      outputParameters:
      - type: object
        mapping: $.
    - name: get-patent-application-status-codes
      description: Get Patent Application Status Codes
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: uspto-open-data-portal-patent-search.getpatentstatuscodes
      outputParameters:
      - type: object
        mapping: $.