openapi: 3.2.0
info:
  title: UTokyo Metadata Harvesting Oai Pmh API
  version: '2.0'
  summary: The two OAI-PMH 2.0 harvesting endpoints the University of Tokyo operates on its own hosts — the institutional repository and the Academic Assets Archives Portal.
  description: "OAI-PMH is the one machine-readable interface the University of Tokyo documents publicly and\noperates itself, and it is served twice:\n\n* **UTokyo Repository** — `https://repository.dl.itc.u-tokyo.ac.jp/oai`. Identify returns\n  repositoryName \"UTokyo Repository\", adminEmail digilib@lib.u-tokyo.ac.jp, earliest\n  datestamp 2017-03-28, deletedRecord `transient`. Seven metadata formats: `jpcoar_2.0`,\n  `jpcoar`, `jpcoar_1.0`, `jpcoar_v1`, `oai_dc`, `ddi` (DDI-Codebook 2.5) and `lom`.\n* **UTokyo Academic Assets Archives Portal** — `https://da.dl.itc.u-tokyo.ac.jp/portal/oai`.\n  Identify returns repositoryName \"UTokyo Academic Archives Portal\", adminEmail\n  jitsumu_arch@lib.u-tokyo.ac.jp, earliest datestamp 2013-01-01, deletedRecord `persistent`,\n  1,957 sets. Five metadata formats: `oai_dc`, `dcndl_simple`, `dcndl_js`, `junii2`, `jpcoar`.\n  This one is documented, in Japanese only, at\n  https://da.dl.itc.u-tokyo.ac.jp/portal/help/api — the English page at\n  /portal/en/help/api says only \"Only available in Japanese\" and links across.\n\nThis document describes the protocol as these two deployments actually answer it. OAI-PMH is\na query-string verb protocol, not a REST API, so the OpenAPI shape here is a description for\ntooling, not a claim that the university publishes an OpenAPI. Responses are XML.\n\nAccess note: `repository.dl.itc.u-tokyo.ac.jp` returns HTTP 406 to requests carrying a\ndesktop-browser User-Agent and HTTP 200 to a plain client. The block is inverted from the\nusual bot challenge. Harvest it with a plain HTTP client and a real contact string, not with\na spoofed browser UA.\n"
  contact:
    name: University of Tokyo Library System — Digital Library Section
    email: digilib@lib.u-tokyo.ac.jp
    url: https://www.lib.u-tokyo.ac.jp/en/
servers:
- url: https://repository.dl.itc.u-tokyo.ac.jp/oai
  description: UTokyo Repository (WEKO3). Institution-operated.
- url: https://da.dl.itc.u-tokyo.ac.jp/portal/oai
  description: UTokyo Academic Assets Archives Portal. Institution-operated.
tags:
- name: oai-pmh
  description: Open Archives Initiative Protocol for Metadata Harvesting, version 2.0.
paths:
  /:
    get:
      operationId: oaiRequest
      summary: Issue an OAI-PMH 2.0 request
      description: A single endpoint dispatching on the `verb` parameter, per OAI-PMH 2.0. Errors are returned inside a 200 response as an `<error>` element with an OAI-PMH error code, not as an HTTP status — this is protocol-correct and callers must parse the body.
      tags:
      - oai-pmh
      parameters:
      - name: verb
        in: query
        required: true
        description: The OAI-PMH verb.
        schema:
          type: string
          enum:
          - Identify
          - ListMetadataFormats
          - ListSets
          - ListIdentifiers
          - ListRecords
          - GetRecord
        example: Identify
      - name: metadataPrefix
        in: query
        required: false
        description: Required for ListIdentifiers, ListRecords and GetRecord. Repository accepts jpcoar_2.0, jpcoar, jpcoar_1.0, jpcoar_v1, oai_dc, ddi, lom. Archives Portal accepts oai_dc, dcndl_simple, dcndl_js, junii2, jpcoar.
        schema:
          type: string
        example: oai_dc
      - name: identifier
        in: query
        required: false
        description: Required for GetRecord. Archives Portal form is `oai:da.dl.itc.u-tokyo.ac.jp:<uuid>` where the UUID is the trailing segment of the item detail page URL under /portal/assets/.
        schema:
          type: string
        example: oai:da.dl.itc.u-tokyo.ac.jp:fbd0479b-dbb4-4eaa-95b8-f27e1c423e4b
      - name: set
        in: query
        required: false
        description: Restrict to one set. Enumerate with verb=ListSets.
        schema:
          type: string
      - name: from
        in: query
        required: false
        description: Lower bound on the datestamp. Granularity YYYY-MM-DDThh:mm:ssZ.
        schema:
          type: string
        example: '2021-10-01'
      - name: until
        in: query
        required: false
        description: Upper bound on the datestamp.
        schema:
          type: string
        example: '2021-12-31'
      - name: resumptionToken
        in: query
        required: false
        description: Continuation token for a paged list. The Archives Portal caps ListRecords at 100 records per page and returns a token carrying completeListSize and cursor. When resuming, send metadataPrefix and the token only — set/from/until must be omitted.
        schema:
          type: string
      responses:
        '200':
          description: An OAI-PMH 2.0 envelope. Also carries protocol-level errors (badVerb, badArgument, cannotDisseminateFormat, idDoesNotExist, noRecordsMatch, noSetHierarchy, badResumptionToken) inside the body.
          content:
            text/xml:
              schema:
                type: string
                description: OAI-PMH 2.0 XML, http://www.openarchives.org/OAI/2.0/
              examples:
                identifyRepository:
                  summary: Repository Identify, captured live 2026-08-19
                  externalValue: ../examples/university-of-tokyo-repository-oai-identify.xml
                listMetadataFormatsRepository:
                  summary: Repository ListMetadataFormats, captured live 2026-08-19
                  externalValue: ../examples/university-of-tokyo-repository-oai-listmetadataformats.xml
                identifyArchives:
                  summary: Archives Portal Identify, captured live 2026-08-19
                  externalValue: ../examples/university-of-tokyo-archives-oai-identify.xml
                listMetadataFormatsArchives:
                  summary: Archives Portal ListMetadataFormats, captured live 2026-08-19
                  externalValue: ../examples/university-of-tokyo-archives-oai-listmetadataformats.xml
        '406':
          description: Returned by repository.dl.itc.u-tokyo.ac.jp (nginx) when the request carries a desktop-browser User-Agent. Retry without one.
          content:
            text/html:
              schema:
                type: string
externalDocs:
  description: API documentation for the Archives Portal (Japanese only)
  url: https://da.dl.itc.u-tokyo.ac.jp/portal/help/api
x-operator: institution
x-operator-evidence: Both hosts are under u-tokyo.ac.jp. Both Identify responses name the University of Tokyo as the repository and give a lib.u-tokyo.ac.jp admin contact. No vendor host is involved.
x-provenance:
  generated: '2026-08-19'
  method: probed
  source:
  - https://repository.dl.itc.u-tokyo.ac.jp/oai?verb=Identify
  - https://repository.dl.itc.u-tokyo.ac.jp/oai?verb=ListMetadataFormats
  - https://repository.dl.itc.u-tokyo.ac.jp/oai?verb=ListSets
  - https://da.dl.itc.u-tokyo.ac.jp/portal/oai?verb=Identify
  - https://da.dl.itc.u-tokyo.ac.jp/portal/oai?verb=ListMetadataFormats
  - https://da.dl.itc.u-tokyo.ac.jp/portal/oai?verb=ListSets
  - https://da.dl.itc.u-tokyo.ac.jp/portal/help/api