openapi: 3.0.3
info:
  title: bonndata Dataverse Native REST API (Public Read Subset)
  description: >-
    Public, read-only subset of the Dataverse Native REST API as exposed by
    bonndata, the University of Bonn institutional research data repository
    (https://bonndata.uni-bonn.de). The paths, parameters, and operationIds in
    this document are taken faithfully from the live machine-readable OpenAPI
    document published by the server at https://bonndata.uni-bonn.de/openapi
    (Dataverse software version 6.7.1). This subset includes only the endpoints
    that are publicly accessible without an API token and were verified live on
    2026-06-03 (search, dataset retrieval, dataset versions, metadata export,
    repository info, and dataset metrics). Response schemas were modeled from
    the actual JSON payloads returned by the live service. The full upstream
    Dataverse API (425 paths, many requiring authentication) is documented at
    the Native API guide referenced below.
  version: 6.7.1
  contact:
    name: bonndata Research Data Repository, University of Bonn
    email: bonndata@uni-bonn.de
    url: https://bonndata.uni-bonn.de/
  license:
    name: Apache License 2.0
    url: https://github.com/IQSS/dataverse/blob/develop/LICENSE.md
externalDocs:
  description: Dataverse Native API guide
  url: https://guides.dataverse.org/en/latest/api/native-api.html
servers:
  - url: https://bonndata.uni-bonn.de/api
    description: bonndata Dataverse Native API base (verified live, 362 indexed datasets)
tags:
  - name: Search
    description: Search the published catalog of datasets, dataverses, and files.
  - name: Datasets
    description: Retrieve published datasets, their versions, and export metadata.
  - name: Info
    description: Repository version and software information.
  - name: Metrics
    description: Aggregate repository metrics.
paths:
  /search:
    get:
      tags: [Search]
      summary: Search published content
      description: >-
        Search across published datasets, dataverses (collections), and files.
        Verified live returning 362 indexed datasets for q=*&type=dataset.
      operationId: Search_search
      parameters:
        - name: q
          in: query
          description: Search query string (use * to match all).
          schema: { type: string }
        - name: type
          in: query
          description: Restrict results to a content type.
          schema:
            type: array
            items:
              type: string
              enum: [dataset, dataverse, file]
        - name: subtree
          in: query
          description: Restrict the search to one or more dataverse aliases.
          schema:
            type: array
            items: { type: string }
        - name: sort
          in: query
          description: Field to sort on (e.g. name, date).
          schema: { type: string }
        - name: order
          in: query
          description: Sort order.
          schema:
            type: string
            enum: [asc, desc]
        - name: per_page
          in: query
          description: Number of results per page (max 1000).
          schema: { type: integer, default: 10 }
        - name: start
          in: query
          description: Zero-based offset of the first result to return.
          schema: { type: integer, default: 0 }
        - name: fq
          in: query
          description: Filter query(ies) to narrow results.
          schema:
            type: array
            items: { type: string }
        - name: show_relevance
          in: query
          schema: { type: boolean }
        - name: show_facets
          in: query
          schema: { type: boolean }
        - name: show_entity_ids
          in: query
          schema: { type: boolean }
        - name: show_type_counts
          in: query
          schema: { type: boolean }
        - name: geo_point
          in: query
          description: Latitude,longitude point for geospatial search.
          schema: { type: string }
        - name: geo_radius
          in: query
          description: Radius in kilometers for geospatial search.
          schema: { type: string }
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
  /search/services:
    get:
      tags: [Search]
      summary: List available search engines
      operationId: Search_getSearchEngines
      responses:
        '200':
          description: Available search services.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiEnvelope'
  /info/version:
    get:
      tags: [Info]
      summary: Get version and build information
      operationId: Info_getInfo
      responses:
        '200':
          description: Dataverse software version and build.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionResponse'
  /info/metrics/datasets:
    get:
      tags: [Metrics]
      summary: Count of published datasets
      operationId: Metrics_getDatasetsAllTime
      parameters:
        - name: dataLocation
          in: query
          schema: { type: string }
        - name: parentAlias
          in: query
          schema: { type: string }
      responses:
        '200':
          description: All-time count of published datasets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountResponse'
  /datasets/{id}:
    get:
      tags: [Datasets]
      summary: Get a dataset
      description: >-
        Retrieve a published dataset by its numeric database id, or by
        persistent identifier using the literal path segment ":persistentId"
        together with the persistentId query parameter (e.g.
        /datasets/:persistentId/?persistentId=doi:10.60507/FK2/BBP6GG).
      operationId: Datasets_getDataset
      parameters:
        - name: id
          in: path
          required: true
          description: Numeric dataset id, or the literal ":persistentId".
          schema: { type: string }
        - name: persistentId
          in: query
          description: Persistent identifier (DOI/Handle) when id is ":persistentId".
          schema: { type: string }
        - name: returnOwners
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: The dataset and its latest published version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiEnvelope'
  /datasets/{id}/versions:
    get:
      tags: [Datasets]
      summary: List dataset versions
      operationId: Datasets_listVersions
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: excludeFiles
          in: query
          schema: { type: boolean }
        - name: excludeMetadataBlocks
          in: query
          schema: { type: boolean }
        - name: limit
          in: query
          schema: { type: integer }
        - name: offset
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: List of dataset versions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiEnvelope'
  /datasets/export:
    get:
      tags: [Datasets]
      summary: Export dataset metadata
      description: >-
        Export the metadata of a published dataset in a chosen format
        (e.g. Datacite, dataverse_json, oai_dc, schema.org, ddi).
      operationId: Datasets_exportDataset
      parameters:
        - name: persistentId
          in: query
          description: Persistent identifier (DOI/Handle) of the dataset.
          schema: { type: string }
        - name: exporter
          in: query
          description: Export format name.
          schema:
            type: string
            example: schema.org
        - name: version
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Exported metadata in the requested format.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
            application/xml:
              schema:
                type: string
components:
  schemas:
    ApiEnvelope:
      type: object
      description: Standard Dataverse API response envelope.
      properties:
        status:
          type: string
          enum: [OK, ERROR]
        data:
          type: object
          additionalProperties: true
        message:
          type: string
      required: [status]
    VersionResponse:
      type: object
      properties:
        status:
          type: string
          example: OK
        data:
          type: object
          properties:
            version:
              type: string
              example: 6.7.1
            build:
              type: string
              example: 1955-8e18f64
          required: [version]
      required: [status, data]
    CountResponse:
      type: object
      properties:
        status:
          type: string
          example: OK
        data:
          type: object
          properties:
            count:
              type: integer
              example: 362
          required: [count]
      required: [status, data]
    SearchResponse:
      type: object
      properties:
        status:
          type: string
          example: OK
        data:
          $ref: '#/components/schemas/SearchData'
      required: [status, data]
    SearchData:
      type: object
      properties:
        q:
          type: string
          example: '*'
        total_count:
          type: integer
          example: 362
        start:
          type: integer
          example: 0
        spelling_alternatives:
          type: object
          additionalProperties: true
        count_in_response:
          type: integer
          example: 2
        items:
          type: array
          items:
            $ref: '#/components/schemas/SearchItem'
      required: [total_count, start, items]
    SearchItem:
      type: object
      description: A single search hit. Fields shown are those returned for datasets.
      properties:
        name:
          type: string
        type:
          type: string
          enum: [dataset, dataverse, file]
        url:
          type: string
          format: uri
        global_id:
          type: string
          example: doi:10.60507/FK2/BBP6GG
        description:
          type: string
        published_at:
          type: string
          format: date-time
        publisher:
          type: string
        citationHtml:
          type: string
        identifier_of_dataverse:
          type: string
        name_of_dataverse:
          type: string
        citation:
          type: string
        storageIdentifier:
          type: string
        subjects:
          type: array
          items: { type: string }
        fileCount:
          type: integer
        versionId:
          type: integer
        versionState:
          type: string
          example: RELEASED
        majorVersion:
          type: integer
        minorVersion:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        publicationStatuses:
          type: array
          items: { type: string }
        contacts:
          type: array
          items:
            type: object
            additionalProperties: true
        authors:
          type: array
          items: { type: string }
        geographicCoverage:
          type: array
          items: { type: string }
      required: [name, type, url]