openapi: 3.1.0
info:
  title: Science Museum Group Collection Documents Objects 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: Objects
  description: Scientific instruments, industrial artifacts, and cultural items in the collection
paths:
  /search/objects:
    get:
      operationId: searchObjects
      summary: Search Collection Objects
      description: Search for physical objects and artifacts in the Science Museum Group collection. Supports filtering by object type, makers, people, categories, museum branch, on-display status, and location.
      tags:
      - Objects
      parameters:
      - name: q
        in: query
        description: Full-text search query term
        required: false
        schema:
          type: string
      - name: type
        in: query
        description: Filter by object type
        required: false
        schema:
          type: string
      - name: makers
        in: query
        description: Filter by maker or manufacturer name
        required: false
        schema:
          type: string
      - name: people
        in: query
        description: Filter by associated person
        required: false
        schema:
          type: string
      - name: categories
        in: query
        description: Filter by collection category
        required: false
        schema:
          type: string
      - name: museum
        in: query
        description: Filter by museum code (NRM, SMG, NMeM, MSI)
        required: false
        schema:
          type: string
          enum:
          - NRM
          - SMG
          - NMeM
          - MSI
      - name: on_display
        in: query
        description: Filter to objects currently on display
        required: false
        schema:
          type: boolean
      - name: location
        in: query
        description: Filter by gallery or storage location
        required: false
        schema:
          type: string
      - name: images
        in: query
        description: Filter to objects with available images
        required: false
        schema:
          type: boolean
      - 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: 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 object search response
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ObjectSearchResponse'
  /objects/{id}:
    get:
      operationId: getObject
      summary: Get Collection Object
      description: Retrieve a single collection object by its unique identifier. Returns the full JSONAPI resource record including all metadata, image references, relationships to people and documents, and curatorial notes.
      tags:
      - Objects
      parameters:
      - name: id
        in: path
        description: Unique collection object identifier (e.g., co26704)
        required: true
        schema:
          type: string
        example: co26704
      responses:
        '200':
          description: Successful object retrieval
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ObjectResponse'
        '404':
          description: Object not found
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ObjectResponse:
      type: object
      description: JSONAPI response for a single collection object
      properties:
        data:
          $ref: '#/components/schemas/CollectionResource'
    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
    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
    ObjectSearchResponse:
      type: object
      description: JSONAPI search response for collection objects
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CollectionResource'
        meta:
          type: object
          properties:
            total:
              type: integer
              description: Total number of matching objects
        links:
          $ref: '#/components/schemas/PaginationLinks'