OAI-PMH Harvester Guide

The Union Catalog exposes one OAI-PMH endpoint:

The endpoint implements OAI-PMH version 2.0. It supports all six protocol verbs and accepts GET and POST requests. Responses are XML, as the protocol requires. ListMetadataFormats reports the available metadata formats.

An aggregator of source repositories

The catalog is an aggregator. It harvests records from participating source repositories and re-disseminates them from this one endpoint. The protocol's aggregator guidelines say how such a service should identify and attribute the records it passes along. The catalog follows them in three visible ways.

• Identifiers. Each record is re-identified under the catalog's namespace as oai:union.ndltd.org:repo:<repo>:<upstream-identifier>. This unique identifier names the source repository and preserves the identifier the record carries there.
• Sets. Each source repository is exposed as a set named repo:<repo>, alongside any setSpecs the source itself published, so one repository's records can be harvested selectively.
• Provenance. Each record carries a provenance container in its <about> section, recording the source repository's base URL and the record's identifier and datestamp there.

Protocol requests

These links run the six verbs against the live endpoint. ListIdentifiers and ListRecords require a metadataPrefix. GetRecord also requires an identifier, so its bare link below returns the protocol's badArgument response.

Selective and incremental harvesting

ListRecords and ListIdentifiers support the protocol's selective harvesting arguments. They accept a set argument and from/until datestamps at second granularity (YYYY-MM-DDThh:mm:ssZ). A record's datestamp is the time the catalog's copy of it last changed. Passing the previous harvest time as from collects only records added, updated, or deleted since then.

http://union.dev.ndltd.org/oai-pmh/?verb=ListRecords&metadataPrefix=oai_dc&set=repo:vt
http://union.dev.ndltd.org/oai-pmh/?verb=ListRecords&metadataPrefix=oai_dc&from=2026-01-01T00:00:00Z

Flow control

List responses return up to 100 records per page and carry a resumptionToken. Tokens are stateless and signed. A harvest can pause and resume at any point before the token's expirationDate, about an hour after issue. The first page reports completeListSize, and every page reports a cursor. If a token expires, the harvester reissues the original list request.

Deleted records

The catalog declares deletedRecord=persistent. When a source repository deletes a record, the catalog keeps a tombstone, a header with status="deleted" and no metadata. Tombstones remain visible so downstream harvesters can propagate removals.

Dissemination

The endpoint serves the records the catalog has classified as theses or dissertations. Deletion tombstones are always disseminated so removals propagate. Participating institutions retain control over their full-text content. The catalog aggregates descriptive metadata for discovery.

The API reference documents the catalog's other machine interfaces, including the search API, item metadata, MCP, RSS, and sitemaps. See the Terms of Service.