University of York Digital Collections Search API

# authorship: generated by API Evangelist from live probes of the operator's own endpoints.
# The document is ours; the facts in it were measured, not claimed. `method: probed` below
# records HOW it was obtained; this header records WHO wrote it. An unmarked artifact would
# be credited to the institution as though they published it, and they did not.
openapi: 3.1.0
info:
  title: University of York Digital Collections Search API
  version: '1.0'
  summary: Keyless JSON search over the University of York's digitised archive, library and cultural-heritage collections.
  description: >-
    The search interface behind discover.york.ac.uk — "Digital Collections | University of York" —
    operated by the University of York on its own registrable domain (york.ac.uk). It is a keyless,
    CORS-open JSON API in front of an Elasticsearch index (`discover-index`) holding 415,165
    documents at the time of profiling, drawn from the University Library, the Borthwick Institute
    for Archives and cultural-heritage partners.

    This description was written from LIVE PROBES of the deployed endpoints on 2026-08-30, and from
    the request construction in the site's own published JavaScript bundle
    (component---src-pages-search-tsx-*.js, `fetch(s + "/api/search-simple?" + l)` where
    `s = "https://discover.york.ac.uk"`). The University of York publishes no OpenAPI, no developer
    portal and no written documentation for this API; every field below is observed, not claimed.
    Nothing has been invented. The response envelope is Elasticsearch's own and is reproduced as
    observed rather than idealised.

    OPERATOR: institution. Host discover.york.ac.uk is under york.ac.uk. The infrastructure is AWS
    (API Gateway behind CloudFront), which is a hosting choice, not a vendor contract — the API
    shape, the index, the field names and the collections are the University's.
  contact:
    name: University of York Digital Collections
    url: https://discover.york.ac.uk/about/
  license:
    name: Not stated by the operator
x-operator: institution
x-provenance:
  method: probed
  generated: '2026-08-30'
  source:
    - https://discover.york.ac.uk/api/search-simple?q=york&page=1&size=2
    - https://discover.york.ac.uk/api/search?q=york&size=2
    - https://discover.york.ac.uk/component---src-pages-search-tsx-329ff92266237191ff27.js
servers:
  - url: https://discover.york.ac.uk
    description: University of York Digital Collections (production)
tags:
  - name: Search
    description: Full-text and faceted search over the digital collections index.
paths:
  /api/search-simple:
    get:
      summary: Search the digital collections index
      description: >-
        The endpoint the public search page calls. Returns an Elasticsearch response envelope with
        `hits` and `aggregations`. All parameters are optional; calling with no parameters returns
        an unfiltered page over the whole index (415,165 documents observed).
      operationId: searchSimple
      tags: [Search]
      security: []
      parameters:
        - name: q
          in: query
          required: false
          description: Free-text query. Sent as an empty string by the site when the user has typed nothing.
          schema: { type: string }
          example: york
        - name: page
          in: query
          required: false
          description: 1-based page number. The site defaults to 1.
          schema: { type: integer, minimum: 1, default: 1 }
        - name: size
          in: query
          required: false
          description: Hits per page. The site defaults to 12.
          schema: { type: integer, minimum: 0, default: 12 }
        - name: collection
          in: query
          required: false
          description: >-
            Comma-separated collection slugs to restrict the query to. The site splits the value on
            commas and trims each entry.
          schema: { type: string }
          example: uoy-photographs
      responses:
        '200':
          description: Elasticsearch search response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: >-
            Malformed parameter. Observed with `size=abc`, which returns
            `{"error":"parsing_exception: [parsing_exception] Reason: Unknown key for a VALUE_NULL in [size]."}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/search:
    get:
      summary: Search the digital collections index (extended aggregations)
      description: >-
        A second live search endpoint on the same index, returning the same envelope with a
        different aggregation set (`aggs_main_collection_name` in place of
        `aggs_main_collection_title`). It is not called by the public search page; it answers the
        same parameters and was confirmed live.
      operationId: search
      tags: [Search]
      security: []
      parameters:
        - { $ref: '#/components/parameters/Q' }
        - { $ref: '#/components/parameters/Page' }
        - { $ref: '#/components/parameters/Size' }
        - { $ref: '#/components/parameters/Collection' }
      responses:
        '200':
          description: Elasticsearch search response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Malformed parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes: {}
  parameters:
    Q:
      name: q
      in: query
      required: false
      schema: { type: string }
    Page:
      name: page
      in: query
      required: false
      schema: { type: integer, minimum: 1, default: 1 }
    Size:
      name: size
      in: query
      required: false
      schema: { type: integer, minimum: 0, default: 12 }
    Collection:
      name: collection
      in: query
      required: false
      schema: { type: string }
  schemas:
    Error:
      type: object
      description: Error body observed on HTTP 400.
      properties:
        error:
          type: string
          example: 'parsing_exception: [parsing_exception] Reason: Unknown key for a VALUE_NULL in [size].'
    SearchResponse:
      type: object
      description: Elasticsearch search response envelope, reproduced as returned.
      properties:
        took: { type: integer, description: Query time in milliseconds. }
        timed_out: { type: boolean }
        _shards:
          type: object
          properties:
            total: { type: integer }
            successful: { type: integer }
            skipped: { type: integer }
            failed: { type: integer }
        hits:
          type: object
          properties:
            total:
              type: object
              properties:
                value: { type: integer, example: 415165 }
                relation: { type: string, example: eq }
            max_score:
              type: [number, 'null']
            hits:
              type: array
              items: { $ref: '#/components/schemas/Hit' }
        aggregations:
          type: object
          description: >-
            Terms aggregations. /api/search-simple returns aggs_type, aggs_main_collection_title,
            aggs_work_type and aggs_creator; /api/search returns aggs_type, aggs_work_type,
            aggs_creator and aggs_main_collection_name.
          additionalProperties: { $ref: '#/components/schemas/Aggregation' }
    Aggregation:
      type: object
      properties:
        doc_count_error_upper_bound: { type: integer }
        sum_other_doc_count: { type: integer }
        buckets:
          type: array
          items:
            type: object
            properties:
              key: { type: string, example: item }
              doc_count: { type: integer, example: 87571 }
    Hit:
      type: object
      properties:
        _index: { type: string, example: discover-index }
        _id: { type: string, example: 'ark:/36941/806938/objects/17061' }
        _score:
          type: [number, 'null']
        _source: { $ref: '#/components/schemas/CollectionItem' }
    CollectionItem:
      type: object
      description: >-
        One indexed digital-collections record. `id` is an ARK-based identifier under the
        University of York's NAAN 36941, which is also the IIIF Image API identifier.
      properties:
        id: { type: string, example: 'ark:/36941/806938/objects/17061' }
        title: { type: string }
        label: { type: string }
        summary: { type: string }
        creator: { type: string }
        date: { type: string }
        date_range:
          type: object
          properties:
            gte: { type: string, format: date }
            lte: { type: string, format: date }
        subjects:
          oneOf:
            - { type: string }
            - { type: array, items: { type: string } }
        rights: { type: string }
        type: { type: string, description: 'Observed values: item, manifest.' }
        work_type: { type: string }
        parent_collection_id: { type: string }
        parent_collection_label: { type: string }
        borthwick_catalogue_reference_code:
          type: array
          items: { type: string }
          description: Reference code in the Borthwick Institute for Archives catalogue.
        ui_redirect_link: { type: string, description: Site-relative link to the viewer for this item. }
        ui_main_collection_title: { type: string }
        ui_external_image_url: { type: string }
        aggs_parent_id:
          type: string
          description: IIIF Presentation 3 manifest URI of the parent object.
          example: 'ark:/36941/796351/presentation/3/manifest'
        aggs_main_collection_title: { type: string }
        aggs_main_collection_name: { type: string }
        aggs_parent_title: { type: string }
        aggs_creator: { type: string }
        aggs_date: { type: string }
        aggs_label: { type: string }
        aggs_subjects: { type: string }
        aggs_rights: { type: string }
        aggs_type: { type: string }
        aggs_work_type: { type: string }
        aggs_cp_court: { type: string, description: 'Cause Papers facet (York Cause Papers collection).' }
        aggs_cp_case: { type: string }
        aggs_cp_details: { type: string }
        aggs_cp_outcome: { type: string }
        aggs_cp_date: { type: string }
        aggs_cp_abstract: { type: string }
        aggs_cp_parties_mentioned: { type: string }
        aggs_cp_other_individuals: { type: string }
        aggs_cp_witnesses: { type: string }
        aggs_cp_places: { type: string }
        aggs_ar_type: { type: string, description: 'Archival-record facet.' }
        aggs_ar_section: { type: string }
        aggs_ar_summary: { type: string }
        aggs_ar_language: { type: string }
        aggs_ar_subjects: { type: string }
        aggs_ar_people: { type: string }
        aggs_ar_places: { type: string }
        aggs_ar_groups: { type: string }
        aggs_ar_dates: { type: string }
        aggs_ar_referenced_by: { type: string }
security: []