API Documentation

The union catalog is built to be read by machines as well as people. This page documents every machine interface the service exposes: metadata harvesting over OAI-PMH, a JSON search API, per-item metadata in JSON and JSON-LD, an MCP endpoint for AI assistants, an RSS feed of recent additions, and sitemaps for crawlers. All interfaces are read-only and require no registration or API key.

Two hosts serve these interfaces. The union catalog host (http://union.dev.ndltd.org) carries the OAI-PMH provider and the RSS feed; the search host (https://search.dev.ndltd.org) carries the search API, item pages, the MCP endpoint, and sitemaps. Examples below use these hosts directly and work as written. For the harvesting endpoint in depth, see the OAI-PMH harvester guide.

OAI-PMH provider

The provider re-disseminates harvested records in oai_dc and supports all six protocol verbs. Records the catalog has classified as theses or dissertations are disseminated; deletion tombstones remain visible so downstream harvesters can propagate removals.

http://union.dev.ndltd.org/oai-pmh/?verb=Identify
http://union.dev.ndltd.org/oai-pmh/?verb=ListRecords&metadataPrefix=oai_dc
http://union.dev.ndltd.org/oai-pmh/?verb=ListRecords&metadataPrefix=oai_dc&set=repo:vt
http://union.dev.ndltd.org/oai-pmh/?verb=GetRecord&metadataPrefix=oai_dc&identifier=oai:union.ndltd.org:repo:vt:oai:vtechworks.lib.vt.edu:10919/12345

Identifiers follow the oai-identifier scheme oai:union.ndltd.org:repo:<repo>:<upstream-identifier>, so every record names its source repository and the identifier it carries there. Each source repository is exposed as a set (repo:<repo>) alongside any setSpecs the source itself published. Resumption tokens are stateless and may be resumed at any time; list responses report completeListSize on the first page.

Search API

GET https://search.dev.ndltd.org/api/search answers metadata queries with JSON. The q parameter searches titles, abstracts, creators, institutions, and subjects; the remaining parameters narrow the result set.

curl "https://search.dev.ndltd.org/api/search?q=machine+learning&degree_level=doctoral&page_size=5"

Responses carry total, page, page_size, items (each with title, creators, institution, and an item_url), and — on the Solr backend — facets.

Item metadata (JSON and JSON-LD)

Every public record has an item page at https://search.dev.ndltd.org/etd/<repo>/<oai-identifier>. The same URL serves three representations, selected by the Accept header or a format query parameter (html, json, jsonld). The JSON representation carries the record's descriptive fields plus each individual metadata statement with its source attribution; the JSON-LD representation is schema.org-typed for linked-data consumers.

curl -H "Accept: application/json"    "https://search.dev.ndltd.org/etd/vt/oai:vtechworks.lib.vt.edu:10919/12345"
curl -H "Accept: application/ld+json" "https://search.dev.ndltd.org/etd/vt/oai:vtechworks.lib.vt.edu:10919/12345"

MCP endpoint for AI assistants

AI assistants that speak the Model Context Protocol can query the catalog natively. The server is stateless, read-only, and speaks the streamable HTTP transport at POST https://search.dev.ndltd.org/mcp. It exposes three tools: search_etds, get_etd, and list_repositories. Point any MCP-capable client at the URL — no authentication is required. A raw handshake looks like this:

curl -X POST https://search.dev.ndltd.org/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

RSS feed

http://union.dev.ndltd.org/rss/ lists the most recently added public records, newest first, with links to their item pages. Feed readers and monitoring tools can poll it without limits beyond ordinary politeness.

Sitemaps

Crawlers should start from https://search.dev.ndltd.org/sitemap.xml, which indexes paged sitemaps of all public item URLs with last-modified dates.

Terms of Service

See the catalog's Terms of Service.