openapi: 3.1.0
info:
  title: Science Museum Group Collection Documents API
  description: 'A JSONAPI-compliant REST API providing open access to the Science Museum Group''s collection of over 7 million objects, people, and documents across five UK museums: the Science Museum (London), the Science and Industry Museum (Manchester), the National Railway Museum (York), the National Science and Media Museum (Bradford), and Locomotion (Shildon). The API supports full-text search, filtering, and individual record retrieval with rich metadata, image references, and curatorial annotations.'
  version: 1.0.0
  contact:
    name: Science Museum Group Collections
    url: https://www.sciencemuseumgroup.org.uk/our-work/our-collection/using-our-collection-api
  license:
    name: Open Government License
    url: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
servers:
- url: https://collection.sciencemuseumgroup.org.uk
  description: Science Museum Group Collection API
tags:
- name: Documents
  description: Documents, archives, and written records in the collection
paths:
  /search/documents:
    get:
      operationId: searchDocuments
      summary: Search Collection Documents
      description: Search for documents, archives, and written records in the Science Museum Group collection. Supports filtering by makers, associated people, and archive reference.
      tags:
      - Documents
      parameters:
      - name: q
        in: query
        description: Full-text search query term
        required: false
        schema:
          type: string
      - name: makers
        in: query
        description: Filter by document creator or maker
        required: false
        schema:
          type: string
      - name: people
        in: query
        description: Filter by associated person
        required: false
        schema:
          type: string
      - name: archive
        in: query
        description: Filter by archive reference
        required: false
        schema:
          type: string
      - name: places
        in: query
        description: Filter by geographical association
        required: false
        schema:
          type: string
      - name: date[from]
        in: query
        description: Filter from date
        required: false
        schema:
          type: string
      - name: date[to]
        in: query
        description: Filter to date
        required: false
        schema:
          type: string
      - name: images
        in: query
        description: Filter to documents with available images
        required: false
        schema:
          type: boolean
      - name: page[number]
        in: query
        description: Zero-indexed page number
        required: false
        schema:
          type: integer
          default: 0
      - name: page[size]
        in: query
        description: Results per page (max 100)
        required: false
        schema:
          type: integer
          maximum: 100
          default: 50
      responses:
        '200':
          description: Successful document search response
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/DocumentSearchResponse'
  /documents/{id}:
    get:
      operationId: getDocument
      summary: Get Collection Document
      description: Retrieve a single document record by its unique identifier. Returns the full JSONAPI resource record including document metadata, image references, archive location, and relationships to people and objects.
      tags:
      - Documents
      parameters:
      - name: id
        in: path
        description: Unique document identifier
        required: true
        schema:
          type: string
        example: cd23456
      responses:
        '200':
          description: Successful document retrieval
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '404':
          description: Document not found
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CollectionResource:
      type: object
      description: A JSONAPI resource item in the collection
      properties:
        id:
          type: string
          description: Unique resource identifier
        type:
          type: string
          enum:
          - objects
          - people
          - documents
          description: Resource type
        attributes:
          type: object
          description: Resource attributes and metadata
          properties:
            name:
              type: object
              description: Name information with primary and alternate names
            summary:
              type: string
              description: Brief summary of the item
            description:
              type: string
              description: Detailed description
            date:
              type: object
              description: Date information including earliest and latest dates
            images:
              type: object
              description: Image references and media information
            museums:
              type: array
              description: Museums where the item is held
              items:
                type: string
            on_display:
              type: boolean
              description: Whether the item is currently on public display
            location:
              type: object
              description: Gallery or storage location information
        relationships:
          type: object
          description: Related resources
          properties:
            makers:
              type: object
              description: People or organizations who made or created the item
            people:
              type: object
              description: People associated with this item
            documents:
              type: object
              description: Related documents
        links:
          type: object
          properties:
            self:
              type: string
              format: uri
              description: Canonical URL for this resource
    ErrorResponse:
      type: object
      description: JSONAPI error response
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
                description: HTTP status code
              title:
                type: string
                description: Error title
              detail:
                type: string
                description: Error detail message
    DocumentSearchResponse:
      type: object
      description: JSONAPI search response for collection documents
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CollectionResource'
        meta:
          type: object
          properties:
            total:
              type: integer
              description: Total number of matching documents
        links:
          $ref: '#/components/schemas/PaginationLinks'
    PaginationLinks:
      type: object
      description: JSONAPI pagination links
      properties:
        first:
          type: string
          format: uri
          description: Link to the first page
        last:
          type: string
          format: uri
          description: Link to the last page
        prev:
          type: string
          format: uri
          nullable: true
          description: Link to the previous page
        next:
          type: string
          format: uri
          nullable: true
          description: Link to the next page
    DocumentResponse:
      type: object
      description: JSONAPI response for a single document record
      properties:
        data:
          $ref: '#/components/schemas/CollectionResource'