openapi: 3.2.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).
  contact:
    name: University of York Digital Collections
    url: https://discover.york.ac.uk/about/
  license:
    name: Not stated by the operator
servers:
- url: https://discover.york.ac.uk
  description: University of York Digital Collections (production)
security: []
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:
  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
  parameters:
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    Q:
      name: q
      in: query
      required: false
      schema:
        type: string
    Collection:
      name: collection
      in: query
      required: false
      schema:
        type: string
    Size:
      name: size
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 12
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