University of Southampton OAI PMH API

openapi: 3.2.0
info:
  title: ePrints Soton Interface OAI PMH API
  version: '2.0'
  x-generated: '2026-08-30'
  x-method: derived
  x-source: Derived from live probes of https://eprints.soton.ac.uk/cgi/oai2 on 2026-08-30. Every operation, parameter and response below was exercised against the running service with a non-browser User-Agent; nothing is assumed from the OAI-PMH specification alone. Captured responses are held in examples/eprints-oai-identify.xml, examples/eprints-oai-listmetadataformats.xml and examples/eprints-oai-getrecord-oai_dc.xml. The University of Southampton does not publish an OpenAPI description of this endpoint; this document is API Evangelist's, not the institution's.
  x-operator: institution
  x-operator-evidence: eprints.soton.ac.uk resolves to 152.78.118.18, inside the University's own JANET allocation. The Identify response self-declares repositoryName "ePrints Soton", repositoryIdentifier "eprints.soton.ac.uk" and adminEmail eprints@soton.ac.uk, and states the system runs "eprints server software (EPrints 3.3.15) developed at the University of Southampton". Unusually for this cohort the repository software is the institution's own product, not a supplier's, so neither the host nor the platform is a vendor.
  description: OAI-PMH 2.0 metadata harvesting interface for ePrints Soton, the University of Southampton's institutional research repository.
  contact:
    name: ePrints Soton
    email: eprints@soton.ac.uk
    url: https://eprints.soton.ac.uk/
  license:
    name: Repository metadata policy (free re-use, attribution via OAI identifier)
    url: https://eprints.soton.ac.uk/cgi/oai2?verb=Identify
servers:
- url: https://eprints.soton.ac.uk/cgi
  description: ePrints Soton OAI-PMH base URL, University of Southampton
tags:
- name: oai pmh
  description: Open Archives Initiative Protocol for Metadata Harvesting, version 2.0.
paths:
  /oai2:
    get:
      operationId: oaiRequest
      summary: Issue an OAI-PMH request
      description: Single-endpoint protocol. The `verb` parameter selects the operation; the remaining parameters are conditional on the verb. Verified live for Identify, ListMetadataFormats, ListSets and GetRecord.
      tags:
      - oai pmh
      parameters:
      - name: verb
        in: query
        required: true
        description: The OAI-PMH operation to perform.
        schema:
          type: string
          enum:
          - Identify
          - ListMetadataFormats
          - ListSets
          - ListIdentifiers
          - ListRecords
          - GetRecord
      - name: metadataPrefix
        in: query
        required: false
        description: Metadata format to return. Required for GetRecord, ListRecords and ListIdentifiers. The eight prefixes enumerated here were read from a live ListMetadataFormats response on 2026-08-30, not from the protocol default set.
        schema:
          type: string
          enum:
          - oai_dc
          - rioxx
          - uketd_dc
          - mets
          - didl
          - rdf
          - oai_bibl
          - oai_dc_ebsco
      - name: identifier
        in: query
        required: false
        description: OAI identifier of a single record. Required for GetRecord. Scheme `oai`, repository identifier `eprints.soton.ac.uk`, delimiter `:` — for example `oai:eprints.soton.ac.uk:498754`.
        schema:
          type: string
          pattern: ^oai:eprints\.soton\.ac\.uk:[0-9]+$
      - name: set
        in: query
        required: false
        description: Restrict a listing to one set. ePrints encodes setSpec values as hexadecimal of the underlying field expression, so the values are opaque and must be read from ListSets rather than constructed.
        schema:
          type: string
      - name: from
        in: query
        required: false
        description: Lower bound on the record datestamp. Granularity YYYY-MM-DDThh:mm:ssZ.
        schema:
          type: string
          format: date-time
      - name: until
        in: query
        required: false
        description: Upper bound on the record datestamp. Granularity YYYY-MM-DDThh:mm:ssZ.
        schema:
          type: string
          format: date-time
      - name: resumptionToken
        in: query
        required: false
        description: Continuation token from a previous incomplete list response.
        schema:
          type: string
      responses:
        '200':
          description: An OAI-PMH envelope. Note that protocol-level failures are also returned as HTTP 200 carrying an `<error>` element with a `code` attribute; HTTP status alone is not a success signal on this API.
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/OAIPMHResponse'
        '401':
          description: Anubis proof-of-work bot challenge. Returned to browser-like User-Agent strings. The body is an HTML challenge page, not an OAI-PMH envelope. Retry with a plain or harvester User-Agent.
          content:
            text/html:
              schema:
                type: string
        '403':
          description: 'Anubis denial. Returned to User-Agent strings matched as disallowed crawlers, including Googlebot. Distinct from the 401 challenge: no proof-of-work will satisfy it.'
          content:
            text/html:
              schema:
                type: string
components:
  schemas:
    OAIError:
      type: object
      properties:
        code:
          type: string
          enum:
          - badArgument
          - badResumptionToken
          - badVerb
          - cannotDisseminateFormat
          - idDoesNotExist
          - noRecordsMatch
          - noMetadataFormats
          - noSetHierarchy
        message:
          type: string
    Identify:
      type: object
      description: Values below are those the live service returned on 2026-08-30.
      properties:
        repositoryName:
          type: string
          examples:
          - ePrints Soton
        baseURL:
          type: string
          format: uri
          examples:
          - http://eprints.soton.ac.uk/cgi/oai2
        protocolVersion:
          type: string
          examples:
          - '2.0'
        adminEmail:
          type: string
          format: email
          examples:
          - eprints@soton.ac.uk
        earliestDatestamp:
          type: string
          format: date-time
          examples:
          - '2021-12-11T15:30:50Z'
        deletedRecord:
          type: string
          examples:
          - persistent
        granularity:
          type: string
          examples:
          - YYYY-MM-DDThh:mm:ssZ
    OAIPMHResponse:
      type: object
      description: Root OAI-PMH envelope, namespace http://www.openarchives.org/OAI/2.0/.
      properties:
        responseDate:
          type: string
          format: date-time
        request:
          type: string
          format: uri
        error:
          $ref: '#/components/schemas/OAIError'
        Identify:
          $ref: '#/components/schemas/Identify'