GoVeda API

openapi: 3.1.0
info:
  title: GoVeda API
  version: '2026-11-10'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-10: 31 operation(s) read from 13 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; GoVeda has published no machine-readable contract that
    the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 3
    documentation: 28
    pages-with-code: 13
    pages-read: 13
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-10'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://www.goveda.com/docs/api
  - https://www.goveda.com/de/docs/api
  - https://www.goveda.com/en/docs/api
  - https://www.goveda.com/es/docs/api
  - https://www.goveda.com/fr/docs/api
  - https://www.goveda.com/ja/docs/api
  - https://www.goveda.com/ko/docs/api
  - https://www.goveda.com/zh/docs/api
  - https://openapi.goveda.com/api-references
  - https://www.goveda.com/docs/getting-started/your-first-mcp
  - https://www.goveda.com/de/docs/agent/mcp
  - https://www.goveda.com/en/docs/agent/mcp
  - https://www.goveda.com/es/docs/agent/mcp
servers:
- url: https://mcp.goveda.com
paths:
  /api/patents/batch-content:
    post:
      operationId: post_api_patents_batch_content
      tags:
      - Api
      summary: Retrieve patents in batch
      x-source: https://openapi.goveda.com/api-references
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/patents/batch-translations:
    post:
      operationId: post_api_patents_batch_translations
      tags:
      - Api
      summary: Retrieve translations for patents in batch
      x-source: https://openapi.goveda.com/api-references
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/patents/{publicationNumber}/backward-npl-citations:
    get:
      operationId: get_api_patents_publicationNumber_backward_npl_citations
      tags:
      - Api
      summary: List backward non‑patent literature citations of a patent
      x-source: https://openapi.goveda.com/api-references
      parameters:
      - name: publicationNumber
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/patents/{publicationNumber}/backward-patent-citations:
    get:
      operationId: get_api_patents_publicationNumber_backward_patent_citations
      tags:
      - Api
      summary: List backward patent citations of a patent
      x-source: https://openapi.goveda.com/api-references
      parameters:
      - name: publicationNumber
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/patents/{publicationNumber}/content:
    get:
      operationId: get_api_patents_publicationNumber_content
      tags:
      - Api
      summary: Retrieve a patent's bibliographic data, text, legal status or family
      x-source: https://openapi.goveda.com/api-references
      parameters:
      - name: publicationNumber
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/patents/{publicationNumber}/forward-citations:
    get:
      operationId: get_api_patents_publicationNumber_forward_citations
      tags:
      - Api
      summary: List forward citations of a patent
      x-source: https://openapi.goveda.com/api-references
      parameters:
      - name: publicationNumber
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/patents/{publicationNumber}/transfers:
    get:
      operationId: get_api_patents_publicationNumber_transfers
      tags:
      - Api
      summary: Retrieve a patent's transfer information
      x-source: https://openapi.goveda.com/api-references
      parameters:
      - name: publicationNumber
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/patents/{publicationNumber}/translations:
    get:
      operationId: get_api_patents_publicationNumber_translations
      tags:
      - Api
      summary: Retrieve a patent's translations
      x-source: https://openapi.goveda.com/api-references
      parameters:
      - name: publicationNumber
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/reports:
    post:
      operationId: post_api_reports
      tags:
      - Api
      summary: Create a novelty report
      x-source: https://openapi.goveda.com/api-references
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiReportsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/reports/{reportId}:
    get:
      operationId: get_api_reports_reportId
      tags:
      - Api
      summary: Retrieve status of a report
      x-source: https://openapi.goveda.com/api-references
      parameters:
      - name: reportId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/search:
    post:
      operationId: post_api_search
      tags:
      - Api
      summary: Deprecated semantic search endpoint (v1) – use POST /api/v2/patents/search
      x-source: https://www.goveda.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiSearchRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiSearchResponse'
      x-evidence:
        kind: documentation
  /api/search/party/count:
    post:
      operationId: post_api_search_party_count
      tags:
      - Api
      summary: Count patents by party (deprecated v1 endpoint).
      description: Deprecated v1 endpoint that maps to POST /api/v2/stats/aggregate.
      x-source: https://openapi.goveda.com/api-references
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/search/party/patents:
    post:
      operationId: post_api_search_party_patents
      tags:
      - Api
      summary: List patents for a party (deprecated v1 endpoint).
      description: Deprecated v1 endpoint that maps to POST /api/v2/stats/list.
      x-source: https://openapi.goveda.com/api-references
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/search/party/suggest:
    get:
      operationId: get_api_search_party_suggest
      tags:
      - Api
      summary: Suggest party names (deprecated v1 endpoint).
      description: Deprecated v1 endpoint that maps to POST /api/v2/assignees/resolve, or POST /api/v2/assignees/group for expand_hierarchy.
      x-source: https://openapi.goveda.com/api-references
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/search/prior-art:
    post:
      operationId: post_api_search_prior_art
      tags:
      - Api
      summary: Deprecated prior‑art search endpoint – use POST /api/v2/patents/prior-art
      x-source: https://www.goveda.com/docs/api
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiSearchPriorArtRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiSearchPriorArtResponse'
      x-evidence:
        kind: documentation
  /api/search/v2:
    post:
      operationId: post_api_search_v2
      tags:
      - Api
      summary: Deprecated synchronous form of POST /api/search (v1) – use POST /api/v2/patents/search
      x-source: https://www.goveda.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiSearchV2Request'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiSearchV2Response'
      x-evidence:
        kind: documentation
  /api/search/{searchId}:
    get:
      operationId: get_api_search_searchId
      tags:
      - Api
      summary: Deprecated endpoint to retrieve results of a stored search – use GET /api/v2/patents/prior-art/{job_id}
      x-source: https://www.goveda.com/docs/api
      parameters:
      - name: searchId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiSearchSearchidResponse'
      x-evidence:
        kind: documentation
  /api/usage/balance:
    get:
      operationId: get_api_usage_balance
      tags:
      - Api
      summary: GET /api/usage/balance
      x-source: https://www.goveda.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://openapi.goveda.com/api/usage/balance  --header \"X-API-Key: $GOVEDA_API_KEY \" A successful response confirms that\
          \ the key works. Read the direct API balance from pools.api ; the top-level balance fields show the web credit pool. If authentication\
          \ fails, see Authentication and common errors   . \n Choose a workflow \n What you want to do Start here How it runs Search by meaning\
          \ with v2 fi"
  /api/usage/records:
    get:
      operationId: get_api_usage_records
      tags:
      - Api
      summary: List usage records
      x-source: https://openapi.goveda.com/api-references
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/usage/stats:
    get:
      operationId: get_api_usage_stats
      tags:
      - Api
      summary: Retrieve usage statistics
      x-source: https://openapi.goveda.com/api-references
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v2/assignees/group:
    post:
      operationId: post_api_v2_assignees_group
      tags:
      - Api
      summary: Expand a corporate group
      x-source: https://www.goveda.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV2AssigneesGroupRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV2AssigneesGroupResponse'
      x-evidence:
        kind: documentation
  /api/v2/assignees/resolve:
    post:
      operationId: post_api_v2_assignees_resolve
      tags:
      - Api
      summary: Resolve assignee names
      x-source: https://www.goveda.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV2AssigneesResolveRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV2AssigneesResolveResponse'
      x-evidence:
        kind: documentation
  /api/v2/patents/batch:
    post:
      operationId: post_api_v2_patents_batch
      tags:
      - Api
      summary: POST /api/v2/patents/batch lists such references in unidentified instead.
      x-source: https://www.goveda.com/docs/api
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v2/patents/prior-art:
    post:
      operationId: post_api_v2_patents_prior_art
      tags:
      - Api
      summary: Prior-art search with v2 fields
      x-source: https://www.goveda.com/docs/api
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV2PatentsPriorArtRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV2PatentsPriorArtResponse'
      x-evidence:
        kind: documentation
  /api/v2/patents/prior-art/{jobId}:
    get:
      operationId: get_api_v2_patents_prior_art_jobId
      tags:
      - Api
      summary: Poll status and retrieve results of a prior‑art job
      x-source: https://www.goveda.com/docs/api
      parameters:
      - name: jobId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV2PatentsPriorArtJobidResponse'
      x-evidence:
        kind: documentation
  /api/v2/patents/search:
    post:
      operationId: post_api_v2_patents_search
      tags:
      - Api
      summary: Semantic search with v2 fields
      x-source: https://www.goveda.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV2PatentsSearchRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV2PatentsSearchResponse'
      x-evidence:
        kind: documentation
  /api/v2/patents/{reference}:
    get:
      operationId: get_api_v2_patents_reference
      tags:
      - Api
      summary: Read a single patent record by reference
      x-source: https://www.goveda.com/docs/api
      parameters:
      - name: reference
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV2PatentsReferenceResponse'
      x-evidence:
        kind: documentation
  /api/v2/stats/aggregate:
    post:
      operationId: post_api_v2_stats_aggregate
      tags:
      - Api
      summary: Statistics API – aggregate counts, ranks, or lists of patents, applications, or simple families
      x-source: https://www.goveda.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV2StatsAggregateRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV2StatsAggregateResponse'
      x-evidence:
        kind: documentation
  /api/v2/stats/list:
    post:
      operationId: post_api_v2_stats_list
      tags:
      - Api
      summary: List the patents behind a count
      x-source: https://openapi.goveda.com/api-references
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV2StatsListRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /mcp:
    get:
      operationId: get_mcp
      tags:
      - Mcp
      summary: GET /mcp
      x-source: https://www.goveda.com/docs/getting-started/your-first-mcp
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: httpie
        snippet: 'http https://mcp.goveda.com/mcp Claude Code handles OAuth: a browser window opens to complete the sign-in. Other clients Add
          this to your MCP client configuration: { '
    post:
      operationId: post_mcp
      tags:
      - Mcp
      summary: Servidor MCP de Patentes
      x-source: https://www.goveda.com/es/docs/agent/mcp
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PostApiReportsRequest:
      type: object
      properties:
        invention_description:
          type: string
          description: Description of the invention to assess
        options:
          type: string
          description: Optional report parameters
      required:
      - invention_description
    PostApiSearchRequest:
      type: object
      properties:
        search_conditions:
          type: object
          description: Conditions for the v1 semantic search.
        fields:
          type: array
          description: Fields to return in each result.
      required:
      - search_conditions
    PostApiSearchResponse:
      type: object
      properties:
        search_id:
          type: string
          description: Identifier for the stored search.
        records:
          type: array
          description: Search results.
    PostApiSearchPriorArtRequest:
      type: object
      properties:
        reference:
          type: string
          description: Patent reference number.
        document:
          type: object
          description: Invention text.
        filter:
          type: object
          description: Optional filter.
    PostApiSearchPriorArtResponse:
      type: object
      properties:
        search_id:
          type: string
          description: Identifier for the asynchronous prior‑art job.
        status:
          type: string
          description: Initial status (202).
    PostApiSearchV2Request:
      type: object
      properties:
        search_conditions:
          type: object
          description: Conditions for the v1 search.
        fields:
          type: array
          description: Fields to return.
      required:
      - search_conditions
    PostApiSearchV2Response:
      type: object
      properties:
        search_id:
          type: string
          description: Persistent search ID.
        records:
          type: array
          description: Search results.
    GetApiSearchSearchidResponse:
      type: object
      properties:
        records:
          type: array
          description: Search results.
        meta:
          type: object
          description: Metadata about the search.
    PostApiV2AssigneesGroupRequest:
      type: object
      properties:
        name:
          type: string
          description: Canonical assignee name to expand.
      required:
      - name
    PostApiV2AssigneesGroupResponse:
      type: object
      properties:
        group:
          type: object
          description: Corporate group details including ultimate owner, subsidiaries, merged companies and former names.
    PostApiV2AssigneesResolveRequest:
      type: object
      properties:
        names:
          type: array
          description: List of assignee names to resolve to canonical names.
      required:
      - names
    PostApiV2AssigneesResolveResponse:
      type: object
      properties:
        resolved:
          type: object
          description: Mapping of input names to canonical assignee names.
        unmatched_names:
          type: array
          description: Names that could not be resolved.
    PostApiV2PatentsPriorArtRequest:
      type: object
      properties:
        reference:
          type: string
          description: Publication, application, or PCT number of the patent to search against.
        document:
          type: object
          description: Invention text containing abstract, claims, description, optional title and effective_date.
        filter:
          type: object
          description: Optional filter for the search.
        collapse_by:
          type: string
          description: Field to collapse results by.
        representative:
          type: boolean
          description: Whether to return a representative record per group.
        limit:
          type: integer
          description: Number of results per page (1–1,000, default 50).
    PostApiV2PatentsPriorArtResponse:
      type: object
      properties:
        job_id:
          type: string
          description: Identifier for the asynchronous prior‑art job.
        status:
          type: string
          description: Initial status (202 Accepted).
    GetApiV2PatentsPriorArtJobidResponse:
      type: object
      properties:
        status:
          type: string
          description: Current status of the job (e.g., pending, completed, failed).
        records:
          type: array
          description: Paged patent records when status is completed.
        meta:
          type: object
          description: Metadata including pagination info (offset, limit).
    PostApiV2PatentsSearchRequest:
      type: object
      properties:
        query:
          type: string
          description: Search query string.
        filter:
          type: object
          description: Optional filter using statistics clauses on the 18 search fields.
        limit:
          type: integer
          description: Number of results to return (1–1,000).
        collapse_by:
          type: string
          description: Field to collapse results by.
        representative:
          type: boolean
          description: Whether to return a representative record per group.
        exact_terms:
          type: array
          description: Optional exact terms to match.
        fields:
          type: array
          description: Record options fields to include in each result.
        member_fields:
          type: array
          description: Member fields to include.
        lang:
          type: string
          description: Language for translation.
        family_fill:
          type: boolean
          description: Whether to fill family information.
      required:
      - query
    PostApiV2PatentsSearchResponse:
      type: object
      properties:
        records:
          type: array
          description: Array of patent records matching the query.
        meta:
          type: object
          description: Metadata about the search, including credits used.
    GetApiV2PatentsReferenceResponse:
      type: object
      properties:
        record:
          type: object
          description: Patent record with requested fields.
        error:
          type: object
          description: Error object if the reference is not found (404).
    PostApiV2StatsAggregateRequest:
      type: object
      properties:
        filter:
          type: object
          description: Statistics filter using v2 field names.
        aggregate:
          type: string
          description: Aggregation type (count, rank, list).
        field:
          type: string
          description: Field to aggregate on.
      required:
      - filter
      - aggregate
      - field
    PostApiV2StatsAggregateResponse:
      type: object
      properties:
        result:
          type: object
          description: Aggregation result according to the requested type.
    PostApiV2StatsListRequest:
      type: object
      properties:
        group_id:
          type: string
          description: Identifier of the aggregated group to list patents for
        page:
          type: string
          description: Pagination page number
        page_size:
          type: string
          description: Number of records per page
      required:
      - group_id
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
security:
- apiKey: []
tags:
- name: Api
- name: Mcp