Digitised Objects Repository Search and Data API

openapi: 3.0.0
x-provenance:
  method: searched
  generated: '2026-08-30'
  source: https://api-dor.ncl.ac.uk/info/open-api
  x-operator: institution
  operator_evidence: api-dor.ncl.ac.uk resolves to dls-dor01.ncl.ac.uk (128.240.212.10), inside Newcastle University's
    own network and under the university's own registrable domain ncl.ac.uk. info.title names Newcastle University,
    the description names Newcastle University Library Special Collections and Digital Library Services. No vendor
    identity appears in servers[], info.title, info.contact or info.termsOfService.
  note: First-party OpenAPI published by the API itself. Saved unmodified in openapi/_original/newcastle-digitised-objects-repository.json;
    this copy adds only x-provenance and an info.contact assembled from the description.
info:
  title: Newcastle University | Digitised Objects Repository | Search and Data API
  version: 1.27.0
  description: 'The *Search and Data API* provides a single point of truth interface for searching, browsing and
    displaying digitised objects held in Newcastle University Library''s Special Collections.


    Data curators: [Special Collections and Archives](https://www.ncl.ac.uk/library/special-collections/)\

    Administrators: [Digital Library Services](https://go.ncl.ac.uk/dls)

    '
  contact:
    name: Digital Library Services, Newcastle University
    url: https://go.ncl.ac.uk/dls
servers:
- url: https://api-dor.ncl.ac.uk
tags:
- name: API Metadata Information
  description: A set of endpoints for gathering information about the API itself. They can be used for validation,
    creating types or checking if the service is live.
- name: V1
  description: A set of endpoints created as as part of the version one of the application.
- name: Collections
  description: A set of endpoints describing the collections present in the repository.
- name: Digitised Objects
  description: A set of endpoints describing the digitised objects present in the repository.
- name: Items
  description: A set of endpoints describing the integrants of the given digitised object present in the repository.
- name: CONTENTdm
  description: A set of endpoints used for describing digitised objects stored in the repository, as well as all
    the complementary resources created based on them.
- name: IIIF
  description: A set of endpoints signposting to [International Image Interoperability Framework](https://iiif.io/)
    services responsible for handling the presentation of the digitised objects.
- name: TEI
  description: A set of endpoints providing metadata and content definitions of documents encoded using [Text Encoding
    Initiative](https://tei-c.org/) guidance.
- name: Index
  description: A set of endpoints returning an index of all the resources present in the repository.
- name: Search
  description: A set of endpoints returning endpoints for searching resources present in the repository.
- name: Autocomplete
  description: A set of endpoints returning endpoints for autocompleting search queries.
- name: Transcript
  description: A set of endpoints returning transcript of the resources present in the repository.
paths:
  /:
    get:
      operationId: getHome
      summary: The API's home page
      description: Returns an OpenAPI interactive documentation for devices requesting HTML, or starting HATEAOS
        links for JSON requests.
      tags:
      - API Metadata Information
      responses:
        '200':
          description: The API's starting point.
          content:
            text/html:
              schema:
                type: string
                description: An OpenAPI interactive documentation
            application/json:
              schema:
                type: object
                properties:
                  _links:
                    type: object
                    properties:
                      info:
                        $ref: '#/components/schemas/HateoasLink'
                      collections:
                        $ref: '#/components/schemas/HateoasLink'
                      digitisedObjects:
                        $ref: '#/components/schemas/HateoasLink'
                      items:
                        $ref: '#/components/schemas/HateoasLink'
                    required:
                    - specification
                required:
                - _links
        5XX:
          description: Indicates that the server encountered an unexpected exception preventing it from fulfilling
            the request.
  /info:
    get:
      operationId: getInfo
      summary: The API's information
      description: Returns a basic set of information describing the state of the API and its current version.
      tags:
      - API Metadata Information
      responses:
        '200':
          description: The metadata object describing the basic information about the API.
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    $ref: '#/components/schemas/Version'
                  build:
                    $ref: '#/components/schemas/Version'
                  baseUrl:
                    type: string
                    example: https://api.dor.ncl.ac.uk
                  _links:
                    type: object
                    allOf:
                    - $ref: '#/components/schemas/HomeLinks'
                    - type: object
                      properties:
                        specification:
                          $ref: '#/components/schemas/HateoasLink'
                      required:
                      - specification
                required:
                - version
                - build
                - baseUrl
                - _links
        5XX:
          description: Indicates that the server encountered an unexpected exception preventing it from fulfilling
            the request.
  /info/open-api:
    get:
      operationId: getInfoOpenAPI
      summary: The OpenAPI specification
      description: Presents the current OpenAPI document specification that the API service pledge to implement.
      tags:
      - API Metadata Information
      responses:
        '200':
          description: A JSON object representing the API's OpenAPI schema.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                example: '{ "openapi": "3.0.0 (...)" }'
        5XX:
          description: Indicates that the server encountered an unexpected exception preventing it from fulfilling
            the request.
  /iiif/{id}:
    get:
      operationId: getIIIF
      summary: IIIF permalink
      description: Signpost to to a service responsible for IIIF manifests generation for the given digitised object.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        example: UkLWZg9D
        required: true
        description: Digitised object's identifier.
      tags:
      - Digitised Objects
      - IIIF
      responses:
        '302':
          description: Redirects to a IIIF manifest.
          headers:
            Location:
              description: URL where the IIIF manifest will be created.
              schema:
                type: string
                format: uri
              required: true
        '400':
          description: The server could not finalise the response due to the malformed, invalid or missing request
            parameters.
        '404':
          description: A digitised object with the specified ID was not found.
        5XX:
          description: Indicates that the server encountered an unexpected exception preventing it from fulfilling
            the request.
  /v1/collections:
    get:
      operationId: getV1CollectionsIndex
      summary: List of collections
      description: Returns summary of collections present in the system.
      tags:
      - V1
      - Collections
      - Index
      parameters:
      - in: query
        name: page
        schema:
          type: number
        description: The pagination index, starting from 1 for the first page.
      - in: query
        name: page.size
        schema:
          type: number
        description: The number of collections matching returned per page, between 1 and 100.
      - in: query
        name: page.start
        schema:
          type: number
        description: The pagination starting offset starting from 0.
      responses:
        '200':
          description: The list of collections matching a query.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ngQRYFju
                        title:
                          type: string
                          example: Newcastle University Archives
                          nullable: true
                        _links:
                          type: object
                          properties:
                            definition:
                              $ref: '#/components/schemas/HateoasLink'
                          required:
                          - definition
                      required:
                      - id
                      - title
                      - _links
                    nullable: true
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  _links:
                    allOf:
                    - $ref: '#/components/schemas/HomeLinks'
                required:
                - items
                - pagination
                - _links
        '400':
          description: The server could not finalise the response due to the malformed, invalid or missing request
            parameters.
        5XX:
          description: Indicates that the server encountered an unexpected exception preventing it from fulfilling
            the request.
  /v1/collections/{id}:
    get:
      operationId: getV1CollectionsShow
      summary: Collection definition
      description: Returns all the metadata and signposts to the related resources for the given collection.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        example: ngQRYFju
        required: true
        description: Collection's identifier.
      tags:
      - V1
      - Collections
      responses:
        '200':
          description: The complete definition of the identified collection.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: ngQRYFju
                  title:
                    type: string
                    example: Newcastle University Archives
                    nullable: true
                  digitisedObjects:
                    type: object
                    properties:
                      totalElements:
                        type: number
                      _links:
                        type: object
                        properties:
                          search:
                            $ref: '#/components/schemas/HateoasLink'
                        required:
                        - search
                    required:
                    - totalElements
                    - _links
                  items:
                    type: object
                    properties:
                      totalElements:
                        type: number
                      _links:
                        type: object
                        properties:
                          search:
                            $ref: '#/components/schemas/HateoasLink'
                        required:
                        - search
                    required:
                    - totalElements
                    - _links
                  _links:
                    type: object
                    properties:
                      index:
                        $ref: '#/components/schemas/HateoasLink'
                    required:
                    - index
                required:
                - id
                - title
                - digitisedObjects
                - items
                - _links
        '400':
          description: The server could not finalise the response due to the malformed, invalid or missing request
            parameters.
        '404':
          description: A collection with the specified ID was not found.
        5XX:
          description: Indicates that the server encountered an unexpected exception preventing it from fulfilling
            the request.
  /v1/digitised-objects:
    get:
      operationId: getV1DigitisedObjectsIndex
      summary: List of digitised objects
      description: Returns summary of digitised objects present in the system.
      tags:
      - V1
      - Digitised Objects
      - Index
      parameters:
      - in: query
        name: page
        schema:
          type: number
        description: The pagination index, starting from 1 for the first page.
      - in: query
        name: page.size
        schema:
          type: number
        description: The number of digitised objects matching returned per page, between 1 and 100.
      - in: query
        name: page.start
        schema:
          type: number
        description: The pagination starting offset starting from 0.
      responses:
        '200':
          description: The list of digitised objects matching a query.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: UkLWZg9D
                        refCode:
                          type: string
                          example: NUA/005671/01
                          nullable: true
                        title:
                          type: string
                          example: Aerial view of King's College
                          nullable: true
                        description:
                          type: string
                          nullable: true
                        _links:
                          type: object
                          properties:
                            definition:
                              $ref: '#/components/schemas/HateoasLink'
                          required:
                          - definition
                      required:
                      - id
                      - refCode
                      - title
                      - description
                      - _links
                      nullable: true
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  _links:
                    allOf:
                    - $ref: '#/components/schemas/HomeLinks'
                    - type: object
                      properties:
                        search:
                          $ref: '#/components/schemas/HateoasLink'
                      required:
                      - search
                required:
                - items
                - pagination
                - _links
        '400':
          description: The server could not finalise the response due to the malformed, invalid or missing request
            parameters.
        5XX:
          description: Indicates that the server encountered an unexpected exception preventing it from fulfilling
            the request.
  /v1/digitised-objects/search:
    get:
      operationId: getV1DigitisedObjectsSearch
      summary: Search digitised objects
      description: Performs a keyword search with filters on the digitised objects present in the system.
      tags:
      - V1
      - Digitised Objects
      - Search
      parameters:
      - $ref: '#/components/parameters/SearchPage'
      - $ref: '#/components/parameters/SearchPageSize'
      - $ref: '#/components/parameters/SearchPageStart'
      - $ref: '#/components/parameters/SearchQ'
      - $ref: '#/components/parameters/SearchQAdvanced'
      - $ref: '#/components/parameters/SearchSort'
      - $ref: '#/components/parameters/SearchFilterCollection'
      - $ref: '#/components/parameters/SearchFilterCollectionId'
      - $ref: '#/components/parameters/SearchFilterSubject'
      - $ref: '#/components/parameters/SearchFilterThematicCategory'
      - $ref: '#/components/parameters/SearchFilterDateFrom'
      - $ref: '#/components/parameters/SearchFilterDateTo'
      - $ref: '#/components/parameters/SearchFilterHasTEI'
      - $ref: '#/components/parameters/SearchFilterHasTranscript'
      - $ref: '#/components/parameters/SearchFilterScope'
      responses:
        '200':
          description: The list of items matching the given search query.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: UkLWZg9D
                        refCode:
                          type: string
                          example: NUA/028944/02
                          nullable: true
                        title:
                          type: string
                          example: Aerial view of main University campus and Newcastle city centre
                          nullable: true
                        description:
                          type: string
                          example: Aerial view of university campus from the west including the Armstrong Building,
                            Bedson Building, King George VI Building and Agriculture Building
                          nullable: true
                        format:
                          type: string
                          example: Photograph
                          nullable: true
                        language:
                          type: string
                          nullable: true
                        creators:
                          type: array
                          items:
                            type: string
                          nullable: true
                        subjects:
                          type: array
                          items:
                            type: string
                          nullable: true
                        dates:
                          type: array
                          items:
                            type: string
                          nullable: true
                        places:
                          type: array
                          items:
                            type: string
                          nullable: true
                        canvas:
                          type: string
                        highlights:
                          type: object
                          description: The list of all matches for the given query per searched field.
                          properties:
                            title:
                              type: array
                              items:
                                type: string
                            description:
                              type: array
                              items:
                                type: string
                            content:
                              type: array
                              items:
                                type: string
                          required:
                          - title
                          - description
                          - content
                        _links:
                          type: object
                          properties:
                            definition:
                              $ref: '#/components/schemas/HateoasLink'
                          required:
                          - definition
                      required:
                      - id
                      - refCode
                      - title
                      - description
                      - format
                      - language
                      - creators
                      - subjects
                      - dates
                      - places
                      - canvas
                      - highlights
                      - _links
                    nullable: true
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  sort:
                    $ref: '#/components/schemas/Sort'
                  query:
                    $ref: '#/components/schemas/CancellableQuery'
                  filters:
                    $ref: '#/components/schemas/Filters'
                  _links:
                    allOf:
                    - $ref: '#/components/schemas/HomeLinks'
                    - type: object
                      properties:
                        index:
                          $ref: '#/components/schemas/HateoasLink'
                        home:
                          $ref: '#/components/schemas/HateoasLink'
                      required:
                      - index
                      - home
                required:
                - items
                - pagination
                - sort
                - query
                - filters
                - _links
        '400':
          description: The server could not finalise the response due to the malformed, invalid or missing request
            parameters.
        '404':
          description: Digitised objects matching the given criteria were not found.
        5XX:
          description: Indicates that the server encountered an unexpected exception preventing it from fulfilling
            the request.
  /v1/digitised-objects/search/autocomplete:
    get:
      operationId: getV1DigitisedObjectsSearchAutocomplete
      summary: Search digitised objects autocompletion
      description: Provides search box autocompletion for the given phrase.
      tags:
      - V1
      - Digitised Objects
      - Search
      - Autocomplete
      parameters:
      - $ref: '#/components/parameters/AutocompleteQ'
      - $ref: '#/components/parameters/AutocompletePageSize'
      - $ref: '#/components/parameters/SearchFilterScope'
      responses:
        '200':
          description: The list of terms/phrases matching the given query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompleteResponse'
        '400':
          description: The server could not finalise the response due to the malformed, invalid or missing request
            parameters.
        '404':
          description: No suggestions were available for the given query.
        5XX:
          description: Indicates that the server encountered an unexpected exception preventing it from fulfilling
            the request.
  /v1/digitised-objects/{id}:
    get:
      operationId: getV1DigitisedObjectsShow
      summary: Digitised object definition
      description: Returns all the metadata and signposts to the related resources for the given digitised object.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        example: UkLWZg9D
        required: true
        description: Digitised object's identifier.
      tags:
      - V1
      - Digitised Objects
      responses:
        '200':
          description: The complete definition of the identified digitised object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: UkLWZg9D
                  refCode:
                    type: string
                    example: NUA/005671/01
                    nullable: true
                  title:
                    type: string
                    example: Aerial view of King's College
                    nullable: true
                  description:
                    type: string
                    nullable: true
                  format:
                    type: string
                    example: Photograph
                    nullable: true
                  language:
                    type: string
                    nullable: true
                  creators:
                    type: array
                    items:
                      type: string
                    nullable: true
                  subjects:
                    type: array
                    items:
                      type: string
                    nullable: true
                  dates:
                    type: array
                    items:
                      type: string
                    nullable: true
                  places:
                    type: array
                    items:
                      type: string
                    nullable: true
                  publishers:
                    type: array
                    items:
                      type: string
                    nullable: true
                  provenances:
                    type: array
                    items:
                      type: string
                    nullable: true
                  contributors:
                    type: array
                    items:
                      type: string
                    nullable: true
                  copyright:
                    type: string
                    nullable: true
                  license:
                    type: string
                    nullable: true
                  manifest:
                    type: string
                  collection:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ngQRYFju
                      title:
                        type: string
                        example: Newcastle University Archives
                        nullable: true
                      _links:
                        type: object
                        properties:
                          definition:
                            $ref: '#/components/schemas/HateoasLink'
                        required:
                        - definition
                    required:
                    - id
                    - title
                    - _links
                  items:
                    type: object
                    properties:
                      totalElements:
                        type: number
                      _links:
                        type: object
                        properties:
                          search:
                            $ref: '#/components/schemas/HateoasLink'
                        required:
                        - search
                    required:
                    - totalElements
                    - _links
                  transcript:
                    type: object
                    properties:
                      _links:
                        type: object
                        properties:
                          content:
                            $ref: '#/components/schemas/HateoasLink'
                        required:
                        - content
                    required:
                    - _links
                    nullable: true
                  teis:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: UkLWZg9D
                        type:
                          type: string
                          enum:
                          - primary
                          nullable: true
                        _links:
                          type: object
                          properties:
                            content:
                              $ref: '#/components/schemas/HateoasLink'
                          required:
                          - content
                      required:
                      - id
                      - type
                      - _links
                    nullable: true
                  createdAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
                    nullable: true
                  _links:
                    type: object
                    properties:
                      index:
                        $ref: '#/components/schemas/HateoasLink'
                      search:
                        $ref: '#/components/schemas/HateoasLink'
                    required:
                    - index
                    - search
                required:
                - id
                - refCode
                - title
                - description
                - format
                - language
                - creators
                - subjects
                - dates
                - places
                - publishers
                - provenances
                - contributors
                - copyright
                - license
                - manifest
                - collection
                - items
                - transcript
                - teis
                - createdAt
                - updatedAt
                - _links
        '400':
          description: The server could not finalise the response due to the malformed, invalid or missing request
            parameters.
        '404':
          description: A digitised object with the specified ID was not found.
        5XX:
          description: Indicates that the server encountered an unexpected exception preventing it from fulfilling
            the request.
  /v1/digitised-objects/{id}/transcript/content:
    get:
      operationId: getV1DigitisedObjectsTranscriptContent
      summary: Digitised object's transcript
      description: Returns a transcript of the given digitised object.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        example: UkLWZg9D
        required: true
        description: Digitised object's identifier.
      tags:
      - V1
      - Digitised Objects
      - Transcript
      responses:
        '200':
          description: The transcript of the digitised object in a plain text form.
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: The server could not finalise the response due to the malformed, invalid or missing request
            parameters.
        '404':
          description: A digitised object with the specified ID or its transcript was not found.
        5XX:
          description: Indicates that the server encountered an unexpected exception preventing it from fulfilling
            the request.
  /v1/items:
    get:
      operationId: getV1ItemsIndex
      summary: List of items
      description: Returns summary of items present in the system.
      tags:
      - V1
      - Items
      - Index
      parameters:
      - in: query
        name: page
        schema:
          type: number
        description: The pagination index, starting from 1 for the first page.
      - in: query
        name: page.size
        schema:
          type: number
        description: The number of items matching returned per page, between 1 and 100.
      - in: query
        name: page.start
        schema:
          type: number
        description: The pagination starting offset starting from 0.
      responses:
   

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/newcastle/refs/heads/main/openapi/newcastle-digitised-objects-api-openapi.yml