openapi: 3.1.0
info:
  version: v3
  title: IIIF APIs
  description: >-
    You can access our images using standard International Image
    Interoperability Framework (IIIF) APIs. This is how to get the images of
    digitised works that you’ve found using the Catalogue API. Right now, only
    our open image collections are available and we support the IIIF Image API.
    We are working to add the IIIF Presentation, Search and Authentication APIs
    across all of our digitised collections.
  contact: {}
servers:
  - url: https://iiif.wellcomecollection.org
tags:
  - name: IIIF Image API
    description: >-
      The Image API allows for interoperable delivery of digital images. Simply,
      the API allows for constructing parameterized URIs for getting a
      particular region and/or size of an image. This ability to get regions and
      sizes of the image is what supports delivering thumbnails as well as deep
      zoom viewing. The image API also specifies a way to get information about
      the image and what image derivatives and image manipulation features are
      supported for that image.
  - name: IIIF Presentation API
    description: The IIIF Search API allows for searching within a digitised item.
  - name: IIIF Content Search API
    description: The IIIF Search API allows for searching within a digitised item.
  - name: Image
    description: <SchemaDefinition schemaRef="#/components/schemas/Image" />
x-tagGroups:
  - name: APIs
    tags:
      - IIIF Image API
      - IIIF Search API
  - name: Models
    tags:
      - Image
paths:
  /image/{identifier}/{region}/{size}/{rotation}/{quality}.{format}:
    get:
      summary: Image
      description: Request an image, which may be part of a larger image.
      tags:
        - IIIF Image API
      responses:
        '200':
          description: ''
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
                description: Requested image
            image/png:
              schema:
                type: string
                format: binary
                description: Requested image
            image/gif:
              schema:
                type: string
                format: binary
                description: Requested image
            image/webp:
              schema:
                type: string
                format: binary
                description: Requested image
        '400':
          description: ''
          content:
            image/jpeg:
              schema:
                type: string
                default: >-
                  The server cannot fulfill the request, as the syntax of the
                  request issued by the client is incorrect.
                description: Error message
            image/png:
              schema:
                type: string
                default: >-
                  The server cannot fulfill the request, as the syntax of the
                  request issued by the client is incorrect.
                description: Error message
            image/gif:
              schema:
                type: string
                default: >-
                  The server cannot fulfill the request, as the syntax of the
                  request issued by the client is incorrect.
                description: Error message
            image/webp:
              schema:
                type: string
                default: >-
                  The server cannot fulfill the request, as the syntax of the
                  request issued by the client is incorrect.
                description: Error message
        '404':
          description: ''
          content:
            image/jpeg:
              schema:
                type: string
                default: >-
                  The image resource specified by identifier does not exist, the
                  value of one or more of the parameters is not supported for
                  this image, or the requested size is greater than the limits
                  specified.
                description: Error message
            image/png:
              schema:
                type: string
                default: >-
                  The image resource specified by identifier does not exist, the
                  value of one or more of the parameters is not supported for
                  this image, or the requested size is greater than the limits
                  specified.
                description: Error message
            image/gif:
              schema:
                type: string
                default: >-
                  The image resource specified by identifier does not exist, the
                  value of one or more of the parameters is not supported for
                  this image, or the requested size is greater than the limits
                  specified.
                description: Error message
            image/webp:
              schema:
                type: string
                default: >-
                  The image resource specified by identifier does not exist, the
                  value of one or more of the parameters is not supported for
                  this image, or the requested size is greater than the limits
                  specified.
                description: Error message
        '500':
          description: ''
          content:
            image/jpeg:
              schema:
                type: string
                default: >-
                  The server encountered an unexpected error that prevented it
                  from fulfilling the request.
                description: Error message
            image/png:
              schema:
                type: string
                default: >-
                  The server encountered an unexpected error that prevented it
                  from fulfilling the request.
                description: Error message
            image/gif:
              schema:
                type: string
                default: >-
                  The server encountered an unexpected error that prevented it
                  from fulfilling the request.
                description: Error message
            image/webp:
              schema:
                type: string
                default: >-
                  The server encountered an unexpected error that prevented it
                  from fulfilling the request.
                description: Error message
        '503':
          description: ''
          content:
            image/jpeg:
              schema:
                type: string
                default: >-
                  The server is busy/temporarily unavailable due to
                  load/maintenance issues.
                description: Error message
            image/png:
              schema:
                type: string
                default: >-
                  The server is busy/temporarily unavailable due to
                  load/maintenance issues.
                description: Error message
            image/gif:
              schema:
                type: string
                default: >-
                  The server is busy/temporarily unavailable due to
                  load/maintenance issues.
                description: Error message
            image/webp:
              schema:
                type: string
                default: >-
                  The server is busy/temporarily unavailable due to
                  load/maintenance issues.
                description: Error message
      parameters:
        - name: identifier
          in: path
          description: >-
            The identifier of the requested image. This may be an ark, URN,
            filename, or other identifier. Special characters must be URI
            encoded.
          required: true
          schema:
            type: string
        - name: region
          in: path
          description: >-
            The region parameter defines the rectangular portion of the full
            image to be returned. Region can be specified by pixel coordinates
            `x,y,w,h`, percentage `pct:x,y,w,h` or by the values `full` or
            `square`.
          required: true
          schema:
            type: string
            pattern: ^full|square|\d,\d,\d,\d|pct:\d,\d,\d,\d$
        - name: size
          in: path
          description: >-
            The size parameter determines the dimensions to which the extracted
            region is to be scaled. Size can be specified by pixel coordinates
            `w,h` or `w,` or `,h`, percentage `pct:n` or by the value `full` to
            return the image at its full size.
          required: true
          schema:
            type: string
            pattern: ^full|\d*,\d*|pct:\d+$
        - name: rotation
          in: path
          description: >-
            The rotation parameter specifies mirroring and rotation. Rotation
            can be specified by any floating point number from 0 to 360. A
            leading exclamation mark indicates that the image should be mirrored
            before any rotation is applied.
          required: true
          schema:
            type: string
            pattern: ^!?\d+\.?\d*$
        - name: quality
          in: path
          description: >-
            The quality parameter determines whether the image is delivered in
            color, grayscale or black and white.
          required: true
          schema:
            type: string
            enum:
              - default
              - color
              - gray
              - bitonal
        - name: format
          in: path
          description: >-
            The format of the returned image is expressed as an extension at the
            end of the URI.
          required: true
          schema:
            type: string
            enum:
              - jpg
              - png
              - gif
              - webp
      operationId: get-image
    parameters: []
  /image/{identifier}/info.json:
    get:
      operationId: get-image-info
      summary: Image Information
      description: >-
        Request information about the image, including characteristics,
        functionality available, and related services.
      tags:
        - IIIF Image API
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Image'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: string
                default: The image resource specified by identifier does not exist.
                description: Error message
            application/ld+json:
              schema:
                type: string
                default: The image resource specified by identifier does not exist.
                description: Error message
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: string
                description: Error message
                default: >-
                  The server encountered an unexpected error that prevented it
                  from fulfilling the request.
            application/ld+json:
              schema:
                type: string
                description: Error message
                default: >-
                  The server encountered an unexpected error that prevented it
                  from fulfilling the request.
        '503':
          description: ''
          content:
            application/json:
              schema:
                type: string
                description: Error message
                default: >-
                  The server is busy/temporarily unavailable due to
                  load/maintenance issues.
            application/ld+json:
              schema:
                type: string
                description: Error message
                default: >-
                  The server is busy/temporarily unavailable due to
                  load/maintenance issues.
      parameters:
        - name: identifier
          in: path
          description: >-
            The identifier of the requested image. This may be an ark, URN,
            filename, or other identifier. Special characters must be URI
            encoded.
          required: true
          schema:
            type: string
  /search/{identifier}/search:
    get:
      summary: Search
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationList'
      operationId: get-search
      description: >-
        The search service takes a query, including typically a search term or
        URI, and potentially filtering further by other properties including the
        date the annotation was created or last modified, the motivation for the
        annotation, or the user that created the annotation.
      tags:
        - IIIF Content Search API
      parameters:
        - schema:
            type: string
          in: query
          name: q
          description: >-
            A space separated list of search terms. The search terms may be
            either words (to search for within textual bodies) or URIs (to
            search identities of annotation body resources). The semantics of
            multiple, space separated terms is server implementation dependent.
        - schema:
            type: string
            enum:
              - painting
              - non-painting
              - commenting
              - describing
              - tagging
              - linking
          in: query
          name: motivation
          description: >-
            A space separated list of motivation terms. If multiple motivations
            are supplied, an annotation matches the search if any of the
            motivations are present.
        - schema:
            type: string
            format: date-time
          in: query
          name: date
          description: >-
            A space separated list of date ranges. An annotation matches if the
            date on which it was created falls within any of the supplied date
            ranges. The dates must be supplied in the ISO8601 format:
            YYYY-MM-DDThh:mm:ssZ/YYYY-MM-DDThh:mm:ssZ. The dates must be
            expressed in UTC and must be given in the Z based format.
        - schema:
            type: string
          in: query
          name: user
          description: >-
            A space separated list of URIs that are the identities of users. If
            multiple users are supplied, an annotation matches the search if any
            of the users created the annotation.
    parameters:
      - schema:
          type: string
        name: identifier
        in: path
        required: true
        description: The identifier of the resource being searched.
  /search/{identifier}/autocomplete:
    get:
      summary: Autocomplete
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TermList'
      operationId: get-autocomplete
      description: >-
        The autocomplete service returns terms that can be added into the q
        parameter of the related search service, given the first characters of
        the term.
      tags:
        - IIIF Content Search API
      parameters:
        - schema:
            type: integer
            default: 1
          in: query
          name: min
          description: >-
            The minimum number of occurrences for a term in the index in order
            for it to appear within the response.
    parameters:
      - schema:
          type: string
        name: identifier
        in: path
        required: true
        description: The identifier of the resource being searched.
components:
  schemas:
    Image:
      title: Image
      type: object
      description: >-
        Technical properties about an image. May also contain rights and
        licensing properties, and services related to the image.
      properties:
        '@id':
          type: string
          format: uri
          description: The base URI of the image.
        protocol:
          type: string
          enum:
            - http://iiif.io/api/image
          format: uri
          description: >-
            The URI which can be used to determine that the document describes
            an image service which is a version of the IIIF Image API.
        width:
          type: integer
          description: The width in pixels of the full image content, given as an integer.
        height:
          type: integer
          description: The height in pixels of the full image content, given as an integer.
        profile:
          description: >-
            A list of profiles, indicated by either a URI or an object
            describing the features supported. The first entry in the list must
            be a compliance level URI.
          type: array
          items:
            oneOf:
              - type: string
                enum:
                  - http://iiif.io/api/image/2/level2.json
                format: uri
              - type: object
                properties:
                  supports:
                    type: array
                    description: The set of features supported for the image.
                    items:
                      type: string
                      enum:
                        - canonicalLinkHeader
                        - profileLinkHeader
                        - mirroring
                        - rotationArbitrary
                        - regionSquare
                        - sizeAboveFull
                  qualities:
                    type: array
                    description: >-
                      The set of image quality parameter values available for
                      the image.
                    items:
                      type: string
                      enum:
                        - default
                        - color
                        - gray
                        - bitonal
                  formats:
                    type: array
                    description: >-
                      The set of image format parameter values available for the
                      image.
                    items:
                      type: string
                      enum:
                        - jpg
                        - png
                        - gif
                        - webp
      required:
        - '@id'
        - protocol
        - width
        - height
        - profile
      x-tags:
        - Models
    TermList:
      title: TermList
      type: object
      description: >-
        A list of simple objects that include the term, a link to the search for
        that term, and the number of matches that search will have. The number
        of terms provided in the list is determined by the server.
      properties:
        id:
          type: string
        type:
          type: string
        ignored:
          type: string
        terms:
          type: array
          items:
            $ref: '#/components/schemas/Term'
    Term:
      title: Term
      type: object
      properties:
        match:
          type: string
          description: The matching term.
        url:
          type: string
          format: uri
          description: The link to the search to perform.
        count:
          type: integer
          description: The number of matches for the term.
          minimum: 1
        label:
          type: string
          description: A label to display instead of the match.
      required:
        - match
        - url
    AnnotationList:
      title: AnnotationList
      type: object
      properties:
        id:
          type: string